android webview 加载本地 html 并发起网络请求时出现 “typeerror: failed to fetch”，根本原因常是缺少网络权限、未配置网络安全策略或未启用必要 webview 设置；本文提供从权限声明、网络配置到代码适配的一站式修复方案。
在 Android 应用中使用 WebView 加载 file:///android_asset/index.html 后，若页面通过 JavaScript（如 fetch() 或 XMLHttpRequest）向远程服务器发起请求，极易遇到跨域（CORS）拦截或网络拒绝错误——但需注意：这不是传统浏览器的 CORS 问题，而是 Android 系统级网络限制与 WebView 安全策略共同导致的结果。常见表现包括 Failed to fetch、net::ERR_CLEARTEXT_NOT_PERMITTED 或直接无响应。
✅ 关键修复步骤（缺一不可）
1. 添加互联网权限（必须）
在 AndroidManifest.xml 的
<uses-permission android:name="android.permission.INTERNET" />
⚠️ 注意：仅声明在
2. 配置 Network Security Configuration（强制要求）
创建文件 res/xml/network_security_config.xml：
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<domain-config>
<domain includeSubdomains="true">your-api-domain.com</domain>
<trust-anchors>
<certificates src="system" />
</trust-anchors>
<!-- 若调试阶段需允许 HTTP（不推荐上线） -->
<cleartextTrafficPermitted="true" />
</domain-config>
<!-- 全局允许（仅限调试，禁止用于生产） -->
<!-- <debug-overrides>
<domain-config>
<domain includeSubdomains="true">localhost</domain>
<domain includeSubdomains="true">10.0.2.2</domain>
<cleartextTrafficPermitted="true" />
</domain-config>
</debug-overrides> -->
</network-security-config>并在 AndroidManifest.xml 的
<application
...
android:networkSecurityConfig="@xml/network_security_config"
... >3. WebView 设置增强（适配现代 API）
在 MainActivity.java 中，移除重复设置 setWebViewClient 的冗余调用（当前代码中设置了两次，后者会覆盖前者），并补充关键配置：
// ✅ 正确合并 WebViewClient，并启用现代网络支持
mWebView.setWebViewClient(new WebViewClient() {
@Override
public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
// Android 7.0+ 使用 WebResourceRequest，兼容旧版可加判断
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
view.loadUrl(request.getUrl().toString());
} else {
view.loadUrl(request.getUrl().toString());
}
return true;
}
@Override
public void onReceivedSslError(WebView view, SslErrorHandler handler, SslError error) {
handler.proceed(); // ⚠️ 仅用于测试！生产环境应验证证书
}
});
// ✅ 必须启用：允许混合内容（HTTP over HTTPS 页面加载 HTTP 资源）
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
mWebView.getSettings().setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW);
}
// ✅ 启用 DOM Storage 和数据库（已存在，确保未被覆盖）
mWebView.getSettings().setDomStorageEnabled(true);
mWebView.getSettings().setDatabaseEnabled(true);4. （可选）后端配合：正确返回 CORS 响应头
若你控制服务端，请确保响应包含以下关键 Header（尤其当 WebView 以 https:// 或 http:// 方式加载页面时）：
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Content-Type, Authorization
? 提示：file:// 协议下，Chrome/WebView 不发送 Origin header，因此服务端 CORS 检查可能被跳过；真正触发拦截的往往是 Android 的 cleartext 限制或 TLS 证书校验。
? 总结与最佳实践
- 永远先检查 INTERNET 权限 —— 这是 80% 初学者失败的根源；
- Android 9+ 必须配置 network_security_config.xml，否则 HTTP 请求直接被系统拦截；
- 避免在生产环境调用 handler.proceed() 处理 SSL 错误，这会带来中间人攻击风险；
- 不要依赖 setAllowUniversalAccessFromFileURLs(true) 解决网络请求问题 —— 它仅影响 file:// 页面内的 JS 访问其他 file:// 资源，对 fetch('https://...') 无效；
- 推荐调试方式：在 WebView 中临时注入 JS 打印 navigator.onLine 和 fetch(...).catch(console.error) 具体错误，精准定位是网络层还是 JS 层异常。
完成以上配置后，重新构建运行，fetch() 请求即可正常发出并接收响应。
