1. 项目概述为什么Android 9.0的HTTP配置成了“必看”如果你是从Android 8.0API 26时代一路开发过来的老手可能还记得当初为了兼容HTTP明文流量在res/xml目录下新建一个network_security_config.xml文件然后简单配置一下domain-config的日子。那时候这更像是一个可选的“加分项”为了绕过Android P的默认限制让应用能继续访问那些还没来得及升级HTTPS的后端接口或测试服务器。但到了Android 9.0API 28情况发生了根本性的变化。谷歌将网络安全配置从一个“建议”提升到了“强制”的层面特别是对于新上架的应用和目标API级别targetSdkVersion为28及以上的应用。这意味着如果你不正确地处理HTTP访问你的应用轻则无法连接到开发环境或内网服务重则直接在上架审核阶段被拒或者在用户设备上出现莫名其妙的网络连接失败。这个变化的核心驱动力是谷歌推动整个移动互联网生态向更安全的HTTPS迁移的决心。从Android 9开始默认情况下应用对所有未明确声明的域名发起的HTTP明文请求都会被系统阻止。这听起来很绝对但谷歌也留了“后门”那就是network_security_config网络安全配置文件。这个文件成了连接你的应用与外部网络世界的“安全通行证”和“规则手册”。它不仅仅是为了“放行”HTTP更重要的是它允许开发者精细地定义应用应该信任哪些证书、哪些连接是安全的、以及在特定场景下如调试、内网可以放宽哪些安全规则。所以当我们在说“Android 9.0开发必看如何安全配置HTTP访问”时我们讨论的远不止是加几行XML代码让应用“能联网”。我们讨论的是如何在保障用户数据安全的大前提下灵活地适配复杂的真实开发与部署环境。这包括了本地调试时连接localhost或10.0.2.2模拟器访问主机、连接企业内网尚未部署SSL证书的服务、集成第三方SDK时其服务仍在使用HTTP、甚至是处理用户自定义URL等边缘场景。一个配置不当的network_security_config可能会引入严重的安全漏洞比如中间人攻击MITM也可能导致功能性的崩溃。因此理解并安全地配置它是现代Android开发者的一项核心技能。2. 核心需求解析我们到底要解决什么问题在深入代码之前我们必须先厘清在Android 9.0环境下配置HTTP访问究竟要应对哪些具体、常见的需求场景。盲目地为了“能用”而配置一个全开放的策略是极其危险的做法。2.1 场景一开发与调试环境这是最常见也最刚需的场景。在开发阶段我们的后端服务很可能运行在本机的localhost:8080或局域网内的某个IP地址上。这些服务通常没有、也不需要配置正式的HTTPS证书。本地服务器Android应用尤其是在模拟器中需要访问主机host上运行的服务。模拟器将10.0.2.2映射为主机的环回地址。内网测试服务器团队内部搭建的测试环境域名可能是内部的如test-api.company.local使用的也可能是自签名的证书。需求本质需要允许应用信任特定的、非公开受信任的证书颁发机构CA颁发的证书或者直接允许向这些特定的域名/IP发起明文HTTP连接。2.2 场景二遗留系统与第三方服务集成现实世界不是纯净的绿洲。很多企业存在历史遗留的系统或者你集成的某个第三方SDK、广告联盟其服务端点可能仍然在使用HTTP。内部老旧系统一些企业内部系统由于历史原因或更新成本短期内无法升级到HTTPS。第三方HTTP服务某些服务提供商可能仍未全面转向HTTPS尽管这越来越少见且不被推荐。需求本质需要为特定的、已知的域名配置例外规则允许HTTP流量但同时要评估和隔离其安全风险避免将不安全的规则应用到整个应用。2.3 场景三用户自定义内容与高级配置对于一些工具类或浏览器性质的应用可能需要处理用户输入的任意URL。自定义主页/书签用户可能设置一个HTTP开头的网址作为主页。内嵌WebView加载非HTTPS内容虽然Google Play对WebView加载非HTTPS内容有严格限制但在某些特定发行渠道的应用中可能仍有此需求。需求本质需要更全局的、但依然可控的放宽策略。注意Google Play政策通常禁止普通应用随意放宽此限制。2.4 场景四增强安全性反向使用network_security_config的强大之处不仅在于“放宽”限制更在于“收紧”策略。证书固定为了防止由设备或网络中间人持有的、看似合法的CA证书发起的攻击可以将应用的服务端证书公钥哈希值“固定”在应用中。这样即使攻击者拥有一个被系统信任的CA签发的伪造证书连接也会被拒绝。自定义信任锚只信任自己指定的CA证书例如企业内部的根证书完全忽略系统预装的CA列表。这对于金融、政务等高安全需求的应用至关重要。需求本质超越系统默认的安全策略实施应用专属的、更严格的安全标准。3. network_security_config详解从文件结构到每个标签理解了需求我们来看工具。network_security_config是一个XML格式的配置文件它必须放置在res/xml/目录下并在AndroidManifest.xml的application标签中通过android:networkSecurityConfig属性引用。3.1 基础文件结构与引用首先在res/xml/如果没有则创建目录下创建文件network_security_config.xml。?xml version1.0 encodingutf-8? network-security-config !-- 在这里配置各种安全策略 -- /network-security-config然后在AndroidManifest.xml中引用它application android:networkSecurityConfigxml/network_security_config ... ... /application3.2 核心标签解析配置文件的核心是几个嵌套的标签它们定义了不同粒度下的安全规则。base-config应用的默认安全配置如果应用没有指定其他配置或者在其他更具体的配置未覆盖的情况下将使用此配置。对于Android 9且targetSdkVersion 28的应用系统默认的base-config就是禁止所有明文HTTP流量。我们通常不需要覆盖整个base-config除非你想为整个应用设置一个自定义的信任锚如只信任自己的CA。domain-config针对特定域名的配置这是最常用、最灵活的标签。它允许你为一系列特定的域名使用cleartextTrafficPermitted属性或子域名通过includeSubdomains属性定义独立的安全规则。规则可以嵌套。debug-overrides仅在调试时生效的覆盖规则这个标签内的规则只在android:debuggabletrue时生效通常是通过debug构建类型或连接调试器时。这是为开发环境配置信任自签名证书或允许明文流量的最佳实践位置可以确保这些不安全的配置不会泄露到生产版本release中。certificates定义信任的证书来源这个标签用在base-config、domain-config或trust-anchors内部用于指定信任哪些证书。srcsystem信任系统预装的CA证书默认。srcuser信任用户安装的CA证书。注意信任用户证书会带来安全风险因为用户可能安装了恶意的中间人证书。仅在必要时如企业设备管理使用并明确告知用户。srcraw/my_ca信任放置在res/raw/目录下的自定义CA证书文件如.cer或.pem格式。3.3 关键属性说明cleartextTrafficPermitted布尔值。是否允许向该配置项所覆盖的域名发起未加密的HTTP请求。true表示允许false表示禁止。includeSubdomains布尔值。该配置是否也适用于指定域名的所有子域名。例如为example.com设置并包含子域名则规则对api.example.com、www.example.com等都生效。4. 实战配置针对不同场景的代码示例理论说再多不如一行代码。下面我们针对第二部分提出的场景给出具体的配置方案。4.1 场景一解决方案安全地允许开发环境HTTP目标允许应用在调试版本中访问localhost、127.0.0.1、10.0.2.2以及内网IP如192.168.1.x的HTTP服务。方案使用debug-overrides标签。这是最安全、最推荐的做法因为它确保了这些配置只存在于你的调试包中。?xml version1.0 encodingutf-8? network-security-config !-- 1. 生产环境/base配置保持默认的严格策略 -- base-config cleartextTrafficPermittedfalse trust-anchors certificates srcsystem / /trust-anchors /base-config !-- 2. 调试环境覆盖仅在debuggabletrue时生效 -- debug-overrides !-- 方案A信任调试用的自签名证书如果后端用了自签名HTTPS -- trust-anchors certificates srcraw/debug_ca / !-- 把自签名CA证书放在res/raw/debug_ca.cer -- certificates srcsystem / /trust-anchors !-- 方案B直接允许向特定域名/IP发送明文HTTP -- domain-config cleartextTrafficPermittedtrue domain includeSubdomainstruelocalhost/domain domain includeSubdomainstrue127.0.0.1/domain domain includeSubdomainstrue10.0.2.2/domain !-- 允许整个私有IP段谨慎使用 -- domain includeSubdomainstrue192.168.1.1/domain domain includeSubdomainstrue192.168.0.1/domain !-- 或者使用通配符不domain标签不支持IP通配符。需要列出具体IP或使用CIDR不原生不支持CIDR。对于动态IP考虑方案C -- /domain-config /debug-overrides /network-security-config注意domain标签不支持IP地址的通配符如192.168.1.*或CIDR表示法。如果你需要覆盖大量内网IP一种折衷办法是配置一个domain-config cleartextTrafficPermittedtrue但不包含任何domain标签这在本配置文件中被视为一个“捕获所有”的规则吗不是的这样配置可能无效或不安全。更安全的做法是如果内网服务有域名即使是hosts文件映射的就使用域名。如果必须用IP可以考虑在代码层面根据构建类型动态决定是否使用HTTP但这超出了配置文件的范畴。实操心得我强烈建议即使在开发环境也尽量为后端服务配置一个自签名证书然后在debug-overrides中通过certificates srcraw/debug_ca /来信任它。这比完全开放明文HTTP更接近生产环境也能让你提前发现一些HTTPS相关的问题如证书验证、TLS版本协商。4.2 场景二解决方案为特定生产域名配置例外目标应用正式版release必须访问一个尚未升级HTTPS的第三方服务http://legacy-service.com。方案使用domain-config为这个特定的域名开启明文流量许可同时保持应用其他所有流量都强制使用HTTPS。?xml version1.0 encodingutf-8? network-security-config !-- 默认配置禁止所有明文流量 -- base-config cleartextTrafficPermittedfalse trust-anchors certificates srcsystem / /trust-anchors /base-config !-- 为特定的遗留服务域名开启明文HTTP -- domain-config cleartextTrafficPermittedtrue domain includeSubdomainstruelegacy-service.com/domain !-- 你可以继续添加其他类似的域名 -- !-- domain includeSubdomainstrueanother-http-site.com/domain -- /domain-config !-- 你甚至可以为一个域名配置更复杂的规则比如证书固定 -- domain-config domain includeSubdomainstruesecure-api.example.com/domain pin-set expiration2024-12-31 !-- 固定证书过期时间可选 -- pin digestSHA-2567HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y/pin !-- 备份Pin用于证书轮换 -- pin digestSHA-256fwza0LRMXouZHRC8Ei4PyuldPDcf3UKgO/04cDM1oE/pin /pin-set trust-anchors certificates srcsystem / /trust-anchors /domain-config /network-security-config关键点domain-config的规则是叠加的且更具体的配置匹配域名会覆盖更通用的配置base-config。这样legacy-service.com可以使用HTTP而其他所有域名如secure-api.example.com仍然强制HTTPS并且我们对安全域名还增加了证书固定。4.3 场景三与四的进阶配置场景三用户自定义内容的警告在base-config中直接设置cleartextTrafficPermittedtrue是极其危险的这会使你的应用所有网络请求包括登录、支付都可能被明文拦截。Google Play政策也明令禁止这种做法除非你的应用是浏览器或具有明确的、用户可知的代理功能。如果确有合理需求并且应用不在Google Play分发配置如下base-config cleartextTrafficPermittedtrue trust-anchors certificates srcsystem / /trust-anchors /base-config场景四增强安全的示例——仅信任自定义CA 假设你的应用只与公司服务器通信且所有证书都由内部CA签发。base-config trust-anchors !-- 不信任系统CA只信任我们自己的CA -- certificates srcraw/my_company_root_ca/ !-- 如果需要可以继续添加其他特定的CA -- !-- certificates srcraw/my_company_intermediate_ca/ -- /trust-anchors /base-config这样配置后应用将不信任任何系统预装的公共CA如DigiCert, Let‘s Encrypt等只信任你内置的CA。这提供了最高级别的证书链控制但也要确保你的CA证书安全且妥善管理轮换。5. 常见问题排查与实战避坑指南即使配置看起来正确在实际开发中你还是会遇到各种网络错误。下面是一些常见问题的排查思路和避坑经验。5.1 问题配置了debug-overrides但调试时依然无法连接HTTP本地服务器。排查步骤确认构建变体你当前运行的是debug构建类型吗检查Android Studio左下角的Build Variants工具窗口确保选中的是debug。确认android:debuggable属性即使使用debug变体也要检查AndroidManifest.xml中的application标签或build.gradle中的配置确保最终APK的该属性为true。现代Android Studio和Gradle默认会正确处理。检查域名/IP是否完全匹配network_security_config对域名的匹配是精确且区分端口的。如果你的服务器运行在http://localhost:8080配置中的domain必须是localhost。注意它不包含协议(http)和端口(:8080)。但如果你在代码中使用的是IP127.0.0.1:8080则必须配置127.0.0.1。检查Logcat搜索CleartextTrafficPermitted或对应的网络错误异常如ERR_CLEARTEXT_NOT_PERMITTED。系统会打印详细的拒绝日志告诉你哪个域名因为违反了哪条安全策略而被阻止。使用adb shell命令验证在连接设备/模拟器后运行以下命令可以导出并查看应用最终的网络安全配置adb shell dumpsys package com.your.package.name | grep -A 50 -B 5 networkSecurityConfig这会显示系统实际解析到的配置有助于确认你的配置文件是否正确加载和应用。5.2 问题在Android 10设备上即使配置了cleartextTrafficPermittedtrue访问某些HTTP站点依然失败。可能原因Android 10API 29引入了一项更严格的规定即使你在网络安全配置中允许了明文流量如果目标服务器响应了一个HTTP的Strict-Transport-Security (HSTS)头Android系统也会强制拒绝连接。HSTS是一个Web安全策略机制告诉浏览器“在未来一段时间内只能通过HTTPS访问我”。Android系统内置了一个预加载的HSTS域名列表包括google.com、github.com等主流站点并且会缓存运行时遇到的HSTS头。解决方案对于测试或内部站点确保你的测试服务器没有发送Strict-Transport-Security响应头。对于用户设备上的已缓存HSTS在开发阶段可以到设备的设置 安全 加密与凭据 清除已保存的HSTS/SSL状态不同厂商路径可能略有差异来清除缓存。注意这会影响设备上所有应用。无法控制服务器如果第三方HTTP站点自己发送了HSTS头那在Android 10上基本无法通过常规HTTP访问。唯一的出路是联系对方升级到HTTPS或者如果你的应用有特殊权限如系统应用可以尝试其他底层网络API但这对于普通应用不可行。5.3 问题证书固定Certificate Pinning配置后服务端证书轮换导致应用无法连接。避坑指南证书固定是一把双刃剑提供了极致安全但也带来了运维复杂性。配置pin-set时请务必遵循以下最佳实践至少设置两个Pin一个对应当前使用的证书叶子证书或中间证书的公钥哈希另一个对应备份证书或即将轮换到的证书的公钥哈希。这样在证书轮换期间新旧证书都能被接受。设置expiration属性这是一个安全阀。例如设置expiration2024-12-31即使你忘记更新App过了这个日期后固定策略会自动失效回退到正常的证书链验证。这可以防止应用因证书过期而“永久瘫痪”。如何计算Pin值Pin值是证书公钥不是整个证书的哈希通常是SHA-256的Base64编码。你可以使用openssl命令获取openssl s_client -connect example.com:443 -servername example.com /dev/null | openssl x509 -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64或者更简单的方法在Chrome浏览器中访问该网站点击地址栏的锁图标 - 连接是安全的 - 证书有效 - 详细信息 - 复制“公钥信息”的SHA-256指纹去掉冒号并进行Base64编码。5.4 问题WebView加载混合内容HTTP within HTTPS或非HTTPS内容失败。说明network_security_config主要影响的是应用层网络请求如HttpURLConnection,OkHttp,Retrofit。对于WebView它有自己的安全设置。Android 5.0默认禁止HTTPS页面加载HTTP资源混合内容。你需要通过WebSettings.setMixedContentMode()来允许。Android 8.0WebView也开始遵循应用的网络安全配置。但为了允许WebView加载非HTTPS首页你通常仍然需要在network_security_config中为对应域名配置cleartextTrafficPermittedtrue。Google Play政策对于通过Google Play分发的应用WebView加载非HTTPS页面受到严格限制需要充分的理由并通过审核。WebView相关配置示例代码中val webView findViewByIdWebView(R.id.webview) val settings webView.settings // 允许HTTPS页面加载HTTP资源混合内容- 谨慎使用 settings.mixedContentMode WebSettings.MIXED_CONTENT_ALWAYS_ALLOW // 注意这需要配合网络安全配置中对相应域名的明文允许。6. 工具与测试如何验证你的配置是正确且安全的写完配置不是终点验证它同样重要。6.1 使用Android Studio的Network Security Config Inspector这是一个内置的检查工具。在Android Studio中打开你的network_security_config.xml文件编辑器右侧可能会有一个“Design”标签页或者你可以通过Analyze Inspect Code来运行检查。它能帮你发现一些常见的配置错误比如无效的标签嵌套、属性值错误等。6.2 使用nsc命令行工具Android SDK中提供了一个强大的命令行工具nsc$ANDROID_HOME/tools/bin/nsc它可以详细解析和验证你的配置文件。$ANDROID_HOME/tools/bin/nsc verify --config res/xml/network_security_config.xml它会输出配置的详细树状结构并指出潜在问题。6.3 进行主动安全测试测试明文流量阻止在配置为禁止明文的地方故意发起一个HTTP请求确认请求被系统阻止并收到CleartextTrafficPermitted异常。测试证书固定尝试用一个由合法公共CA签发、但公钥不匹配的证书例如用另一台服务器的证书来模拟中间人攻击确认连接失败。对比Debug与Release包使用apktool或检查adb shell dumpsys的输出确保debug-overrides中的内容没有被打包到release版本的APK中。这是防止安全配置泄露的关键一步。6.4 监控与日志在开发过程中密切关注Logcat中与网络安全相关的日志。系统会打印D/NetworkSecurityConfig相关的信息告诉你当前应用使用了哪个配置以及处理每个网络请求时应用了哪些规则。这是最直接的调试信息。配置network_security_config是一个在安全与兼容性之间寻找平衡点的过程。没有一劳永逸的“万能配置”最好的策略永远是为生产环境配置最严格的安全策略默认禁用明文使用证书固定为调试环境配置最小化的、临时的例外规则并且对任何允许明文流量的域名保持警惕和明确的记录。随着后端服务的全面HTTPS化这些例外配置应该逐渐减少直至消除。理解每一个标签和属性背后的安全含义才能让你的应用在日益严峻的网络环境中既保持功能正常又守护好用户的数据安全。