Cordova 开发遇到 Internal navigation rejected 错误的排查与修复

Cordova 构建 iOS 时 Internal navigation rejected 错误排查

在 Cordova 混合应用开发过程中，如果你发现控制台或日志中频繁出现 ERROR Internal navigation rejected - <allow-navigation> not set for url='xxx' 这样的报错，通常意味着 WebView 的安全策略拦截了当前的页面跳转请求。

问题根源

这主要发生在 iOS 9 及以上版本。出于安全考虑，iOS 系统对 WebView 的导航行为进行了更严格的限制。如果 Cordova 项目的白名单配置缺失或不完整，WebView 将无法加载非原生协议或非允许域名的链接，从而抛出上述拒绝访问的错误。

简单来说，就是 App 不知道是否应该信任你试图跳转的那个地址。

解决方案

我们需要在项目的配置文件 config.xml 中显式声明允许的导航规则。这个文件通常位于项目根目录下。

打开 config.xml，在 <widget> 标签内部添加如下配置：

<allow-navigation href="*" />

这里的 href="*" 表示允许跳转到任意 HTTP 或 HTTPS 协议的页面。对于调试阶段或者需要动态加载内容的场景，这是一个快速生效的方法。

注意事项

1. 安全性权衡：使用通配符 * 虽然能解决报错，但在生产环境中存在安全风险。建议根据实际业务需求，将 * 替换为具体的域名，例如 <allow-navigation href="https://example.com/*" />。
2. 重新编译：修改配置后，必须执行清理并重新编译项目（如 cordova clean && cordova build ios），否则更改可能不会生效。
3. 其他相关标签：除了 allow-navigation，有时还需要检查 allow-intent 标签，它主要用于控制外部浏览器打开特定 URL 的行为，两者配合使用可覆盖更多场景。

完成上述配置并重新运行后，该错误通常会消失，页面跳转也能恢复正常。