常见问题

本页收集 eruda-plus 用户最常遇到的问题与解决方法。开始排查前，建议先确认你使用的是最新版本——大部分历史问题已在更新日志中标记修复。

通用问题

悬浮球不显示？

首先确认 eruda.init() 确实被调用且没有报错：可以在页面控制台输入 eruda && eruda._isInit 检查。其次检查页面 CSS 是否把 body 设为了 overflow: hidden 且挂载容器高度为零。少数站点会隐藏外来元素，可尝试在 init 时指定其他 container。最后确认没有开启系统级的「强制深色/省电」策略阻止脚本运行。

初始化后页面报错或样式异常？

eruda-plus 会把自己的样式注入 document，个别站点存在极端的 CSS 重置导致面板样式被覆盖。这种情况下请附上报错截图与站点 URL 提交 Issue，我们按站点逐一适配。也可以先开启「无痕模式」排除浏览器扩展的干扰。

console 被覆写后如何恢复？

调试台销毁时会自动还原。若你需要在运行中临时放行日志到原生控制台，可在设置中关闭「覆写控制台」，此时日志仅进入原生 console，不再显示在面板中。完整销毁请使用 eruda.destroy()。

网络面板

为什么有些请求显示不出响应内容？

图片等二进制响应以预览形式展示；跨域响应若无 CORS 头，浏览器不会把响应体暴露给脚本，此时响应区会显示为空，这与桌面 DevTools 在跨域下的表现一致。另外 no-store 与 Service Worker 拦截的请求受各自机制约束，请结合具体场景判断。

Mock 规则为什么不生效？

按以下顺序排查：规则是否勾选了「启用」；模式是否与完整 URL 匹配（关键词匹配是子串匹配，/api 能命中所有包含它的请求）；是否被更早的重写规则改写了 URL 导致匹配失败；请求是否本身就被屏蔽规则拦截——屏蔽的优先级高于 Mock。列表中带 * 的状态码即代表 Mock 命中。

屏蔽与 Mock 谁优先？

执行顺序为：重写 → 屏蔽 → Mock → 节流。也就是说重写后的 URL 才参与屏蔽与 Mock 匹配，被屏蔽的请求不会再进入 Mock 与真实网络。

节流会影响页面上的图片加载吗？

会。节流作用于 XHR 与 fetch，<img> 等资源加载由浏览器内核直接调度，脚本层无法干预——这与桌面 DevTools 的网络节流限制相同。需要验证弱网下的图片体验时，可使用系统级弱网模拟配合本功能。

报错与堆栈

点击堆栈链接后源码显示不全？

超大文件会自动跳过高亮以保障流畅度，但行号与内容依然完整可查。若源码区显示「无法加载源代码」，通常是该文件存在跨域限制或已被服务端删除。

堆栈里的行号与源文件对不上？

如果站点发布了压缩混淆后的代码，行号对应的是压缩产物。若构建系统产出 sourcemap 且同域可访问，可在源码面板直接查看 map 后的文件；跨域的 sourcemap 受浏览器安全策略限制无法读取。

发布与部署

npm 包里包含什么？

包内包含 dist/eruda.js（完整版）、dist/eruda-network-plus.js（仅网络增强插件）、类型声明与 README。通过 npm publish 的 OIDC 可信发布通道发布，每次 GitHub Release tag 会触发自动发布流程。

如何在生产环境彻底关闭调试台？

推荐用 URL 参数或环境变量控制初始化，例如 if (location.search.includes('debug')) eruda.init()。未初始化时 eruda-plus 只包含包体加载成本，不会执行任何拦截。若已初始化，可调用 eruda.destroy() 在运行时彻底移除。

还有其他问题？欢迎到 GitHub Issues 搜索或提问，通常会在 48 小时内得到回复。