移动端真机调试实战指南

概述

响应式 H5、微信小程序、Hybrid 内嵌页、UniApp/Taro 跨端应用，都要直面设备碎片化（屏幕、系统版本、内核、性能）和真实交互（触摸、传感器、JSBridge）。浏览器模拟器无法还原真实触摸细节、真机性能、弱网和原生交互，因此真机调试是移动端开发的必备环节。

本文给出两条主线：Chrome/Safari 完整调试（看元素、改样式、打断点）与 Charles 抓包（只看接口）。前者用于开发与本地联调，后者用于线上或 APP 内嵌 H5 的接口排查。

学习目标

说清模拟器无法替代真机的四类局限
完成 Android（chrome://inspect）与 iOS（Safari Web Inspector）真机连接
配置开发服务器允许局域网访问并解决跨域
用 Charles 完成 HTTPS 抓包、断点改包、Map Local、弱网限速
掌握 vConsole / Eruda 这类移动端"页面内控制台"的兜底方案

一、为什么必须真机调试

局限	说明
触摸事件	模拟器用鼠标近似，多点触控、长按、滑动细节失真
真实性能	复杂计算、动画在低端真机上才可能暴露卡顿
网络环境	模拟器难以复现 4G/5G 切换与弱网
原生交互	Hybrid 中的 `window.JSBridge.callNative(...)` 在桌面环境无法执行

二、方案一：Chrome / Safari 完整调试

Android + Chrome

手机「设置 → 关于手机」连点版本号 7 次开启开发者模式，进「开发者选项」打开 USB 调试
USB 连接电脑并选"文件传输"，弹窗点允许
电脑 Chrome 打开 chrome://inspect/#devices，勾选 Discover USB devices
手机浏览器访问页面，列表中出现设备后点 inspect，即可用完整 DevTools

iOS + Safari（需 Mac）

iPhone「设置 → Safari → 高级」开启 Web 检查器
Mac Safari「偏好设置 → 高级」勾选"在菜单栏显示开发菜单"
USB 连接并信任，iPhone 用 Safari 打开页面
Mac Safari「开发 → [你的 iPhone] → 页面」打开 Web Inspector

局域网无线调试

开发服务器需允许外部访问，并用代理解决跨域：

javascript

// vite.config.js
export default {
  server: {
    host: '0.0.0.0', // 允许同网段手机访问
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://backend.example.com',
        changeOrigin: true,
        rewrite: (p) => p.replace(/^\/api/, ''),
      },
    },
  },
};

手机与电脑连同一 WiFi，访问 http://[电脑IP]:3000。本机 IP：ifconfig | grep "inet " | grep -v 127.0.0.1（Mac/Linux）或 ipconfig（Windows）。

三、方案二：Charles 抓包

Charles 本质是 HTTP/HTTPS 代理，长项在接口层：请求/响应拦截、重放、改包、弱网模拟；短板是看不到 DOM、Console 和执行 JS，因此只适合"只想看接口"的场景。macOS 用户首选（跨平台且易用），Windows 可用免费的 Fiddler。

首次配置要点：

开启代理：Proxy → Proxy Settings 端口默认 8888
启用 HTTPS：Proxy → SSL Proxying Settings 勾选 Enable，添加 Host: * / Port: 443
电脑安装 Charles 根证书并设为"始终信任"；手机访问 chls.pro/ssl 下载安装（iOS 还需在「关于本机 → 证书信任设置」启用）
手机 WiFi 代理改"手动"，服务器填电脑 IP、端口 8888，Charles 弹窗点 Allow

高频用法：

功能	入口	用途
过滤	顶部搜索 / Recording Settings 的 Include	只盯目标域名
断点改包	右键请求 → Breakpoints	修改请求参数或响应数据测试边界
重发	右键 → Repeat / Repeat Advanced	压测或复现接口问题
Map Local	Tools → Map Local	用本地 JSON 替线上接口，做 Mock
Map Remote	Tools → Map Remote	把线上接口映射到测试环境
弱网	Proxy → Throttle Settings	3G/4G/自定义带宽与延迟，验证超时与骨架屏

四、移动端页面内控制台

当无法走电脑 DevTools（如纯线上环境、别人手机），用页面内嵌控制台兜底：

vConsole：npm i vconsole，在入口 new VConsole()，页面右下角出现面板，可看 Console、Network、System、Elements
Eruda：更轻量，适合生产环境按需启用——通过 ?debug=true 这类 URL 参数才初始化，避免污染普通用户

javascript

// 生产环境按需启用 Eruda
const params = new URLSearchParams(location.search);
if (params.get('debug') === 'true') {
  import('eruda').then(({ default: eruda }) => eruda.init());
}

五、常见问题对照

现象	原因	解决
Chrome 找不到设备	USB 调试未开 / 缺驱动	开启 USB 调试、装驱动、重插
iOS 不显示在 Safari	Web 检查器未开	iPhone 设置 → Safari → 高级 → Web 检查器
手机打不开电脑 IP	不同网段 / 防火墙	同 WiFi，放行端口或关防火墙
Charles 抓不到 HTTPS	未装证书 / 未开 SSL	装根证书并启用 SSL Proxying
代理后无法上网	IP 或端口错	确认电脑 IP 与 8888，Charles 在运行
跨域失败	未配代理	配 webpack/vite 的 proxy

常见问题

Q: 开发阶段和线上排查分别该用哪套方案？

本地联调、要改样式或断点，用 Chrome/Safari 真机 inspect 最顺手；线上 bug 或 APP 内嵌 H5 拿不到电脑调试权限时，Charles 抓包看接口最快，再用 vConsole/Eruda 在页面内补看日志。两者常组合：Charles 改响应 Mock，配合页面内控制台验证渲染。

Q: 为什么 HTTPS 抓包要先装证书还要"信任"？

HTTPS 是端到端加密，Charles 要解密就必须充当"中间人"：它用自己的根证书签发站点证书，手机只有信任了该根证书才会接受被篡改的流量。iOS 13+ 还需额外在「证书信任设置」手动启用，否则系统仍会拒绝。