在开发 Android 应用时，我们经常会遇到各种各样的网络连接问题，其中最令人头疼的莫过于面对突然弹出的 Cleartext HTTP traffic not permitted 错误。特别是对于刚接触 Android 开发的新手朋友，或者是在维护老项目的开发者来说，这个问题往往让人措手不及。当你在 Logcat 中看到这行红色的报错，或者应用的数据加载界面一直转圈却无果时，通常就是安全策略在“作怪”。
在这篇文章中，我们将作为技术伙伴，一起深入探讨为什么 Android 要禁止明文流量，这个机制背后的安全原理是什么，以及最重要的——我们该如何通过多种专业的技术手段来彻底解决这个问题。无论你是想让测试服务器快速跑通，还是需要配置企业级的安全白名单，这里都有你需要的答案。
HTTP 与 HTTPS：不仅仅是多了一个 "S"
在我们着手解决错误之前，让我们先回到基础，理解一下为什么 Android 系统要“强人所难”。我们要从这两个协议的根本区别说起。
HTTP（超文本传输协议） 是互联网的基石。它就像是我们在邮局寄送的一张明信片。信件上的内容——也就是我们要传输的数据，无论是用户的密码、聊天记录还是图片——任何人只要在这张明信片经过的路上（比如路由器、ISP 供应商）稍微停留，都能毫不费力地看清上面的内容。在现代网络环境中，这显然是极不安全的。
而 HTTPS（安全套接字层超文本传输协议），则像是给这张明信片装进了一个只有收件人和发件人才能打开的保险箱，并且贴上了防伪标签。URL 中的那个 "S"，代表了 Security（安全）。它利用 TLS（传输层安全） 或 SSL 协议，在客户端和服务器之间建立了一条加密通道。即使攻击者在半路截获了数据包，他们看到的也只是一堆乱码，完全无法破解其中的信息。
Android 的安全立场
出于对用户隐私和数据安全的极致追求，Google 从 Android 9（API 级别 28） 开始，默认禁用了所有应用的“明文流量”。这意味着，如果你的应用试图通过 http:// 协议连接服务器，系统会直接拦截请求并抛出错误。这是 Android 平台演进的一个里程碑，迫使开发者拥抱更安全的网络环境。然而，在实际开发中，我们往往会遇到以下情况，必须暂时或永久地允许 HTTP 访问：
- 内部测试环境：公司内部的测试服务器可能尚未配置 SSL 证书。
- 第三方 API 限制：某些老旧的第三方接口只支持 HTTP。
- 调试与抓包：在开发阶段，我们需要通过抓包工具（如 Charles 或 Fiddler）查看明文数据以排查逻辑错误。
既然明白了原因和背景，让我们通过实战步骤，逐一攻克这些障碍。
解决方案 1：理想状态——迁移到 HTTPS
虽然这听起来显而易见，但在解决“明文流量被禁”的错误时，我们首先应该问自己：“我能直接把 URL 换成 HTTPS 吗？”
许多现代服务器和 API 提供商（如 AWS, Azure, Google Cloud 等）默认已经支持 HTTPS，或者提供免费的 SSL 证书。如果服务器端支持，这是最简单、最安全的修复方式，无需修改任何 Android 代码逻辑。
修改示例：
假设你之前的 API 请求是这样的：
// 这是一个不安全的 HTTP 请求
String unsafeUrl = "http://api.example.com/v1/data";
你可以简单地将其修改为：
// 升级为安全的 HTTPS 请求
String secureUrl = "https://api.example.com/v1/data";
如果你的服务器支持 HTTPS，运行一下应用，错误可能瞬间就消失了。但如果服务器不支持，或者你正在处理老旧的遗留系统，我们就需要采取更深层的措施了。
解决方案 2：全局开启明文流量（快速但不推荐生产环境）
如果你正在开发一个处于快速原型阶段的应用，或者明确知道应用不会处理敏感数据，你可以选择在全局范围内允许明文流量。这就好比告诉 Android 系统：“我知道我在做什么，请放行所有的明文请求。”
我们需要修改 INLINECODE29f3d62f 文件中的 INLINECODE163f8201 标签。
具体操作步骤：
- 打开项目中的
AndroidManifest.xml文件。 - 找到
标签。 - 添加
android:usesCleartextTraffic="true"属性。
代码示例：
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:usesCleartextTraffic="true"
android:theme="@style/Theme.App">
注意事项：
这种方法虽然简单快捷，但它“一刀切”地关闭了针对所有域名（包括第三方服务和内部链接）的网络安全保护。在提交到 Google Play 时，过度的明文流量可能会导致审核被拒或安全警告。因此，除非万不得已，我们强烈建议使用下一种更精细化的方法。
解决方案 3：网络安全配置（企业级最佳实践）
对于大多数商业级应用来说，我们通常只对特定的几个域名（例如测试服务器、内部接口）允许 HTTP 访问，而对其他所有域名强制使用 HTTPS。Android 提供了一个非常强大的机制——网络安全配置文件，让我们可以精确地控制域名的安全策略。
#### 第一步：创建网络安全配置 XML 文件
我们需要在项目的 INLINECODE6433b10a 目录下创建一个新的 XML 文件。如果 INLINECODEc3c5e39a 文件夹不存在，请右键点击 INLINECODE2f242c91 文件夹，依次选择 New > Directory，输入 INLINECODE4c876ef5。
然后，右键点击刚才创建的 INLINECODE7d83bf8d 文件夹，选择 New > XML Resource File，将其命名为 INLINECODE3ea12932。
#### 第二步：配置域名白名单
在这个文件中，我们将定义哪些域名允许明文传输。假设我们需要访问 api.internal-test.com，且该服务器目前仅支持 HTTP。
代码示例（res/xml/network_security_config.xml）：
api.internal-test.com
<!-- legacy-partner.com -->
这段代码是如何工作的？
通过 INLINECODE86888559 标签，我们实际上是在告诉 Android 系统：“嘿，对于 INLINECODEb0a16eaa 这个地址，我知道它可能不安全，但我信任它，请允许使用 HTTP 协议访问。” 而对于其他任何不在列表中的网站，系统依然会严格执行 HTTPS 检查，从而保证了整体应用的安全性。
#### 第三步：在 Manifest 中引用配置文件
光创建文件是不够的，我们还需要在 AndroidManifest.xml 中告诉系统去哪里读取这个配置。
代码示例（更新后的 AndroidManifest.xml）：
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:networkSecurityConfig="@xml/network_security_config"
android:theme="@style/Theme.App">
通过这种方式，我们既解决了特定域名的访问问题，又没有牺牲应用整体的安全性，这是目前最推荐的解决方案。
解决方案 4：处理特殊的沙箱版本问题
还有一种较少见但令人困惑的情况，可能与 Target Sandbox（目标沙箱） 有关。如果你的应用在清单文件中显式声明了 android:targetSandboxVersion，并且值大于 1（在 Android 8.0 之后引入的新沙箱），那么一些较旧的网络行为可能会被严格限制。
虽然这不是解决明文流量的首选方案，但如果你发现上述方法都无效，且你的应用依赖于非常旧的 SDK 行为，你可以尝试检查并调整此属性（通常建议移除它，或者设置为 1）。
代码示例：
深入理解与常见陷阱
在解决了连接问题之后，我们不妨再深入一点，了解一下你可能会遇到的进阶问题和最佳实践。
#### 1. 混合内容的处理
在现代网络技术中，有一种被称为 SSL Pinning（证书锁定） 的技术。如果你启用了证书锁定，那么仅仅允许明文流量可能还不够，你必须确保证书哈希值完全匹配。在网络安全配置中，你可以通过 标签来锁定证书，防止中间人攻击。这对于金融类或支付类应用尤为重要。
#### 2. 调试技巧：如何抓包明文
当你使用了 usesCleartextTraffic="true" 或者配置了白名单后，你就可以使用像 Charles 或 Fiddler 这样的工具来抓取 HTTP 数据包了。这对调试 JSON 数据结构非常有帮助。
- 提示： 如果你的 Android 设备运行在 Android 7.0+，抓包 HTTPS 依然需要额外的配置（在 INLINECODE68f7ceb6 中添加 INLINECODE5d7e2700 以信任用户安装的抓包证书）。
#### 3. 性能优化建议
- 减少 HTTP 调用：HTTP/1.1 相比 HTTPS/TLS 会话通常握手开销较小，但在现代移动网络下，差别微乎其微。然而，如果必须使用 HTTP，请确保你使用了 HTTP Keep-Alive（连接复用）来减少握手次数。
- 数据压缩：既然是明文传输，数据流量可能会较大。确保你的 API 支持
Accept-Encoding: gzip，并在客户端使用如 OkHttp 这样的库自动处理解压缩，以节省流量并加快加载速度。
常见错误排查清单
如果你按照上述步骤操作后，依然无法连接，请检查以下几点：
- 语法错误：检查
network_security_config.xml的 XML 格式是否正确。有时候复制粘贴会导致出现隐藏的特殊字符。 - 域名拼写：确保 XML 中的
与你的 API URL 完全一致（不包含 http:// 或 https:// 前缀，也不要带路径，只填域名）。 - 混淆问题：如果你使用了 ProGuard 或 R8 进行代码混淆，确保你的网络相关类没有被错误地优化掉。
- 防火墙/网络限制：有时候不是手机禁止了流量，而是公司网络或路由器的防火墙拦截了特定的端口。
总结
在 Android 开发的道路上，Cleartext HTTP traffic not permitted 不仅仅是一个错误提示，它更像是 Android 平台在督促我们要重视用户信息安全。在这篇文章中，我们了解了 HTTP 和 HTTPS 的本质区别，掌握了从简单的修改 Manifest 到精细化的网络安全配置等多种解决方案。
作为开发者，我们有责任在应用的易用性和安全性之间找到最佳的平衡点。虽然有时候为了开发效率，我们需要临时开放 HTTP 访问，但请不要忘记在发布生产版本前，尽可能地将所有网络请求迁移到安全、加密的 HTTPS 链路上。希望这篇文章能帮助你顺利解决连接问题，构建出既稳定又安全的 Android 应用！