HarmonyOS ArkWeb 系列之不插数据线也能调试网页——WiFi 无线调试详解

文章目录

• • • USB 调试和 WiFi 调试的区别
    • 代码实现
    • 权限配置
    • 如何用 DevTools 连接（WiFi 方式）
    • 连接流程图
    • 端口选择建议
    • 安全问题：WiFi 调试比 USB 调试风险更高
    • USB 调试 vs WiFi 调试，该用哪个？
    • 踩坑记录
    • 写在最后

上一篇讲了 USB 调试，需要插数据线。但有些情况下插线很不方便：

• 设备正在固定支架上测试特定姿态
• 同时调试多台设备，USB 口不够
• 需要调试 USB 充电时的 Web 行为

WiFi 无线调试就是为这些场景设计的。和 USB 调试的效果完全一样，只是连接方式从 USB 变成了局域网 TCP。

USB 调试和 WiFi 调试的区别

代码实现

WiFi 调试只需要给 setWebDebuggingAccess 多传一个端口号参数：

import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';

const DEBUGGING_PORT: number = 8888; // TCP 端口，1024~65535 均可，避开常用端口

@Entry
@Component
struct WebComponent {
controller: webview.WebviewController = new webview.WebviewController();

aboutToAppear(): void {
try {
// 第二个参数：TCP Socket 监听端口
webview.WebviewController.setWebDebuggingAccess(true, DEBUGGING_PORT);
} catch (error) {
console.error(`开启无线调试失败: ${(error as BusinessError).code}, ${(error as BusinessError).message}`);
}
}

build() {
Column() {
Web({ src: 'https://www.example.com', controller: this.controller })
.width('100%')
.height('100%')
}
}
}

和 USB 调试的区别：

权限配置

和 USB 调试一样，需要在 module.json5 里声明网络权限：

{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
}
]
}
}

如何用 DevTools 连接（WiFi 方式）

前提条件：手机和电脑连接同一个 WiFi 网络。

步骤一：获取手机的 IP 地址

在手机上：「设置 → 关于手机 → 状态信息 → IP 地址」，记下 IP，比如 192.168.1.123。

步骤二：运行应用

安装并运行开启了 WiFi 调试的应用，打开包含 Web 组件的页面。

步骤三：在 Chrome 打开调试页面

在电脑 Chrome 地址栏输入：

devtools://devtools/bundled/inspector.html?ws=192.168.1.123:8888/json

把 192.168.1.123 替换为你手机的实际 IP，8888 替换为你配置的端口号。

或者先访问 http://192.168.1.123:8888/json 查看所有可调试的页面列表，找到对应页面的 WebSocket URL，再用那个 URL 打开 DevTools。

连接流程图

端口选择建议

端口号 8888 只是示例，你可以用 1024~65535 范围内的任意值。但要避开以下常用端口，防止冲突：

推荐用 8888、9090、7777 这类不太常用的端口。

安全问题：WiFi 调试比 USB 调试风险更高

USB 调试要求物理连接，且设备会询问是否信任电脑，有一定的物理安全保障。

WiFi 调试的风险更高：同一局域网内任何设备都可以连接到调试端口。这意味着公司内网里的同事、咖啡厅同一 WiFi 里的陌生人，都可能连上你的调试接口。

正确的安全实践：

import { BuildProfile } from 'BuildProfile';

const DEBUGGING_PORT: number = 8888;

aboutToAppear(): void {
// 只在 DEBUG 模式下开启，release 包绝对不能开启
if (BuildProfile.DEBUG_MODE) {
try {
webview.WebviewController.setWebDebuggingAccess(true, DEBUGGING_PORT);
console.info(`Web 无线调试已开启，端口: ${DEBUGGING_PORT}`);
} catch (error) {
console.error(`开启调试失败: ${(error as BusinessError).message}`);
}
}
}

生产环境绝对不能开启任何调试模式，这是红线。

USB 调试 vs WiFi 调试，该用哪个？

日常开发：USB 调试优先

• 连接更稳定
• 不受网络环境影响
• 安全风险小

以下场景考虑 WiFi 调试：

• 设备无法插 USB（特殊测试夹具、多台设备并行测试）
• 需要同时调试多台设备（每台用不同端口）
• 远程协助调试（需要通过 VPN 或内网穿透）

踩坑记录

坑一：端口被防火墙拦截

某些企业/校园网络会拦截非标准端口的通信。如果 http://手机IP:8888/json 访问超时，先检查网络防火墙策略。

坑二：手机 IP 地址变化

连接 WiFi 时，手机通常是 DHCP 分配 IP，重新连接 WiFi 后 IP 可能变化。建议在路由器上给手机绑定静态 IP，或者在应用界面上显示当前 IP 地址，方便查看。

import { wifi } from '@kit.ConnectivityKit';

// 在页面上显示当前 IP，方便开发时查看
const linkedInfo = wifi.getLinkedInfo();
const ip = linkedInfo.ipAddress;
// 将数字 IP 转为字符串（大端字节序）
const ipStr = `${(ip >> 24) & 0xff}.${(ip >> 16) & 0xff}.${(ip >> 8) & 0xff}.${ip & 0xff}`;
console.info(`当前设备 IP: ${ipStr}`);

坑三：同时开两个 Web 组件页面，端口冲突

setWebDebuggingAccess 是全局设置，整个应用共用一个调试服务端口。如果应用里有多个页面都有 Web 组件，不需要在每个页面里都调用，只需要在应用启动时调用一次即可（比如在 EntryAbility.onCreate() 里调用）。

写在最后

WiFi 调试和 USB 调试的效果完全一样，只是多了个端口参数，多了个 IP 地址的连接方式。

掌握这两种调试方式，基本上覆盖了 Web 组件开发的所有调试场景。记住：上线前一定要关掉。