1. 移动端调试痛点为什么必须在 vite 项目里嵌一个 eruda1.1 真机调试的三大难题做过移动端开发的都知道最难受的不是写代码而是查问题。PC 上有 Chrome DevTools鼠标一点就能看 console、断点、网络请求但到了手机上这套东西基本全废。第一个难题是真机与模拟器不一致。模拟器里跑得好好的样式一到真机上就错位字体大小、安全区域、iOS 橡皮筋滚动各种诡异现象只有真机上才复现。第二个难题是看不了日志。微信内置浏览器、App 内嵌 WebView、各种安卓定制浏览器它们都没有开放的开发者工具入口。页面报错了你连 console 里写了什么都看不到。第三个难题是远程调试门槛高。安卓要开 USB 调试、装驱动、走 adb 端口转发iOS 要连 Mac、开 Safari 开发者模式团队里女孩子用 Windows 的同事基本干不了这活。所以移动端界一直需要一种页面自带调试器的思路把调试面板直接打进页面里用户打开页面就能看到 console、网络请求、本地存储这些信息。这就是 eruda 这类工具存在的意义。1.2 认识 eruda 与 vite-plugin-eruda-pro 的分工eruda 本身是一个运行在浏览器里的移动端调试面板开源、体积不算大功能覆盖 console 日志、Network 抓包、Elements 查看 DOM、Sources 断点、Storage 本地存储等基本是移动端的小号 DevTools。它不依赖任何客户端工具只要页面里引入了它的脚本点开浮动按钮就能呼出面板。但直接用 eruda 有个麻烦怎么把它合理地集成进工程。手动在 HTML 里加 script 标签开发环境没问题可一旦转到生产环境就尴尬——你不想让用户看到调试面板也不想把调试器代码打进生产包。这时候就需要一个工程化的封装层vite-plugin-eruda-pro 干的就是这件事。它是基于 Vite 插件机制写的一个工具核心职责是把 eruda 的引入、加载、开关控制、构建排除全部自动化。在开发阶段你打开手机访问本地服务页面上自动出现调试面板在打包上线时它可以从产物里干干净净地移除不会给生产环境留一点尾巴。2. vite-plugin-eruda-pro 工作原理与核心配置解读2.1 插件在背后完成了哪四件关键事我用过一段之后把它的内部逻辑拆成了四部分理解这几件事对整个排查思路很有帮助。第一件事是往 HTML 里注入引入逻辑。Vite 的插件体系里transformIndexHtml是一个专门用来改写 HTML 的钩子vite-plugin-eruda-pro 就是在这个阶段把 eruda 相关代码塞进index.html的。你可以把它理解成你自己手动写过的那段script srceruda.js/script现在由插件替你管理。第二件事是版本管理。eruda 版本一直在迭代手动去 CDN 淘一个固定版本还得担心缓存失效。插件内部会把版本号和资源地址封装好配置里给个version就能锁定省得每次都要改 HTML。第三件事是开关控制。插件提供了hash、enabled这类参数让你决定在什么情况下加载面板、在什么情况下不加载这一点在多人协作和测试环境里特别值钱。第四件事是构建排除。生产环境默认不注入是这类插件的底线你不需要自己加一堆环境判断代码插件在 build 模式下会直接跳过注入逻辑产物体积自然不会被拖累。2.2 配置项逐参数拆解enabled、hash、csp 的真实用途下面是我梳理出来最常用的一组配置直接在插件选项里传就行。import eruda from vite-plugin-eruda-pro export default defineConfig({ plugins: [ eruda({ enabled: true, silent: false, debug: false, csp: false, hash: #debug, version: 3.0.1, include: /\.html$/, exclude: /prod/ }) ] })逐项说下我的理解。enabled是总开关默认 true。你要是某天临时不想让面板出现改成 false 就完事不用动代码。silent控制 eruda 启动时要不要在 console 里打印一些提示信息生产调试时开着会比较吵建议测试环境设成 true。hash是个很有趣的参数它会让面板只有在 URL 地址栏带指定 hash 时才加载。比如配了#debug手机访问http://192.168.1.10:5173/#debug才会弹出调试按钮不带 hash 访问就是干净页面。这对测试同学很友好——日常回归不受干扰需要排查时加个参数就行。csp是给有内容安全策略的站点用的。如果你的项目网关或者服务端设置了 CSP 头外链脚本默认会被拦截这时候需要把插件配置成csp: true它会改用更符合 CSP 约束的方式注入。include和exclude是两个正则用来限定注入范围比如只给页面类 HTML 注入、排除特定目录。我一直强调一个观点配置不用全都配你能说清每个参数为什么存在就已经赢过大多数人。这套配置设计得比较收敛没有几十个选项堆面前核心就这几个学起来负担小。3. 三步接入 vite-plugin-eruda-pro 并实现按需加载3.1 最小化接入一行代码让移动端页面出现调试面板接 Vite 插件基本都是流水线操作先装包再注册然后重启开发服务器。npm i vite-plugin-eruda-pro -D装的时候我建议加-D因为它是纯开发期工具没有理由进dependencies。接下来在vite.config.ts里注册import { defineConfig } from vite import eruda from vite-plugin-eruda-pro export default defineConfig({ plugins: [eruda()] })完事。启动npm run dev手机和电脑连同一个局域网访问终端里打印的地址页面上就能看到 eruda 的浮动按钮。点开之后console 区会立刻显示当前页面的日志Network 面板里能看到静态资源和接口请求的时序。这一步如果没反应优先查手机和电脑是不是同一网段、防火墙有没有放行 5173 端口九成问题出在这两个地方。3.2 进阶管控只允许指定设备打开面板项目进入联调阶段之后光有开关还不够你得考虑测试环境所有人都会访问。如果人人都能看到调试按钮视觉上很乱甚至可能误触导致页面卡顿。我的做法是用hash参数做一个准入机制。eruda({ hash: #eruda })这样默认访问不会加载 eruda只有手动拼接#eruda的 URL 才会呼出面板。联调的时候我让测试同学把加参数的地址存成书签排查问题效率高很多还不会影响正常业务演示。如果你的场景更极端希望面板只在特定设备上出现可以搭配用户代理判断。Vite 插件本身不提供设备白名单但你可以利用enabled配合环境变量来实现团队内部分发比如只在一台专门的测试机上打开调试其他人访问完全无视。思路是写一个自定义插件或者用.env.test区分环境插件里读mode再决定行为。3.3 生产构建的兜底策略插件默认在生产环境不注入这点我实测过vite build之后产物里搜不到 eruda 相关代码。但我不建议你盲目信任默认值尤其是多人协作的项目最好自己在构建产物里再查一遍。grep -r eruda dist/没有任何输出说明排除干净了。如果还有沾边的内容检查是不是有地方手动引了 eruda 的 npm 包或者 CDN 脚本这类手动引用不受插件管控。另外提醒一句eruda 这种调试工具即使体积不大也不该出现在生产链路里它不仅影响首屏加载还会暴露内部接口和数据属于安全边界问题。4. 实战踩坑记录eruda 面板不显示怎么办4.1 从现象到根因的排查案例我把自己和身边同事踩过的坑整理成了一张排查表按照频率排序每个问题都给出定位思路。现象一页面正常但浮动按钮就是不出来。先确认访问的 URL 是否带了正确的 hash如果配置了hash: #debug不带参数就是不会加载。再看浏览器控制台有没有脚本报错重点看网络面板里 eruda 对应脚本是否 404。开发模式下 Vite 对本地依赖的解析很快但不排除局域网 DNS 和缓存导致旧版本资源被拉到。现象二按钮出来了点开面板是白屏。多半是 eruda 版本和当前浏览器不兼容或者资源被 CSP 拦截。先升级version到最新试一圈不行就把csp: true打开。白屏还有一个隐蔽原因某些安卓 WebView 严格模式下不允许evaleruda 内联代码会被拒这种情况很难绕建议在系统 WebView 或 Chrome 里测试。现象三面板能打开但 console 看不到业务日志。这个问题最坑。常见原因是 eruda 初始化过晚在它接管 console 之前页面已经输出了不少日志。Vite 插件虽然会自动把代码注到 HTML 头部但如果在异步模块里执行早期日志确实可能丢失。稳妥做法是业务代码里不用急着打印面板加载后再操作复现。现象定位方向解决建议浮动按钮不出现hash 参数、脚本 404核对 URL 后缀抓网络请求面板白屏版本兼容、CSP 拦截升级版本开启 csp 配置日志缺失初始化时机、缓存刷新重试清缓存后复现样式错乱面板与业务 CSS 冲突检查 has 覆盖eruda 自带样式隔离4.2 插件与 Vite 其他配置的兼容性问题Vite 配置里插件多了之后顺序和安全边界就成了新问题。vite-plugin-eruda-pro 依赖transformIndexHtml钩子如果你同时用了其他也改 HTML 的插件先注册的先执行。如果某个插件提前把 HTML 做了内联合并eruda 的注入位置就可能不对。另一个常见冲突是 base 路径。项目配置了base: /mobile/时插件如果用了绝对路径的引用方式CDN 或者静态资源地址就要确保能对得上。我建议排查插件问题时优先去掉一半插件用二分法定位是哪个环节引发的。还有一点易被忽略Vite 的define配置里如果把process.env.NODE_ENV替换掉了插件内部的环境判断可能失效。这种问题最头疼因为它不报错只是表现诡异。遇到面板时好时坏建议先检查构建时有没有全局替换环境变量的代码。5. 生产环境安全关闭 eruda 的完整方案5.1 为什么必须从构建层面做排除有人会想既然 eruda 只是一个调试面板我上线前把调用代码删了不就行这种想法在个人项目里勉强能过但在正式项目里风险极大。一来人工删除不可控漏一处就是安全隐患二来版本迭代后有人重新加了调试代码你未必能发现三来调试面板一旦在生产环境可访问等于把内部接口、网络请求、页面结构全部暴露给用户这不是小问题。所以正确的思路是让构建工具替你把关。只要插件默认行为就是生产环境跳过注入你就可以在团队规范里明确一条任何人不得在业务代码里手动引入 eruda也不得绕过插件去做自定义 npm 包引用。把防线前移到工程规范层面比事后整改省心得多。5.2 基于插件机制的三种关闭策略实操里我有三种玩法按项目要求选。第一种是完全禁用。直接不注册插件或者enabled: false适合调试阶段已经收尾、不需要再开真机调试的项目。第二种是环境区分。配合vite --mode做环境变量控制比如只有development和test模式才启用production模式彻底不启用。这是团队项目最推荐的姿势。export default defineConfig(({ mode }) ({ plugins: [ mode production ? [] : [eruda({ hash: #debug })] ] }))这段代码的意图很清楚生产模式插件数组为空其他模式才注入 eruda。比在插件内部判断更可控因为你把行为暴露在了 Vite 配置层后续接手的人一眼就能看懂。第三种是构建产物校验。在 CI 流水线里加一条检查任务构建后 grep dist 目录发现 eruda 关键词就报错。这属于兜底措施给上层约定再加一道保险。6. 我对这套调试链路的几点经验补充6.1 值得长期坚持的使用习惯用 vite-plugin-eruda-pro 一段时间后我总结出几个习惯对团队协作和效率提升很有帮助。第一给移动端联调单独建一个启动脚本。比如npm run dev:mobile专门用来开 eruda 插件日常开发不动。这样一个命令就能区分桌面端调试和真机联调两种场景避免插件在所有环境下都生效。第二把带 hash 的调试地址写进项目 README。新同学接手时不用问你怎么打开调试按钮文档里写清访问方式能省掉很多沟通成本。这个细节看起来小但团队人一多就能感受到价值。第三真机调试时优先用 Network 面板看请求耗时。很多人只盯着 console 看报错忽略了接口耗时和水资源加载瀑布图。eruda 的 Network 面板能把每个请求的时间线列出来排查首屏速度慢的问题时比后端日志直观得多。6.2 后续可以尝试的扩展方向这个插件的扩展空间比我一开始以为的要大。比如你可以结合 Vite 的configureServer钩子自定义一个接口允许远程控制某台设备是否开启面板或者把 eruda 的面板数据导出到本地存储方便回传测试现场的信息。另外如果你同时维护 PC 端和移动端两套项目还可以把 vite-plugin-eruda-pro 的配置抽成一个公共的 Vite 插件配置片段通过 npm 私有包下发。要是项目里已经用了类似 vConsole 的方案想迁移过来也不难——它们都是基于同一个在页面里注入调试面板的思路区别主要在生态整合度。我个人现在最受益的地方其实是省心。以前每次真机调试都要打开各种远程调试工具连接不稳的时候来回折腾。现在页面自己带调试能力还是可按需加载的工作流顺畅了很多。这种工具不需要很高的学习成本却实实在在解决了移动端调试的日常尴尬建议做移动端和混合应用的朋友都试一下。