1. 项目概述一次安卓开发中的URI解析报错1.1 问题出现的场景与表象这是安卓开发中一个特别典型的一眼懵错误。项目跑着跑着某个网络请求或者图片加载突然崩了Logcat刷出一行刺眼的红字java.lang.IllegalArgumentException: invalid URI scheme localhost。很多朋友第一次看到这个报错时第一反应是我这代码里哪有什么URI啊——但这个报错的含义非常明确代码里某个地方把localhost:8080/xxx这类字符串当成了URI去解析然后解析失败。具体来说这个报错由Android系统自带的java.net.URI类或okhttp3.HttpUrl类在解析URL时抛出。当我们调用new URI(String)或者URI.create(String)时如果传入的字符串没有合法的scheme协议头系统就会直接抛出IllegalArgumentException。而报错信息里明确写了invalid URI scheme localhost说明代码传进来的字符串是localhost:xxxx这样的格式系统把localhost当成了scheme去校验结果发现它压根不是一个合法的协议头。真正让人头疼的是这个报错不会在开发阶段立刻暴露往往是在联调接口、换测试环境服务器地址、或者接手别人代码时突然爆发。我在实际排查中遇到的场景大概有三类一是后端同学给的接口文档里直接写localhost:8080/api/login这样的地址前端拿到后没加http://前缀就丢给网络框架二是项目里有个配置项从服务端下发baseUrl结果服务端配置漏了协议头三是开发者在拼接图片地址或者WebView加载地址时写成了webView.loadUrl(localhost:8080/test.html)。1.2 这个报错的核心影响范围很多开发者觉得这个报错改一下加上http://不就好了但实际上它涉及的面挺广首先它会影响所有基于HTTP的请求场景——OkHttp、Retrofit、Glide、WebView都逃不开URL解析这一步其次它还牵扯到Android系统的一个安全机制——从Android 9API 28开始系统默认禁止明文HTTP流量如果你在本地调试时用的地址是http://localhost除了要处理scheme问题还得在Manifest里配置usesCleartextTraffic或者网络安全配置。这意味着一个简单的地址格式问题可能同时踩中格式校验和网络安全策略两个坑。这篇文章我会从URI解析的原理讲起完整复盘这个问题的根因、常见写法错误、修复方案再顺带聊聊另一类更隐蔽的报错invalid token image/jpeg——它发生在Retrofit配合OkHttp上传图片的场景里本质和URL解析不是一个问题但报错格式非常相似经常被人放到一起搜我会一并说明。1.3 适合哪些开发者参考如果你正在用Retrofit、OkHttp、Glide或者WebView开发App或者你维护的项目里有动态下发的网络地址配置这篇文章建议收藏。我下面会贴出能直接运行的修复代码、详细的排查思路以及我自己在项目里踩过的几个很隐蔽的坑。2. 为什么会出现invalid URI scheme从Java URI解析机制说起2.1 URI的Scheme到底是什么要理解这个报错必须先搞清楚URIUniform Resource Identifier统一资源标识符的基本结构。一个标准的URI长这样scheme://authority/path?query#fragment其中scheme就是协议头比如http、https、ftp、content、file都是合法的scheme。Java的java.net.URI类在解析字符串时会先取第一个:之前的部分当作scheme来校验。如果字符串里压根没有:或者:前面的内容不符合scheme的命名规则比如包含了空格、中文、特殊字符、或者以数字开头就会抛URISyntaxException或者IllegalArgumentException。但invalid URI scheme localhost这个报错有个特别之处localhost:8080这个字符串里是有冒号的localhost是冒号前面的部分按道理URI会把它当成scheme处理。问题恰恰在于localhost不是一个合法的scheme——合法的scheme必须以字母开头后面只能跟字母、数字、、-、.而且通常有注册意义。Java的URI实现内部用了一个isLetter校验localhost虽然是合法字母组合但它在系统层面没有被注册为合法协议所以直接抛异常。我用一个简单的例子来说明// 这段代码会抛 IllegalArgumentException: invalid URI scheme localhost URI uri URI.create(localhost:8080/api/login); // 这段代码可以正常运行 URI uri2 URI.create(http://localhost:8080/api/login);第一行代码的报错信息就是你看到的java.lang.IllegalArgumentException: invalid URI scheme localhost。注意这里抛的是IllegalArgumentException而不是URISyntaxException原因在于URI.create(String)方法内部会捕获URISyntaxException并重新包装成IllegalArgumentException——这个设计初衷是让调用方不需要处理受检异常但也导致很多人看到报错后不知道去哪里查根因。2.2 为什么localhost会被当成scheme而不是host很多开发者会疑惑我写localhost:8080localhost明显是主机名啊为什么Java不把它当作host原因很简单URI解析器只有在看到://时才会进入authority主机部分解析状态。如果你写的是localhost:8080解析器看到的状态是读取到localhost当作scheme候选读取到:确认前面有内容当作scheme分隔符校验localhost是否合法scheme发现不合法直接抛异常而如果你写的是localhost://8080解析器会认为scheme是localhost8080是authority开头的一个路径片段——这仍然不是你想要的。换句话说想让localhost被识别为主机名必须提供完整的scheme://host:port结构。缺少了//解析器根本不会进入主机解析逻辑。这也是为什么修复方式不是把localhost改成别的而是给地址补上http://前缀。顺着这个思路往下走你就能理解另一个细节为什么有些代码里写10.0.2.2:8080也会报一样的错因为10.0.2.2:8080同样没有scheme前缀解析器会把10.0.2.2当成scheme候选但scheme不能以数字开头于是抛URISyntaxException。两种报错同源不同表现本质都是缺少协议头。2.3 OkHttp和Retrofit对URL的隐藏要求这里要特别提醒一点如果你用的是OkHttp或者Retrofit它们的URL解析逻辑和Java自带的URI还不完全一样。OkHttp用的是内部封装的HttpUrl解析器在校验scheme时比Java更严格——它只接受http和https两种scheme。所以你传入ftp://localhost:8080这种地址时Java的URI可能不报错但OkHttp会直接抛IllegalArgumentException: Expected URL scheme http or https but was ftp。我在实际项目中遇到过一种诡异场景代码里明明给地址加了http://前缀但启动时仍然报invalid URI scheme localhost。最后定位发现是Retrofit的baseUrl()方法要求必须以/结尾而动态拼接的接口地址被直接拼在了baseUrl后面形成http://localhost:8080加一个不带斜杠的路径绕了一圈又触发了OkHttp的URL重组逻辑最终报错信息还是跟scheme有关。2.4 Android网络安全策略对localhost的额外限制说完了scheme本身的问题还得提一句Android 9之后的高版本网络限制。很多开发者修好scheme问题后发现请求还是失败报CLEARTEXT communication to localhost not permitted by network security policy。这是因为Android默认禁止明文HTTP流量即使你连接的是localhost也不例外。区别在于如果你用的是模拟器10.0.2.2指向宿主机localhost指向模拟器自身——如果你在模拟器里访问http://localhost:8080等于访问模拟器自己通常没有服务在监听而访问http://10.0.2.2:8080才是宿主机上的服务。这个混用问题在开发阶段极其常见我见过不少人把这两个地址弄混然后怀疑是不是自己的修复方式有问题。如果你确实需要在开发阶段访问本地HTTP服务推荐用网络安全配置的方式单独对某个域名放开明文流量而不是全局开启usesCleartextTraffic。具体配置方法我在后面实操环节会给出来。3. 完整修复实操从改地址到防患于未然3.1 场景一硬编码地址缺少scheme最直接的修复就是给所有URL字符串补上http://或https://前缀。但这里有个隐藏的技巧不要直接手拼字符串用HttpUrl的构建器或者统一的工具类去处理可以避免后续各种格式问题。我推荐用一个简单的UrlUtils工具类来规范化地址import okhttp3.HttpUrl; public class UrlUtils { /** * 规范化URL自动补全缺失的scheme * 输入: localhost:8080/api/login - 输出: http://localhost:8080/api/login * 输入: 10.0.2.2:8080/api - 输出: http://10.0.2.2:8080/api * 输入: https://example.com/api - 输出: https://example.com/api */ public static String normalizeUrl(String rawUrl) { if (rawUrl null || rawUrl.trim().isEmpty()) { throw new IllegalArgumentException(URL不能为空); } String trimmed rawUrl.trim(); if (!trimmed.startsWith(http://) !trimmed.startsWith(https://)) { trimmed http:// trimmed; } // 用HttpUrl解析验证能提前暴露格式问题 HttpUrl parsed HttpUrl.parse(trimmed); if (parsed null) { throw new IllegalArgumentException(URL格式非法: rawUrl); } return parsed.toString(); } }这个工具类的核心逻辑很简单先检查前缀没有就补上http://然后用OkHttp的HttpUrl做一次解析校验。HttpUrl.parse()比Java的URI.create()更严格也更适合网络库场景它能提前发现端口号非法、host包含非法字符、路径格式不对等问题。在Retrofit里你可以这样使用public class ApiClient { private static final String BASE_URL UrlUtils.normalizeUrl(localhost:8080); public static ApiService getApiService() { OkHttpClient client new OkHttpClient.Builder() .connectTimeout(15, TimeUnit.SECONDS) .readTimeout(15, TimeUnit.SECONDS) .build(); Retrofit retrofit new Retrofit.Builder() .baseUrl(BASE_URL) .client(client) .addConverterFactory(GsonConverterFactory.create()) .build(); return retrofit.create(ApiService.class); } }注意Retrofit的baseUrl必须以/结尾否则运行时会抛IllegalArgumentException: baseUrl must end in /。如果你通过normalizeUrl方法处理后的地址末尾没有斜杠建议再补一个工具方法确保以/结尾或者直接约定BASE_URL常量手动写成http://localhost:8080/。3.2 场景二WebView加载本地测试地址如果你遇到的是WebView场景比如加载本地调试页面// 错误写法 webView.loadUrl(localhost:8080/test.html); // 正确写法 webView.loadUrl(http://localhost:8080/test.html);但注意WebView还有一个坑如果你加载的是http://地址而页面里有https://的资源引用Android的混合内容策略会拦掉部分请求。调试本地页面时建议直接使用http://10.0.2.2:8080访问宿主机服务模拟器场景同时设置WebView的混合内容模式if (Build.VERSION.SDK_INT Build.VERSION_CODES.LOLLIPOP) { webView.getSettings().setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW); }3.3 场景三服务端动态下发的BaseUrl这是最隐蔽的一类问题。我遇到过项目里有个ConfigManager从服务端拉配置返回的base_url字段在后台配置时被误填成192.168.1.100:8080——少了http://。这个值在字符串拼接阶段不会报错只有请求真正发起时才会炸而且因为配置是运行时下发的本地复现很困难。对这种场景我的建议是在后端返回配置的映射层就统一走一遍normalizeUrl逻辑在本地维护一份兜底配置当远程配置解析失败时自动使用本地默认值增加配置合法性校验解析失败直接上报日志而不是让用户用到坏配置public class ConfigManager { private String baseUrl http://10.0.2.2:8080/; // 默认值 public void updateRemoteConfig(RemoteConfig config) { String rawUrl config.getBaseUrl(); try { this.baseUrl UrlUtils.normalizeUrl(rawUrl); } catch (IllegalArgumentException e) { // 记录日志保留上一次可用配置避免线上崩溃 Log.e(ConfigManager, baseUrl配置非法: rawUrl, e); } } }3.4 本地开发环境网络配置把localhost和明文HTTP彻底打通修好scheme只是第一步。接下来要解决Android 9的网络请求限制。这里我推荐用网络安全配置Network Security Configuration而不是直接在Manifest里开全局usesCleartextTraffic因为后者会把所有域名都放开明文通信上生产环境有安全隐患。在res/xml目录新建network_security_config.xml?xml version1.0 encodingutf-8? network-security-config !-- 只对本地开发域名放开明文流量生产环境不要这样配 -- domain-config cleartextTrafficPermittedtrue domain includeSubdomainstrue10.0.2.2/domain domain includeSubdomainstruelocalhost/domain domain includeSubdomainstrue127.0.0.1/domain /domain-config /network-security-config然后在Manifest的application标签里引用application android:networkSecurityConfigxml/network_security_config ... 这里要特别提一个我踩过的坑网络域名的配置不允许写IP地址带端口。你以为可以写domain10.0.2.2:8080/domain实际上这个配置是解析不了的因为domain标签只匹配域名/IP不匹配端口。端口是跟随URL的协议自动处理的http://10.0.2.2:8080默认就走80端口以外的8080不影响明文策略判断。3.5 参数对比不同修复方案怎么选修复方案适用场景优点缺点硬编码字符串直接补http://一次性修改、地址固定最简单直接几秒钟搞定容易遗漏后续维护成本高封装UrlUtils自动补全多处地方需要拼接URL统一入口能提前校验格式需要团队约定新增开发可能绕过工具类服务端下发本地校验动态配置、运营后台可改灵活性高能快速切换环境需要前后端配合校验逻辑要完备网络安全配置放开明文Android 9本地调试最小化放开流量范围安全可控需要区分debug和release构建我的建议是本地调试用封装UrlUtils 网络安全配置两个方案配合前者保证地址格式正确后者保证请求能发出去。上线前检查一下网络配置文件确保cleartextTrafficPermittedtrue只保留在debug构建的配置里。关于debug和release的区分有一个小技巧在src/debug/res/xml/和src/main/res/xml/各放一份同名配置文件debug那份放开本地明文流量main那份保持严格策略。这样打包release时应用自动会用main目录下的配置不会把开发环境的宽松配置带到线上。4. 排查思路与相似报错辨析invalid token和更多坑4.1 排查这套问题的完整思路如果你遇到的报错不完全是标题里这个而是一些变体我建议按下面的顺序排查第一步看完整堆栈。很多人只看第一行报错就跑去改代码实际上Caused by后面的信息往往直接指向真正的错误位置。比如Caused by: java.net.URISyntaxException: Expected scheme name at index 0: localhost:8080/xxx说明是字符串解析的问题而Caused by: java.net.UnknownHostException说明域名解析失败但地址本身格式没问题。第二步确认URL字符串的最终值。在调用网络请求之前打断点或者加一行Log.d(DEBUG_URL, url)看看实际传给网络库的字符串长什么样。很多时候动态拼接的地址跟你想的完全两样。第三步模拟器还是真机。模拟器的localhost指向模拟器自身10.0.2.2才指向宿主机真机则需要通过adb reverse tcp:8080 tcp:8080把手机的8080端口转发到电脑上然后用http://127.0.0.1:8080访问。这一步错了地址格式再正确也连不上服务。第四步检查网络安全配置。如果地址格式完全正确但请求还是失败看一下Logcat有没有CLEARTEXT communication字样有的话就是明文流量被拦了。4.2 相似报错invalid token image/jpeg其实是另一回事搜这个报错的人越来越多但它的成因和URI scheme完全不是一回事。java.lang.IllegalArgumentException: invalid token image/jpeg出现在Retrofit配合OkHttp做文件上传的场景报错信息之所以相似是因为它们都抛IllegalArgumentException但触发点是MultipartBody构建时的Content-Type解析。我复盘一下这个报错的完整链路——很多朋友用Retrofit上传图片时代码可能长这样Multipart POST(api/upload) CallUploadResponse uploadImage( Part MultipartBody.Part filePart, Part(description) RequestBody description );调用时你自然而然地写RequestBody fileBody RequestBody.create( MediaType.parse(image/jpeg), imageBytes ); MultipartBody.Part filePart MultipartBody.Part.createFormData( file, photo.jpg, fileBody );理论上这么写没问题但你真正遇到invalid token image/jpeg时通常是因为代码里写了MediaType.parse(image/jpeg; charsetUTF-8)或者更离谱的写法MediaType.parse(image/jpeg,image/png) // 多个类型混在一起 MediaType.parse(image/jpeg ) // 结尾多了空格MediaType.parse()内部会对字符串做严格的token校验image/jpeg合法但image/jpeg; charsetUTF-8对它来说合法却不是静态工厂方法能接受的格式。更常见的错误是直接在Part注解里写死了类型比如Part(file) RequestBody fileBody; // 而调用方传入了不规范的类型字符串OkHttp的MultipartBody.Builder在调用addFormDataPart时对每个part的Content-Type都会执行MediaType.parse校验一旦传入的字符串无法解析成合法的MediaType就会抛出IllegalArgumentException: invalid token image/jpeg——报错里的image/jpeg是它从你传入的字符串里截取到第一个非法token时的现场。这类问题的排查思路和URI scheme完全不同检查MediaType.parse()的入参必须形如image/jpeg、application/json不能带空格、分号、逗号或charset检查MultipartBody.Part.createFormData的第三个参数RequestBody.create()的contentType务必是干净的MIME类型检查Part注解里的常量如果注解写的是Part(file; filenametest.jpg)这种非法格式同样会炸我提供一个通用的工具方法private static final MapString, String EXTENSION_TO_MIME new HashMap(); static { EXTENSION_TO_MIME.put(jpg, image/jpeg); EXTENSION_TO_MIME.put(jpeg, image/jpeg); EXTENSION_TO_MIME.put(png, image/png); EXTENSION_TO_MIME.put(webp, image/webp); EXTENSION_TO_MIME.put(gif, image/gif); } public static RequestBody createImageBody(byte[] imageBytes, String fileName) { String extension fileName.substring(fileName.lastIndexOf(.) 1).toLowerCase(); String mimeType EXTENSION_TO_MIME.get(extension); if (mimeType null) { mimeType application/octet-stream; // 兜底避免崩溃 } return RequestBody.create(MediaType.parse(mimeType), imageBytes); }这个工具方法解决了两个问题一是统一管理MIME类型映射避免开发者在调用处随手写错二是对未知扩展名兜底避免因为一个文件类型问题导致整个上传流程崩溃。4.3 常见问题速查表报错信息触发场景根因解决措施invalid URI scheme localhost网络请求地址或WebView地址URL缺少http://或https://前缀使用URL工具类补全schemeExpected URL scheme http or https but was ftpOkHttp请求使用了非HTTP协议改用http://或https://baseUrl must end in /Retrofit初始化baseUrl末尾缺少斜杠统一在常量定义时补/CLEARTEXT communication not permittedAndroid 9请求HTTP地址系统默认禁止明文流量配置网络安全策略对调试域名放开invalid token image/jpegRetrofit上传图片MediaType.parse()入参非法用MIME映射表确保入参格式正确NullPointerException: parameter urlRetrofit请求baseUrl返回null配置解析时做空值兜底这张表基本覆盖了我这几年在项目里遇到过的所有和URL、MediaType相关的崩溃场景。每一条我都踩过每一条的修复方式都不难难在找到报错的第一行时不要慌按类型去归类。4.4 Debug模式下的附加建议最后特别想说一个经验关于localhost在团队协作中的规范问题。我自己维护过一个项目测试环境地址在三个人手里分别是localhost、192.168.1.100、10.0.2.2三个写法每个人跑起来的效果都不一样。后来我统一了规范不同环境的BaseUrl全部走BuildConfig管理// build.gradle buildTypes { debug { buildConfigField String, API_BASE_URL, \http://10.0.2.2:8080/\ } release { buildConfigField String, API_BASE_URL, \https://api.example.com/\ } }禁止在业务代码里拼接完整URL只允许拼路径比如ApiClient.getApiService().login(...)baseUrl永远从BuildConfig.API_BASE_URL获取新增网络地址必须走工具类统一规范化代码评审时看到裸地址直接打回这样做了之后改地址改到崩溃的问题基本绝迹了。毕竟invalid URI scheme localhost这种报错最有效的解法不是出了再修而是从入口上堵住它出现的可能。你可以在自己项目里把地址写错的概率压到最低也可以等真出了事再快速定位到具体是哪个环节丢了协议头这两种能力对一个安卓开发者来说都值得拥有。