Cordova打包Vue2应用：Android WebSocket连不上的完整排查指南-代码聚汇网

Cordova打包Vue2应用：Android WebSocket连不上的完整排查指南

孙亚健·2026-10-12·阅读 27 GEO检测（免费）

CordovaVue2WebSocket

|难度：普通|阅读约 27 分钟

最近把一个 Vue2 实时通信项目用 Cordova 11 打成 apk，装到 Android 手机上测试。页面打开正常，样式、按钮、HTTP 请求都好好的，唯独 WebSocket 一直连不上：PC 浏览器里实时推送完好，手机端永远停在“连接中”。查了两天，console 里各种报错都见过，最后发现这个“手机连不上”其实是三个问题叠在一起：CSP 默认没有放行 ws 连接；Android 9+ 默认禁止明文流量（ws:// 属于明文）；连接地址写成了 localhost，在手机上 localhost 指向的是手机自己。后面还牵扯出服务器监听地址、Cordova 白名单等好几个隐藏细节。这篇文章把完整排查链路记下来，给以后打包 Cordova + Vue2 项目的朋友一个参照。

1. 问题现场：PC 正常、手机连不上的 WebSocket

1.1 一段在浏览器里跑得好好的代码，为什么到了 apk 里就哑火

项目里有个聊天功能，前端用的是原生 WebSocket。Vue2 代码大致长这样：

javascript复制// 连接初始化
const WS_URL = 'ws://localhost:9501/ws'
this.ws = new WebSocket(WS_URL)

this.ws.onopen = () => {
  this.$store.commit('setSocketStatus', true)
}
this.ws.onclose = () => {
  this.$store.commit('setSocketStatus', false)
}
this.ws.onerror = (e) => {
  console.log('websocket error', e)
}

在 PC 端跑 npm run serve，打开页面，onopen 立刻触发，服务端也收到了连接，消息来回都正常。等 npm run build 产出静态文件，放进 Cordova 项目的 www 目录，再用 cordova build android 出 apk，装到手机上测试，问题就出现了：

页面能正常打开，其他走 https 的 HTTP 接口都通；
WebSocket 的 onopen 不执行，onerror 倒是触发了；
服务端日志里完全没有新连接记录。

一开始我怀疑是 vue 代码打包时被压缩出了问题，但同样的 JS 在 PC 上用 file:// 方式直接打开也能连上。这就说明问题不在 Vue 代码本身，而是 Android WebView 的运行环境和浏览器不一致。

1.2 PC 浏览器和 WebView 之间，至少差了四个设置

把 PC 浏览器和 Cordova 的 Android WebView 放一起对比，差异一目了然：

维度	PC 浏览器	Cordova Android WebView
页面加载方式	http://localhost:8080	file:///android_asset/www/index.html
ws:// 是否算明文	浏览器不限制	Android 9+ 默认拦截明文流量
CSP 策略	devServer 默认没启用或很宽松	Cordova 模板自带严格 CSP meta
localhost 指向	PC 自己	手机自己
调试方式	DevTools 直接看	需要 chrome://inspect 或 adb logcat

结论先说透：Android WebView 对 WebSocket API 的支持是完整的，问题不是“手机不支持 WebSocket”，而是它外面套了好几层网络策略。接下来按排查顺序讲这三层开关。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 三个元凶逐个排查：CSP、明文流量与 localhost 陷阱

2.1 第一道闸：CSP 默认没放行 ws，console 直接红色拒绝

CSP 全称 Content Security Policy，是浏览器的一个安全层，用来限制页面能加载哪些资源、能连接哪些后端。WebSocket 连接归 connect-src 指令管，如果页面里没有显式声明 connect-src，浏览器就回退到 default-src。

Cordova 11 生成的模板 index.html 里默认带一行 CSP：

html复制<meta http-equiv="Content-Security-Policy"
      content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:;">

这里面没有 ws:// 的影子。于是 WebView 在发起 ws 连接前就把请求挡掉了，console 里会给明确提示：

code复制Refused to connect to 'ws://192.168.0.7:9501/ws' because it violates the following Content Security Policy directive: "default-src 'self' ..."

刚开始没意识到是 CSP，是因为 PC 浏览器开发环境默认没有这个 meta 标签，所以同样的代码在 PC 上完全正常。一旦知道原因，解决也不复杂：在 CSP 的 connect-src 里把 ws/wss 地址加进去。这一步不改，后面改什么都白搭。

2.2 第二道闸：Android 9+ 默认拒绝明文流量，手机会直接掐断连接

绕过了 CSP 后，新的报错大概率会是：

code复制net::ERR_CLEARTEXT_NOT_PERMITTED

这是 Android 从 9.0（API 28）开始引入的明文流量限制。所谓明文流量，就是没有经过 TLS 加密的协议：http://、ws://、ftp:// 都算。ws:// 本身不带加密，和发不加密的 HTTP 请求一样，数据在网络上裸奔。Android 对 targetSdkVersion 大于等于 28 的应用，默认把 usesCleartextTraffic 置为 false，所有明文网络请求一律拒绝。Cordova 11 背后的 cordova-android 11 默认 targetSdk 远超 28，所以默认就是禁止 ws 的。

用生活里的例子理解：http 和 ws 相当于把快递内容直接暴露在快递单上，任何中间环节都能看到；https 和 wss 则是先把物品封进箱子里、封条加密，快递单上只有地址。Android 的保底策略就是：不让我验证箱子有没有封好，我干脆单都不给你发。

所以单纯在代码里把 ws 换成 wss 就能绕过这道闸。但开发环境很多服务器不支持 wss，那就得在 manifest 层面开一个口子，把 usesCleartextTraffic 临时打开。这个口子具体怎么开，放到第 3 节说。

2.3 第三道坎：localhost 是给电脑自嗨的，手机上的 localhost 是手机自己

还有一类连不上，配置全改完了还是失败，最后发现是地址问题。PC 浏览器里的 ws://localhost:9501/ws 能连，是因为 localhost 指到开发机自己。手机上的 localhost 指到手机自己，手机自己的 9501 端口上并没有 WebSocket 服务，自然连不上。

正确做法是把地址改成电脑在局域网里的 IP，比如 ws://192.168.0.7:9501/ws，并且保证下面几个条件同时满足：

手机和电脑连的是同一个 WiFi 或局域网网段；
WebSocket 服务端监听的是 0.0.0.0，而不是 127.0.0.1；
电脑防火墙对 9501 端口放行；
如果局域网开了 AP 隔离（一些公共 WiFi 会这样），手机和电脑之间根本不通，换热点测试最直接。

服务端监听这个点特别容易忽略。很多本地模拟服务默认只监听回环地址，PC 自己访问没问题，局域网里其他设备一概访问不了。用 Node 的 ws 库时要显式指定 host：

javascript复制const WebSocketServer = require('ws').Server
const wss = new WebSocketServer({ port: 9501, host: '0.0.0.0' })

这一步做不好，前面所有配置等于白做。

3. 修复实操：Cordova 配置文件的完整改法

3.1 先把 WebSocket 地址从代码里抠出来

修配置之前，先做一件干净的事：把 WebSocket 地址从 Vue 代码里的硬编码改成环境变量。这样开发环境、测试环境、生产环境各用各的地址，不用每次打包都改代码。

在 Vue2 项目根目录的 .env.production 里加一行：

code复制VUE_APP_WS_URL=ws://192.168.0.7:9501/ws

代码里读这个变量：

javascript复制const wsUrl = process.env.VUE_APP_WS_URL || `ws://${location.hostname}:9501/ws`

注意 location.hostname 在 file:// 页面里可能是空字符串，所以这个 fallback 只在浏览器调试时有用。移动端打包前一定要把环境变量配好。

3.2 第二步：让 CSP 的 connect-src 放行 ws/wss

Cordova 的 www/index.html 实际上就是 Vue 产物覆盖得到的，CSP 的 meta 标签写在 public/index.html 里，最终会跟着构建产物一起进入 www。Cordova 模板默认的 CSP 需要手动扩展，把 WebSocket 地址加进 connect-src：

html复制<meta http-equiv="Content-Security-Policy"
      content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval';
               connect-src 'self' ws://192.168.0.7:9501 wss://192.168.0.7:9501;
               style-src 'self' 'unsafe-inline';
               media-src *;
               img-src 'self' data: content:;">

开发阶段图省事，可以用 connect-src 'self' ws://*:* wss://*:*，但上线前建议把域名和端口写死，避免 CSP 形同虚设。如果之后把 ws 改成了 wss，同样只要改 CSP 里的地址，不需要动 manifest 那边，因为 wss 本身不是明文流量。

3.3 第三步：在 config.xml 里打开明文流量开关

Cordova 11 最省事的做法是用官方 preference，在 config.xml 的 android platform 节点里加一行：

xml复制<platform name="android">
    <preference name="AndroidUsesCleartextTraffic" value="true" />
</platform>

加好后执行 cordova prepare android，再去 platforms/android/app/src/main/AndroidManifest.xml 里确认，application 节点上会被注入 android:usesCleartextTraffic="true"。

如果某个 Cordova 版本里这个 preference 不生效，可以用 edit-config 强制合并：

xml复制<platform name="android">
    <edit-config file="app/src/main/AndroidManifest.xml"
                 target="/manifest/application"
                 mode="merge">
        <application android:usesCleartextTraffic="true" />
    </edit-config>
</platform>

上面两种写法二选一。我推荐先用 preference，因为简单，少引入一堆 XML 命名空间的问题。

强烈建议：不要直接去改 platforms/android 目录下的 AndroidManifest.xml。那个目录是 Cordova 根据 config.xml 和插件动态生成的，你改了，下一次 cordova platform rm android && cordova platform add android 或 cordova prepare 就会被覆盖。想要可复现、可提交、上 CI 稳定，就用 config.xml 的声明式配置。

3.4 第四步：顺手把 Cordova 白名单也放宽

Cordova 从早期版本开始就有白名单机制，用来控制 WebView 允许跳转到哪些地址、应用允许请求哪些外部资源。虽然 WebSocket 严格来说不完全等于导航，但白名单配置缺失时，某些 WebView 版本和插件组合下照样会拦 ws 连接。保险起见，在 config.xml 里加：

xml复制<allow-navigation href="ws://*/*" />
<allow-navigation href="wss://*/*" />
<access origin="ws://*" />
<access origin="wss://*" />

正常情况下，<access origin="*" /> 已经覆盖了大多数外部请求，如果为安全考虑之前收紧过，那 ws 也需要单独列出来。改完之后重新构建：

bash复制cordova build android
# 或者直接跑真机
cordova run android --device

到这里，前面说的 CSP、明文流量、localhost、白名单这几层就全部打通了。

3.5 一份可直接参考的完整 config.xml

如果你是照着抄，直接看这个：

xml复制<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.myvueapp" version="1.0.0"
        xmlns="http://www.w3.org/ns/widgets"
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>MyVueApp</name>
    <description>A Vue2 project wrapped by Cordova 11</description>
    <content src="index.html" />

    <access origin="*" />
    <allow-navigation href="http://*/*" />
    <allow-navigation href="https://*/*" />
    <allow-navigation href="ws://*/*" />
    <allow-navigation href="wss://*/*" />

    <platform name="android">
        <preference name="AndroidUsesCleartextTraffic" value="true" />
    </platform>
</widget>

id 记得换成你自己应用的包名。这样配置文件在团队协作、CI 流水线里都是可复现的，不会因为某个人手改过 platforms 目录导致行为不一致。

4. 真机验证：用 Chrome Inspect 和 adb 把日志看得明明白白

4.1 用 chrome://inspect 直接看 WebView 的控制台

改完配置后，别急着看状态栏图标，上真机看日志最准。

手机打开 USB 调试，连接电脑，用 Chrome 地址栏访问 chrome://inspect。如果页面里能列出你的 App WebView，点 inspect 就能看到和浏览器一模一样的 DevTools，Console 里的报错、Network 里的请求、Sources 里的 JS 全部可查。

有一点要注意：release 构建的 apk 默认没有开启 WebView 调试。排查阶段尽量用 cordova run android --debug 或者 cordova build android --debug。如果已经开始维护 release 包，也可以在 MainActivity 的 onCreate 里加一句：

java复制WebView.setWebContentsDebuggingEnabled(true);

不过上线前记得去掉，不然任何拿到你手机的人都能通过 chrome://inspect 看内部页面。

4.2 没有开发者工具时，adb logcat 也能定位

如果 Chrome 版本和系统 WebView 不兼容、设备列表里就是不出现 WebView 标签，另一个办法是抓系统日志。先清空旧日志：

bash复制adb logcat -c
adb logcat | grep -iE "console|websocket|chromium"

WebView 的 console.log 会以 CONSOLE(...) 的形式打到系统日志里。我之前排查时，logcat 里直接看到：

code复制chromium: [INFO:CONSOLE(1234)] "Refused to connect to 'ws://...' because it violates ... CSP", source: http://localhost/index.html? (1)

这一行直接把问题指向 CSP，省掉大量猜测。建议整个排查过程都把这个命令挂在旁边，每次改动后观察新日志。WebSocket 连接是在应用层被拦的，TCP 层面不一定有痕迹，只看服务端日志很容易误判成“根本没连上来”。

4.3 一页速查：常见报错与对应解法

把开发和联调阶段遇到的报错整理成表格，遇到哪个直接对号入座：

报错文本	原因	解法
Refused to connect to 'ws://...' because it violates Content Security Policy	CSP 未放行	在 meta 或服务端响应头里给 connect-src 加上 ws/wss 地址
net::ERR_CLEARTEXT_NOT_PERMITTED	Android 明文流量限制	开启 AndroidUsesCleartextTraffic 或改用 wss
Failed to construct 'WebSocket': The URL 'ws://...' is invalid	地址格式错误	检查协议头、端口、路径是否写对
WebSocket connection failed: net::ERR_CONNECTION_REFUSED	服务端没监听或端口不通	检查服务端 host 是否为 0.0.0.0、防火墙、局域网连通性
net::ERR_CERT_AUTHORITY_INVALID	wss 用了自签名证书	换成受信任的 CA 证书，开发期可用网络安全配置临时信任

把 TCP 通了但握手失败、握手到了但协议不匹配这些问题也考虑进去，基本能覆盖开发阶段八成以上的坑。

5. 生产环境建议：wss 与网络安全配置的正确写法

5.1 能用 wss 就别在 ws 上纠结

表格里反复提到 wss，这里专门说清楚。wss:// 是 WebSocket 的加密版本，底层走 TLS，Android 不会把它当明文流量拦截。所以如果后端已经支持 HTTPS，WebSocket 服务只要挂在同一个域名下并启用 SSL，前端把地址从 ws:// 改成 wss://，CSP 里对应改成 wss://，manifest 的明文开关根本不需要打开。

这也是发布到生产环境的唯一正解。usesCleartextTraffic 开到 true 等于全局允许明文 HTTP 和 ws，对面向真实用户的应用来说，这个口子太大了。就算只连自己的服务器，中间链路被劫持、数据被篡改的风险也会绕过 WebSocket 本身的权限控制。

特别提醒：自签名证书在 Android WebView 里默认不受信任，wss:// 用自签证书会报 ERR_CERT_AUTHORITY_INVALID，就算把 android:usesCleartextTraffic 设为 true 也救不回来。开发时想测 wss，要么用内网环境里的正式证书，要么用网络安全配置临时信任证书，不要为了省事直接关掉证书校验。

5.2 只想放行指定域名？用 networkSecurityConfig 做精确放行

如果不想全局打开明文流量，只想让 App 连内网那个特定的 ws 服务器，Android 也提供了更细粒度的做法：网络安全配置。

在 platforms/android/app/src/main/res/xml/ 下新建 network_security_config.xml：

xml复制<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">192.168.0.7</domain>
        <domain includeSubdomains="true">ws-api.example.com</domain>
    </domain-config>
</network-security-config>

然后在 AndroidManifest.xml 的 application 节点上引用：

xml复制<application android:networkSecurityConfig="@xml/network_security_config" ... />

这样只有列出的域名可以走明文，其他地址仍然必须 https/wss。

在 Cordova 项目里做这件事有两种方式：要么在 config.xml 里用 edit-config 引用这个资源，再通过 hook 脚本把 xml 文件复制到 res/xml 目录；要么直接在 platforms 目录里放好文件，但要接受 platform rm/add 后会丢。如果你没有自动化构建流程，我的建议是：能接受全局开明文就用 preference，两分钟搞定；如果想要正规一点，找一个验证过的 hook 脚本把 res/xml/network_security_config.xml 从项目根目录复制到平台目录，这样配一次，后续构建都能带上。

5.3 顺带提醒：Vue2 打包 Cordova 常踩的另两个坑

跟 WebSocket 无关，但只要是 Cordova 打包 Vue2 项目的人，大概率会连续踩中。

第一，vue-router 必须用 hash 模式。mode: 'history' 依赖服务器支持路由回退，而 Cordova 的页面跑在 file:// 下，根本没有服务端，进入子路由刷新就是白屏：

javascript复制const router = new VueRouter({
  mode: 'hash',
  routes
})

第二，vue.config.js 里要设置 publicPath: './'。不设的话，打包后的 JS/CSS 路径以 / 开头，在 file:// 协议下找不到资源，页面白得干干净净。这两个坑当年都让我排查过很长时间，建议打包前先写好。

这次问题解决后，我最大的体会是：Cordova 打包本身不复杂，复杂的其实是浏览器环境和 WebView 环境之间的差异。CSP、明文流量、localhost、白名单，任何一个都可能让你线上功能静默失效，而且这几个因素经常同时存在。排查的时候按“地址检查 → CSP → 明文开关 → 白名单”的顺序来，配合 chrome://inspect 确认每一步的报错变化，两个小时基本能定位。如果这篇记录能帮你少走点弯路，那就算值了。