三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Android明文HTTP通信配置指南：Network Security Configuration详解

发布时间：2026/8/13 3:12:51 三亩地 编程学习日记
Android明文HTTP通信配置指南：Network Security Configuration详解

1. 项目概述：为什么我们还在讨论明文HTTP？

在Android开发圈里，每次提到“允许明文HTTP通信”，总能看到一些开发者露出“这还不简单”的表情，然后随手在AndroidManifest.xml里加上android:usesCleartextTraffic="true"。但如果你真这么干了，尤其是在2024年的今天，我敢说，你很可能正在给自己或团队埋下一个不大不小的坑。这个项目标题“Android网络安全配置：允许明文HTTP通信的正确姿势20240418”，恰恰点出了一个被很多人误解或轻视的关键领域：在日益严格的网络安全要求下，如何合规、安全且精准地管理Android应用中的非加密网络流量。

简单来说，它解决的核心问题是：当你的应用因为历史遗留接口、内网环境调试、特定硬件设备通信（如某些IoT设备）或本地服务器测试等不得已的原因，必须与HTTP（而非HTTPS）端点通信时，如何正确配置，既能满足功能需求，又能遵循Android系统的安全策略，避免应用在更新版本的Android系统上崩溃或被应用商店拒绝。这绝不是一句“打开明文流量开关”那么简单，它涉及到对Android网络安全配置（Network Security Configuration）文件的深入理解、对不同Android版本的适配，以及如何在安全与便利之间找到最佳平衡点。

这篇文章，就是把我过去几年在多个项目中处理这类问题踩过的坑、总结的经验，系统地梳理给你。无论你是正在对接一个老旧的后台系统，还是在开发一个需要与本地智能硬件通信的App，这里的“正确姿势”都能帮你避免常见的陷阱，写出更健壮的代码。

2. 网络配置的核心思路与方案选型

2.1 从“一刀切”到“精细化管控”的演进

早期Android（主要是Android 6.0 Marshmallow到Android 8.0 Oreo之间）对明文HTTP的态度相对宽松。常用的方法就是在AndroidManifest.xml的<application>标签里设置android:usesCleartextTraffic="true”。这个属性就像一个大总闸，一旦打开，整个应用对所有域名的HTTP请求都被允许。在开发和测试初期，这确实非常方便。

但问题也随之而来。首先，这是全局性的。意味着即使用户访问的是外网，你的应用也可能通过HTTP传输敏感信息，带来安全风险。其次，从Android 9.0 (Pie) 开始，Google进一步收紧了策略。默认情况下，即使你设置了usesCleartextTraffic="true”，系统对目标API级别（targetSdkVersion）为28及以上的应用，仍然会阻止向未加密（HTTP）的连接发起请求，除非你进行了更明确的配置。这直接导致了“为什么我在模拟器上好好的，真机（Android 9+）上就网络错误？”的经典问题。

于是，Google引入了更强大的工具：Network Security Configuration (NSC)文件。这是一个独立的XML配置文件，允许开发者以声明式的方法，精细地控制应用的网络安全行为。它的核心思想从“全部允许”转变为“默认拒绝，显式允许”。对于明文HTTP，NSC允许你针对特定域名或特定IP地址段进行放行，而不是全局放开。这就像从给整栋楼通电，变成了给每个房间单独安装一个带标签的开关，安全性和可控性大大提升。

2.2 三种主流方案深度对比

面对明文HTTP需求，我们通常有三种配置路径。选择哪一种，取决于你的应用场景、目标用户设备版本以及安全审计要求。

方案一：传统全局开关 (android:usesCleartextTraffic)

  • 做法：在AndroidManifest.xml中设置。
  • 优点：配置简单，一行代码。兼容所有Android版本（虽然高版本行为有变）。
  • 缺点：安全性最低，影响整个应用。在Android 9+且targetSdkVersion >= 28时，此配置可能失效，必须结合NSC文件使用。在Google Play上架时，此配置可能引发安全审查的额外问询。
  • 适用场景：仅用于早期原型验证、或目标用户绝对集中在Android 8.0以下的极端情况。在现代开发中，已不推荐作为最终方案。

方案二：基础NSC域允许

  • 做法：创建network_security_config.xml文件，在其中使用<domain-config>为特定域名启用明文流量。
  • 优点：安全性高，作用范围精确。符合Android安全最佳实践。是Google官方推荐的方式。
  • 缺点：配置稍复杂，需要理解NSC文件结构。对于需要访问大量不确定HTTP域名（如内网多IP）的场景，配置可能繁琐。
  • 适用场景：绝大多数需要明文通信的场景。例如，你的App需要访问公司内网的测试服务器http://test.internal.company.com，或者某个已知的第三方HTTP API。

方案三：NSC调试覆盖配置

  • 做法：在NSC文件中使用<debug-overrides>，仅在调试构建（debug build）时允许明文流量到指定地址。
  • 优点：完美区分生产环境和开发环境。发布版本（release build）自动禁用明文，安全性最佳。
  • 缺点：仅对通过Android Studio安装的调试包生效。对于需要打测试包给QA或产品经理在真机上测试的场景，可能不适用（除非他们也用debug包）。
  • 适用场景：开发阶段的首选。用于连接本地开发服务器（http://10.0.2.2:8080或http://localhost）或内部测试环境。

我的经验是，对于正式项目，方案二和方案三的结合是最佳实践。在debug构建类型中使用<debug-overrides>方便开发，在release构建类型中，通过<domain-config>精确放行必要的生产环境明文域名（如果确实存在的话）。如果生产环境完全不需要HTTP，那么只保留<debug-overrides>是最干净的。

3. 核心细节解析与实操要点

3.1 理解network_security_config.xml文件结构

这个文件是配置的核心，它必须放在res/xml/目录下。如果该目录不存在，你需要手动创建。它的基本结构像一个决策树，从上到下，系统会按顺序匹配规则。

<?xml version="1.0" encoding="utf-8"?> <network-security-config> <!-- 基准配置：默认信任系统预装CA证书，以及用户安装的证书 --> <base-config cleartextTrafficPermitted="false"> <trust-anchors> <certificates src="system" /> <certificates src="user" /> </trust-anchors> </base-config> <!-- 针对特定域名的配置 --> <domain-config cleartextTrafficPermitted="true"> <domain includeSubdomains="true">insecure.example.com</domain> <domain includeSubdomains="true">192.168.1.100</domain> </domain-config> <!-- 仅调试版本生效的配置 --> <debug-overrides> <trust-anchors> <certificates src="user" /> </trust-anchors> </debug-overrides> </network-security-config>

关键标签解读：

  • <base-config>: 为应用的所有连接设置默认规则。cleartextTrafficPermitted="false"是Android 9+的默认行为，意味着默认禁止所有明文HTTP流量。这是安全的基石。
  • <trust-anchors>: 定义信任的证书颁发机构（CA）。src="system"指手机系统内置的权威CA，src="user"指用户自己安装的证书（常用于抓包调试）。在生产配置中，通常只信任system。
  • <domain-config>: 这是实现“精细化管控”的关键。你可以为不同的域名设置不同的规则。cleartextTrafficPermitted="true"即允许该域名使用HTTP。
  • <domain>: 在<domain-config>内使用，指定具体的域名或IP地址。includeSubdomains="true"表示规则也适用于其所有子域名（例如，设置example.com为true，则api.example.com、cdn.example.com也都适用）。
  • <debug-overrides>: 其内部规则仅在非发布版本（即debuggable为true的构建）中生效。这是隔离开发与生产配置的神器。

注意：在<domain>标签中使用IP地址是允许的，这在连接本地服务器或内网设备时非常有用。但请注意，IP地址不支持includeSubdomains属性。

3.2 在AndroidManifest.xml中引用配置

创建好NSC文件后，必须在清单文件中告知应用使用它。在<application>标签中添加android:networkSecurityConfig属性进行关联。

<application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:networkSecurityConfig="@xml/network_security_config" <!-- 关键行 --> ... > ... </application>

一个至关重要的联动关系：当你正确配置了networkSecurityConfig后，android:usesCleartextTraffic属性的行为会发生变化。在Android 9+设备上，如果你在NSC中通过<domain-config>明确允许了某个域名的明文流量，那么即使usesCleartextTraffic全局设置为false（或默认），该域名的HTTP请求也能成功。反之，如果你只设置了usesCleartextTraffic="true"，但没在NSC中做任何配置（或者NSC中<base-config>明确禁止明文），那么在高版本系统上，HTTP请求依然会被阻止。因此，最佳实践是：在清单中保持usesCleartextTraffic的默认值（不设置或设为false），将所有流量控制逻辑转移到NSC文件中。这样意图更清晰，也便于维护。

3.3 处理非域名形式的URL和重定向

在实际开发中，你可能会遇到一些特殊情况。比如，你的请求URL直接就是一个IP地址加端口，或者后端返回的重定向地址是HTTP的。NSC文件对这两种情况都有明确的处理逻辑。

对于直接使用IP地址的请求（如http://192.168.31.10:3000/api），你需要在<domain-config>的<domain>标签中直接填写这个IP地址。例如：<domain>192.168.31.10</domain>。注意，这里填写的是纯IP，不需要带端口和路径。系统会匹配主机部分。

关于重定向，这是一个容易踩坑的点。假设你的应用向一个HTTPS端点https://api.example.com/login发起请求，而服务器返回了一个302重定向，Location头指向了一个HTTP地址http://cdn.example.com/asset.jpg。此时，Android系统会检查重定向目标地址（即http://cdn.example.com）是否符合网络安全配置。如果该域名不在允许明文通信的<domain-config>列表中，这次重定向请求将被系统直接阻止，导致网络错误。因此，如果你的后端架构中存在从HTTPS到HTTP的重定向，必须确保所有可能被重定向到的HTTP域名，都在NSC文件中被显式允许。

4. 分场景实操过程与配置详解

4.1 场景一：连接本地开发服务器或内网测试环境

这是开发阶段最高频的需求。我们希望在调试时能方便地连接本机（localhost或10.0.2.2，后者是Android模拟器访问主机环回地址的特殊别名）运行的服务器。

正确姿势：使用<debug-overrides>

在res/xml/network_security_config.xml中配置：

<?xml version="1.0" encoding="utf-8"?> <network-security-config> <!-- 生产环境默认规则：禁止明文，只信任系统CA --> <base-config cleartextTrafficPermitted="false"> <trust-anchors> <certificates src="system" /> </trust-anchors> </base-config> <!-- 调试环境特殊规则 --> <debug-overrides> <trust-anchors> <!-- 允许用户安装的证书，方便Charles/Fiddler抓包 --> <certificates src="user" /> </trust-anchors> <!-- 特别允许本地开发服务器的明文连接 --> <domain-config cleartextTrafficPermitted="true"> <domain>localhost</domain> <domain>10.0.2.2</domain> <!-- 如果你的本地服务器有自定义域名，比如 mydev.local --> <domain includeSubdomains="true">mydev.local</domain> <!-- 允许整个内网网段（谨慎使用） --> <domain>192.168.1.1</domain> <domain>192.168.1.100</domain> </domain-config> </debug-overrides> </network-security-config>

实操心得：

  1. localhost和10.0.2.2对于模拟器是有效的，但对于USB调试的真机，localhost指的是手机本身，而不是你的开发电脑。此时，你需要使用电脑在局域网内的IP地址（如192.168.1.100）。
  2. <debug-overrides>内的配置只会在通过Android Studio直接运行debug变体时生效。如果你打了一个debug包（APK）发给别人安装，它同样生效。但release包会完全忽略这部分配置。
  3. 将内网IP段（如192.168.1.x）全部加入允许列表在测试时很方便，但要注意安全边界。更好的做法是只添加你确切知道的测试服务器IP。

4.2 场景二：应用必须访问某个已知的第三方HTTP API

有些老旧公共服务或特定硬件设备可能只提供HTTP接口。你需要在生产版本中允许访问它。

正确姿势：使用针对性的<domain-config>

<?xml version="1.0" encoding="utf-8"?> <network-security-config> <base-config cleartextTrafficPermitted="false"> <trust-anchors> <certificates src="system" /> </trust-anchors> </base-config> <!-- 允许访问特定的第三方HTTP服务 --> <domain-config cleartextTrafficPermitted="true"> <domain includeSubdomains="true">legacy-api.example-service.com</domain> </domain-config> <!-- 允许访问某个智能硬件设备的IP --> <domain-config cleartextTrafficPermitted="true"> <domain>192.168.50.1</domain> <!-- 假设是某个设备的固定IP --> </domain-config> </network-security-config>

关键点：这里配置的<domain-config>位于<debug-overrides>之外，因此对debug和release版本都生效。这意味着你的生产应用也会允许向legacy-api.example-service.com发送HTTP请求。务必在隐私政策或应用描述中向用户说明这一点，并评估其安全风险。如果可能，极力推动服务提供方升级到HTTPS是根本解决方案。

4.3 场景三：应对Android 9.0 (Pie) 及以上的兼容性配置

如果你的targetSdkVersion已经升级到28或更高，你会发现之前的“万能”usesCleartextTraffic="true"不好使了。这是因为Android P引入了一项默认行为：禁止所有明文流量。

解决方案就是前面提到的NSC文件。但这里有一个重要的细节：即使你创建了NSC文件并允许了特定域名，如果你仍然在清单中保留了android:usesCleartextTraffic="true"，系统行为会变得有些微妙。在某些版本上，它可能被视为一个“全局允许”的覆盖指令，导致你的NSC精细化配置失效。

因此，对于targetSdkVersion >= 28的应用，最清晰、最推荐的做法是：

  1. 从AndroidManifest.xml中移除android:usesCleartextTraffic属性，或者显式设置为false。
  2. 完全依赖network_security_config.xml文件来管理网络安全性。
  3. 在NSC文件中，通过<base-config cleartextTrafficPermitted="false">设置默认禁止明文。
  4. 通过<domain-config>逐个放行真正需要的HTTP域名或IP。

这样配置，应用在Android 9.0以下的设备上，由于系统不支持NSC，会回退到默认允许明文的行为（为了兼容性）。而在Android 9.0+的设备上，则会严格执行你在NSC中定义的精细规则。这种配置策略能实现最好的前后兼容。

5. 常见问题排查与实战技巧实录

即使按照“正确姿势”配置了，在实际开发和测试中，你仍然可能会遇到各种网络连接问题。下面是我总结的一些常见“坑”及其排查思路。

5.1 问题一：配置了NSC，但HTTP请求依然失败（错误：CLEARTEXT communication not permitted）

这是最常见的问题。排查步骤应该像侦探破案一样有条理：

  1. 检查NSC文件是否被正确引用：确认AndroidManifest.xml中android:networkSecurityConfig指向的路径和文件名完全正确，且没有拼写错误。一个快速验证的方法是，故意在NSC文件中写一个XML语法错误（比如少一个闭合标签），然后编译运行。如果编译器报错，说明文件被成功读取；如果不报错，则说明可能根本没引用到。
  2. 确认请求的域名/IP是否在允许列表中：仔细核对NSC文件中<domain>标签的内容。http://api.test.com:8080/v1对应的域名是api.test.com，端口和路径不是匹配依据。确保没有多余的空格或换行。特别注意子域名：如果你要访问beta.api.test.com，而配置里只有<domain>api.test.com</domain>且includeSubdomains="false"（默认），那么请求会被阻止。必须设置为<domain includeSubdomains="true">api.test.com</domain>或直接指定<domain>beta.api.test.com</domain>。
  3. 检查构建变体：你是否正在运行release构建变体，却只把配置写在了<debug-overrides>里？或者反过来？确保你的配置针对当前运行的变体是有效的。
  4. 检查Android系统版本：在Android 9+的设备/模拟器上，你的targetSdkVersion是否>=28？如果是，必须使用NSC，仅设置usesCleartextTraffic无效。
  5. 使用ADB命令验证配置：这是一个非常实用的高级技巧。在终端执行以下ADB命令，可以强制应用在下次启动时重新解析NSC文件，有时能解决缓存问题：
    adb shell pm clear your.package.name
    或者，在应用运行时，通过StrictMode或日志来观察。你可以在代码中尝试获取当前配置：
    val config = ApplicationProvider.getApplicationContext<Context>().resources.getString(R.xml.network_security_config) Log.d("NSC_DEBUG", "Config: $config")
    但这需要将NSC文件作为原始资源读取，稍显复杂。

5.2 问题二：HTTPS请求在调试时失败（证书错误）

当你使用Charles、Fiddler等抓包工具拦截HTTPS流量时，需要在手机上安装抓包工具的根证书。此时，你需要配置NSC以信任用户安装的证书。

配置方法：在<debug-overrides>或针对特定域名的<domain-config>中，添加<certificates src="user" />。

<debug-overrides> <trust-anchors> <certificates src="system" /> <certificates src="user" /> <!-- 关键：信任用户证书 --> </trust-anchors> </debug-overrides>

实操心得：

  • 在<base-config>中添加<certificates src="user" />是极度危险的，因为这会让你的生产版本也信任用户安装的任意证书，极大降低安全性，可能导致中间人攻击。绝对不要在生产配置中这么做。
  • 正确的做法是仅在<debug-overrides>中信任用户证书，这样只有调试包会受影响。
  • 如果抓包仍然失败，请检查证书是否已正确安装到手机的“用户凭据”中，并且确保你的抓包工具正确配置了代理和SSL解密规则。

5.3 问题三：不同构建变体（Flavor）需要不同的网络配置

大型项目通常有多个产品风味（product flavors），例如dev、staging、prod，它们需要连接不同的后端环境（有些是HTTP，有些是HTTPS）。

解决方案：为不同Flavor创建不同的NSC文件。

  1. 在src目录下为每个flavor创建对应的资源目录：
    • src/dev/res/xml/network_security_config.xml
    • src/staging/res/xml/network_security_config.xml
    • src/main/res/xml/network_security_config.xml(prod或默认配置)
  2. 在每个文件中编写针对该环境的配置。例如，dev版本可以允许内网HTTP地址，prod版本则严格禁止任何明文。
  3. 在AndroidManifest.xml中，仍然只引用@xml/network_security_config。构建系统会根据当前激活的flavor自动选择正确的文件。

这是管理多环境配置最清晰、最不容易出错的方式，强烈推荐在复杂项目中使用。

5.4 问题四：WebView中的明文HTTP内容加载失败

如果你的应用内使用了WebView来加载网页，那么WebView同样受到网络安全配置的约束。上述所有关于NSC的规则，同样适用于WebView。

这意味着，如果你在WebView中尝试加载一个http://开头的网页或页面内的HTTP资源（如图片、脚本），而该域名不在NSC的允许列表中，加载将会失败。

解决方法完全一致：在network_security_config.xml中，通过<domain-config>允许该网页的域名。例如，要加载http://internal-wiki.company.com，就需要添加对应的域名配置。

一个需要特别注意的点是，从Android 10 (API 29) 开始，即使你在NSC中允许了明文，WebView的默认混合内容策略也可能阻止非加密资源。你可以在代码中为WebView设置更宽松的策略（仅在必要时）：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) { webView.settings.mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW }

但这会降低页面安全性，需权衡使用。

6. 安全考量与最佳实践总结

允许明文HTTP通信本质上是一种安全妥协。在不得不这么做的时候，我们必须将风险降到最低。以下是我从多个项目上线和安全审计中总结出的几条铁律：

  1. 最小化原则：只允许访问确有必要且受控的HTTP端点。绝对不要为了方便而全局打开明文流量（usesCleartextTraffic="true"）或允许一个很大的IP段。
  2. 环境隔离：充分利用<debug-overrides>。开发、测试环境需要的HTTP配置，绝不允许泄露到生产版本中。用构建变体和资源目录来严格隔离。
  3. 明确告知：如果生产版本应用必须使用HTTP通信，应在隐私政策或应用描述中向用户明确说明，并解释原因（例如，“为连接您本地网络中的特定设备”）。透明是最好的策略。
  4. 持续推动升级：将允许HTTP的域名记录在案，并作为技术债务。积极与相关服务提供方沟通，制定升级到HTTPS的计划和时间表。HTTP允许列表应该是临时的，而不是永久的。
  5. 定期审计：在每次应用大版本更新前，复查network_security_config.xml文件。清理不再使用的域名，确认每个允许项仍然必要。
  6. 测试覆盖：为涉及HTTP通信的功能编写集成测试或UI测试，并在不同Android版本（特别是API 28+）的模拟器或真机上运行，确保配置始终生效。

最后，我个人最深刻的体会是，“正确姿势”的核心不在于记住那几行XML配置，而在于建立起一种“默认安全，显式放行”的思维模式。Android系统在不断收紧安全策略，这是对用户负责，也是对开发者提出更高要求。从一开始就采用精细化的NSC进行配置，虽然初期会多花一点时间，但它带来的清晰性、可维护性和安全性，会在项目的整个生命周期里持续回报你。下次当你又想顺手加上usesCleartextTraffic="true"时，不妨先停下来，想想是否真的没有更优雅、更安全的解决方案。

编程学习 学习日记 实战经验
← 返回列表