Eruda 移动端调试：面板选择、按需加载与数据安全

Eruda 是面向移动浏览器的网页调试控制台。它适合在手机上快速检查 JavaScript 日志、DOM、网络请求、页面资源和运行信息；可按需选取工具面板，也支持扩展。它不是浏览器完整 DevTools 的等价物，也不替代真实设备的远程调试、服务端观测或自动化回归。

旧教程把 2.x 固定版本写成“当前版本”，并建议使用 @latest、document.write 和 localStorage 持久开关。本文改为可审查的现代接入方式。以本文核对时的上游 package.json 为准，Eruda 发布在 3.x 主版本线上；安装时应重新检查 npm 版本、变更记录和维护状态，不要把此处版本当作永久结论。

安装：项目依赖优先

日常开发将 Eruda 安装为开发依赖，并让锁文件确定解析版本：

npm install --save-dev eruda

在支持 ESM 动态导入的客户端代码里，只有开发模式才加载并初始化：

export async function startMobileDebug() {
  if (!import.meta.env.DEV) return null;
  const eruda = (await import("eruda")).default;
  eruda.init({
    tool: ["console", "elements", "network", "resources", "sources", "info"],
  });
  return eruda;
}

环境变量语法随 Vite、Webpack、Next.js、Astro 等工具不同，照项目的客户端构建文档改写。所有打进浏览器的条件和常量都可被用户查看，因此不能把“知道某个 query 参数”或“Local Storage 有一个 true”当成安全授权。若要给内测同学开放，应通过受保护的测试构建、访问控制和明确期限，而非公开线上页面的暗门。

完成调试时关闭面板或直接刷新隔离测试页；若页面生命周期会反复初始化，要避免重复调用 init() 并检查退出清理。调试器可能包装全局 API，性能、内存与时序测试应再用不含调试面板的构建复测。

面板怎么选

Console：找首个异常、警告和错误堆栈。先确认异常是否发生在工具加载之前，检查 Source Map 与压缩产物是否匹配。
Elements：检查 DOM 结构、样式和元素尺寸。适合定位滚动容器、遮罩层、点击区域或安全区适配问题；复杂布局仍应回到桌面 DevTools 看计算样式和布局轨迹。
Network：观察请求 URL、方法、状态和时间。对照服务端请求 ID 定位失败，切勿将完整请求头、Cookie、Authorization、响应体直接贴到公开工单。
Resources：检查页面资源与可访问的客户端存储。清理前确认目标是测试数据；生产用户的存储包含会话、偏好和离线数据，不应随意删改。
Sources：有助于查看加载脚本和源文件，但未必获得正确 Source Map，也不意味着可以安全地修改正在运行的生产页面。
Info：汇总 URL、User Agent 等环境字段。复制前检查 URL 查询参数和设备信息是否包含可识别个人或内部环境的内容。

尽量只初始化排障需要的面板，缩小 UI 与内存开销。不同 Eruda 版本的工具名称、配置字段、插件 API 会变化；以安装版本附带的类型声明和官方文档为准。示例采用官方 README 当前列出的面板名称，不代表所有版本都支持相同配置。

不要直接复制的旧式 CDN 注入

旧文示例通过 document.write 插入未固定版本的第三方脚本，再用 Local Storage 决定是否加载。现代模块应用应使用动态 import；如果仅做一次临时静态页实验，也应该选明确版本并把脚本限制在可信域名。不要直接使用：

<script src="https://cdn.example.invalid/eruda/REVIEWED_VERSION/eruda.js"></script>

这个 .invalid 域名和 REVIEWED_VERSION 是占位符，不能运行。按官方 README 和当前 CDN 文档取得精确地址。没有 SRI、版本固定和 CSP 审查时，避免生产 CDN 注入。document.write 可能覆盖或阻塞页面解析、造成竞态，也不适合 SPA 的页面生命周期；它不是修复脚本加载失败的通用手段。

调试流程：记录可复核的证据

记录设备、系统、浏览器或 WebView 内核版本、应用版本、网络环境与发生时间；使用专用测试账号和测试数据。
先清楚描述预期与实际结果，执行最短复现路径，不要同时刷新、清数据和切换网络，以免破坏现场。
看 Console 最早的异常，再结合 Network 找到对应请求及状态。区分 DNS/TLS/浏览器策略、服务端响应、数据解析、UI 状态更新等层次。
记录请求 ID、状态码、时间和必要字段结构；Authorization、Cookie、账号、手机号、真实内容、私网地址全部遮盖。
在桌面远程调试、第二种移动浏览器或相邻 WebView 版本上交叉验证。若问题只发生在一类容器，检查原生桥接、权限、内核版本和注入时机。
修复后同时验证开发调试构建和关闭 Eruda 的生产等价构建，并清理临时日志、测试存储和账号会话。

面板的 Network 记录不是完整抓包证明。请求可能在注入前发出，也可能由 Service Worker、Worker、iframe、原生网络层或未覆盖 API 处理。面板没有记录时，应结合远程 DevTools、代理抓包（经授权）、服务端日志和请求追踪 ID继续定位。

插件与能力扩展

Eruda 生态里有 FPS、时序、内存、特性检测、代码片段、触摸事件等第三方或独立插件。插件与面板同样能读取页面内容，甚至运行代码，所以安装前要核对维护者、源仓库、npm 包名、许可、依赖、发布记录和数据权限。不要把旧清单中的每个插件都视作官方维护或适合生产。

自定义插件应限定输入、避免执行用户提供的任意代码，减少对页面全局对象的修改，并检查卸载时能否移除监听器、Observer、定时器和 DOM。插件有副作用时，优先只在专用调试构建中启用。

生产与隐私边界

调试面板能读取当前页面可见的数据，包括用户输入、接口响应、URL 参数和客户端存储；屏幕录制和截图也会扩散这些内容。
不要让普通访客通过 query、Local Storage、控制台命令或未鉴权 API 打开调试面板。前端条件不是访问控制。
不要在生产环境把请求体、响应体、Cookie、密码、令牌或个人信息写入日志；日志最小化和脱敏应在应用层落实。
严格 CSP 下不要为了调试全站放开任意脚本、unsafe-eval 或宽泛 CDN 来源；遵循组织的安全评审。
内测开启要有负责人、有效期、可撤销开关、适用账号/环境和事后清理；不要对公网长期保留调试入口。
报告问题时只提交最小脱敏证据；导出 HAR、Console 或 storage 前逐字段检查。

官方资料

Eruda 官方 README：安装、基础初始化、文档入口及相关项目。
Eruda 文档站与官方类型声明：核对安装版本对应的初始化选项和 API。
Eruda 发布历史与 npm 包：核对兼容性、版本和依赖。
MDN：动态 import()：按需加载代码模块。

Eruda 是排障时的放大镜，不会替你判断数据是否安全、问题归属哪一层或修复是否可靠。把它留在受控的开发/内测工作流中，线上用户的稳定性则由测试、错误监控、结构化日志、指标和追踪共同保障。