1. 从一次“网络请求失败”的调试说起那天下午我正在调试一个即将上线的App新版本。功能很简单就是从服务器拉取一个JSON配置。在Android 9.0API 28的测试机上一切正常数据刷刷地就回来了。但当我切换到一台Android 11API 30的真机上运行时熟悉的网络请求却卡住了日志里只留下一个冷冰冰的java.net.SocketException: socket failed: EPERM (Operation not permitted)。起初我以为是服务器问题但用浏览器访问接口明明好好的。排查了半小时从URL拼接到请求头都没发现问题。直到我猛然想起这个项目的targetSdkVersion前不久刚升级到30。问题很可能就出在这里——Android API 30即Android 11引入了一项重大的网络安全变更它彻底改变了应用访问外部网络的方式而很多开发者包括当时的我对此还毫无准备。如果你也在开发或维护一个Android应用并且你的targetSdkVersion已经或即将升级到30Android 11或更高版本Android 12/13/14那么理解并正确配置网络权限就是你必须跨过的一道坎。这不再是简单的在AndroidManifest.xml里加一行uses-permission android:nameandroid.permission.INTERNET /就能搞定的事情了。从API 30开始Android引入了一套更精细、更安全的网络访问控制模型旨在限制应用对非必要网络资源的访问以提升用户隐私和系统安全。本文将基于我踩坑和解决这个问题的完整过程为你详细拆解Android API 30的网络权限设置涵盖其背后的原理、必须的配置步骤、不同场景下的适配方案以及那些官方文档里不会写的实操细节和避坑指南。2. 核心变更为何 targetSdkVersion 30 成了分水岭在深入配置之前我们必须先理解Android 11API 30到底改变了什么。这个变更的核心在于网络安全性配置和默认网络行为的调整。2.1 废弃了“宽松”的默认网络访问策略在targetSdkVersion低于30时即使你在AndroidManifest.xml中只声明了INTERNET权限你的应用也默认拥有一个“宽松”的网络访问策略。这意味着只要用户授予了网络权限通常是安装时默认授予你的应用就可以自由地访问任何明文HTTP和HTTPS站点。系统对应用发出的网络请求几乎不做额外限制。然而从targetSdkVersion30开始这个默认行为发生了根本性改变。如果你的应用没有显式地定义一个名为network_security_config.xml的网络安全配置文件那么系统会应用一套更严格的默认策略。这套默认策略会阻止你的应用访问大多数非加密HTTP流量并且可能会对HTTPS流量有更严格的证书校验要求。这就是为什么我的应用在API 28上能跑在API 30上却报“Operation not permitted”的根本原因——应用试图发出的网络请求尤其是HTTP请求被系统的新安全策略给拦截了。2.2 引入强制性的网络安全配置为了获得网络访问能力应用现在必须在res/xml/目录下创建一个network_security_config.xml文件并在AndroidManifest.xml的application标签中通过android:networkSecurityConfig属性引用它。这个文件是你向系统声明应用网络访问策略的“白皮书”。你可以在这里定义哪些域名的连接是受信任的通过证书固定。是否允许明文流量HTTP。是否信任用户或系统安装的证书用于调试或特定企业环境。更细粒度的域配置。没有这个文件或者配置不正确网络请求就可能失败。这是Android迈向更严格隐私保护和安全模型的重要一步要求开发者明确声明其应用的网络意图而不是“默认全部允许”。2.3 Cleartext Traffic明文流量策略的变化明文流量即非加密的HTTP流量一直是安全风险点。在API 28Android 9.0时Google就默认禁止了明文流量但允许通过在network_security_config.xml中配置来启用。到了API 30对明文流量的管控更为严格和明确。即使你配置了允许明文流量也需要非常小心地限定范围通常只允许访问特定的域名或IP而不是全局放开。3. 实战配置构建你的 network_security_config.xml理解了“为什么”之后我们来看“怎么做”。下面是一个最基础、最常用的network_security_config.xml配置它能让一个面向公网HTTPS API和少量特定HTTP服务的应用在API 30上正常运行。首先在你的Android项目app/src/main/res/目录下新建一个xml文件夹如果不存在的话然后在该文件夹内创建network_security_config.xml文件。?xml version1.0 encodingutf-8? network-security-config !-- 基础配置信任系统预装的证书 -- base-config cleartextTrafficPermittedfalse trust-anchors certificates srcsystem / /trust-anchors /base-config !-- 针对调试版本的特殊配置信任用户安装的证书方便抓包调试 -- debug-overrides trust-anchors certificates srcuser / /trust-anchors /debug-overrides !-- 域特定配置允许某个特定域名使用HTTP明文流量 -- domain-config cleartextTrafficPermittedtrue domain includeSubdomainstrueinsecure.example.com/domain /domain-config /network-security-config逐段解析与配置逻辑base-config这是应用的默认安全配置。cleartextTrafficPermittedfalse全局禁止明文HTTP流量。这是推荐的安全做法强制应用使用HTTPS。如果你的应用完全使用HTTPS这个配置就足够了。trust-anchors定义受信任的证书颁发机构CA。certificates srcsystem /信任Android系统内置的CA证书。这是必须的否则你的应用将无法验证任何正规CA签发的HTTPS证书比如Let‘s Encrypt、DigiCert等导致所有HTTPS请求失败。debug-overrides这个配置块仅在非发布版本debuggabletrue时生效。它对于开发调试至关重要。当我们使用Charles、Fiddler或mitmproxy等抓包工具时这些工具会充当“中间人”并生成一个自签名的CA证书安装在手机上。默认情况下应用不信任用户安装的证书导致抓包时HTTPS请求会报证书错误。配置certificates srcuser /后在调试版本中应用将信任用户安装的CA证书从而允许抓包工具成功解密和查看HTTPS流量。切记此配置仅应用于调试绝不应出现在发布版本中。domain-config用于对特定域名进行例外配置。这里最常见的用例就是允许某个域名使用明文HTTP。cleartextTrafficPermittedtrue对该域启用明文流量。domain includeSubdomainstrueinsecure.example.com/domain指定域名。includeSubdomainstrue表示该规则也适用于其所有子域名如api.insecure.example.com。使用场景你有一个旧的、尚未升级HTTPS的图片服务器域名或者在内网测试环境中使用HTTP地址。务必谨慎使用并尽可能将域名范围限制到最小。创建好配置文件后你必须在AndroidManifest.xml中引用它application android:name.MyApplication android:iconmipmap/ic_launcher android:labelstring/app_name android:networkSecurityConfigxml/network_security_config ... ... /application注意android:networkSecurityConfig这个属性在较旧的Android Support Library或AndroidX库中可能不被识别。确保你的项目编译版本足够高例如compileSdkVersion 31并且Gradle插件版本较新如7.0。如果IDE报红但编译正常通常可以忽略。4. 高级场景与精细化控制基础配置能解决90%的问题但面对复杂场景我们需要更精细的控制。4.1 证书固定防范中间人攻击的终极手段证书固定是一种高级安全技术它要求应用只信任特定的、预置的服务器证书或公钥哈希而不是系统信任的所有CA。这可以有效防御那些控制了某个CA或用户安装了恶意CA证书的中间人攻击。network-security-config domain-config domain includeSubdomainstrueapi.yourapp.com/domain !-- 证书固定只信任指定的公钥哈希SHA-256 -- 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-configpin-set定义一组受信任的公钥哈希。expiration设置固定的过期时间强制应用在过期前更新配置这是一个安全最佳实践。pin一个Base64编码的SPKI指纹SHA-256哈希。你需要从服务器的证书或公钥中提取。为什么需要备份Pin服务器证书会到期更新。如果你只固定了一个证书当服务器更换证书时所有老版本客户端将无法连接。提供一个备份Pin例如新证书的Pin可以平滑过渡。实操心得证书固定虽然安全但运维复杂度高。除非你的应用对安全性有极高要求如金融、政务否则需要权衡利弊。一旦实施必须建立严格的证书管理流程。4.2 针对特定Build Type或Flavor的配置你可能希望debug版本允许明文流量方便测试而release版本则严格禁止。可以通过Gradle的资源合并功能实现。在app/src/debug/res/xml/下创建network_security_config.xml配置宽松的策略如允许明文。在app/src/main/res/xml/下创建network_security_config.xml配置严格的策略如禁止明文。在构建时Gradle会将debug目录下的配置合并/覆盖main目录下的配置从而实现差异化。4.3 处理自签名证书或私有CA在内网环境或开发测试中服务器可能使用自签名证书或私有CA颁发的证书。要让应用信任它们有两种方式将CA证书打包到App中仅限调试或可控环境network-security-config domain-config domain includeSubdomainstrueinternal.company.com/domain trust-anchors certificates srcraw/my_custom_ca/ !-- 将CA证书放在res/raw/目录下 -- certificates srcsystem/ /trust-anchors /domain-config /network-security-config警告这会将你的CA证书硬编码在APK中存在安全风险。如果该CA私钥泄露所有使用此配置的应用都可能受到攻击。在调试版本中信任用户证书如前所述使用debug-overrides并安装CA证书到设备。这是更灵活和安全的方式。5. 常见问题排查与避坑指南即使配置看起来正确网络请求仍可能失败。以下是我在实践中总结的排查链路和常见坑点。5.1 问题现象Cleartext HTTP traffic to xxx not permitted这是最经典的错误。意味着应用试图发起一个HTTP请求但当前的安全策略不允许。排查步骤确认目标URL首先检查你请求的URL它是不是以http://开头如果是那问题就很明确了。检查network_security_config.xml你的base-config或相关domain-config中cleartextTrafficPermitted是否设置为false如果目标域名需要HTTP你是否为其配置了独立的domain-config cleartextTrafficPermittedtrue域名是否完全匹配注意大小写和子域名。example.com的配置对www.example.com无效除非设置了includeSubdomainstrue。检查AndroidManifest.xml的旧属性在API 28以前我们可能通过application android:usesCleartextTraffictrue来允许明文流量。这个属性在API 28及以上版本已被network_security_config.xml覆盖但有时会产生冲突。最安全的做法是移除android:usesCleartextTraffic属性完全通过网络安全配置文件来管理。检查WebView如果你的应用内嵌了WebView并且WebView加载了HTTP页面同样受此规则限制。WebView的网络安全配置继承自应用的配置或者可以通过WebSettings.setMixedContentMode等进行单独设置但根源仍需在network_security_config.xml中放行对应域名。5.2 问题现象HTTPS请求失败证书验证错误表现为SSLHandshakeException或CertificateException。排查步骤确认服务器证书有效先用浏览器或curl命令访问该HTTPS地址确认证书是有效的、由可信CA签发的、且未过期。检查抓包工具如果你正在使用抓包工具请确认是否在设备上安装并信任了抓包工具的CA证书。同时检查你的网络库如OkHttp或network_security_config.xml是否配置了信任用户证书debug-overrides。检查证书固定配置如果你配置了证书固定请确认服务器返回的证书链中是否存在与你预置的Pin匹配的公钥。服务器证书轮换后固定的Pin必须更新。检查系统时间设备系统时间不正确可能导致证书“过期”或“未生效”的验证错误。检查网络库配置某些网络库如OkHttp、Retrofit允许自定义TrustManager或SSLSocketFactory。如果你在这些地方做了自定义配置例如绕过证书验证请确保其与network_security_config.xml的预期行为一致避免冲突。5.3 问题现象仅在Android 10及以下正常Android 11失败这强烈指向是targetSdkVersion升级到30引入的问题。排查步骤确认targetSdkVersion检查app/build.gradle文件targetSdkVersion是否已经 30。确认配置文件存在且被引用检查res/xml/network_security_config.xml文件是否存在并且AndroidManifest.xml中的android:networkSecurityConfig属性是否正确指向它xml/network_security_config。检查默认行为记住没有配置文件就等于使用了最严格的默认策略。请确保你的配置文件至少包含一个base-config来信任系统证书。5.4 一个隐藏的深坑非应用商店渠道安装的应用从Android 11开始对于通过非应用商店渠道如直接下载APK安装的应用系统会进一步限制其网络访问。即使你正确配置了network_security_config.xml应用在首次启动时也可能无法访问网络。这是因为系统将这些应用视为“不受信来源”。解决方案引导用户去系统设置中找到你的应用在“权限”管理里手动开启“允许访问网络”或类似的开关不同厂商UI略有不同。作为开发者你可以在应用启动时检查网络权限如果被拒绝则弹窗引导用户去设置页面开启。可以使用PackageManager.checkPermission来检查INTERNET权限但注意这个权限在Android中是“normal”级别通常自动授予但在上述特殊情况下可能被系统限制。6. 网络权限的未来与最佳实践建议随着Android版本的迭代网络权限的管理只会越来越精细和严格。从Android 14API 34开始又引入了对应用内启动网页意图Intent的进一步限制。作为开发者我们需要建立一套面向未来的网络权限管理策略。全面拥抱HTTPS这是最根本的解决方案。停止在新功能中使用HTTP并制定计划将遗留的HTTP端点迁移到HTTPS。这将一劳永逸地避免绝大多数明文流量问题。将network_security_config.xml纳入标准配置无论当前targetSdkVersion是多少都建议提前创建和配置这个文件。对于targetSdkVersion 30的应用该文件也会生效让你提前适应新的安全模型。为Debug和Release构建差异化配置如前所述利用Gradle的source set功能为debug构建配置宽松策略信任用户证书、允许特定测试域名明文为release构建配置严格策略禁止明文、启用证书固定等。谨慎使用域配置domain-config非常强大但要慎用。特别是cleartextTrafficPermittedtrue务必将其限制在绝对必要的、范围明确的域名内切勿使用通配符或过于宽泛的域名。建立证书管理流程如果你使用了证书固定必须建立一个流程来管理证书的生命周期监控服务器证书过期时间提前生成新证书的Pin并更新到客户端设置合理的pin-set expiration日期。充分测试在将targetSdkVersion升级到30或更高版本之前必须在涵盖目标API级别的设备上进行全面的网络功能测试。特别要测试HTTP/HTTPS API调用、文件下载/上传、WebView内容加载、第三方SDK的网络请求它们也受此配置影响。那次调试经历最终以在项目中添加了正确的network_security_config.xml文件而告终。整个过程让我深刻体会到Android平台的安全演进正在迫使开发者从“默认允许”的粗放模式转向“显式声明”的精细模式。这虽然增加了前期的适配成本但从长远看对于构建一个更安全、更可信的应用生态是至关重要的。现在每当我开始一个新项目或升级旧项目的targetSdkVersion时配置网络安全文件已经成为和添加INTERNET权限一样自然的第一个步骤。