上周帮同事看一个 Vue 2.6 的后台项目他发我截图Elements 面板里 DOM 树清清楚楚就是翻遍 DevTools 的选项卡也找不到 Vue 那一个。我让他打开浏览器的扩展管理页果然躺着一个灰掉的 Vue.js devtools下面一行小字写着此扩展程序不再受支持。他装的是 5.3.4这也是我们团队内部一直在用的版本。这个场景我今年遇到不下五次。devtools 5.3.4 是 vue-devtools v5 分支的收尾版本只认 Vue 2 那一套调试协议。现在还会去装它的人多半不是想装旧版而是只能装旧版内网机器没有应用商店、测试机内核被锁死、离线环境只能靠 U 盘拷扩展、或者团队要求所有人用同一个版本好对齐截图。这篇就把这件事讲透它到底管哪一代 Vue、为什么装完老是提示 Vue.js not detected、浏览器开始拒绝 Manifest V2 之后还有哪几条路可走以及装好之后哪几个设置值得花十分钟配一下。1. devtools 5.3.4 的定位它管的是哪一代 Vue为什么还有人回头装1.1 5.x 与 6.x/7.x 之间那道线本质是一条协议线Vue 2 的调试接入方式是框架在启动时去认领一个已经存在的全局钩子对象然后把组件实例逐个登记上去。5.x 这套面板就是照着这个协议写的。Vue 3 换了另一套初始化流程走的是新的注册事件5.x 里的面板代码压根不认识这套东西——所以你把 5.3.4 装在 Vue 3 项目上最好的结果是面板能出来但永远显示未检测到最差的结果是面板上只有一片空白。再往下还有一层5.3.4 是Manifest V2的扩展而 6.x 之后换成了 Manifest V3。这两件事必须分清楚因为很多时候面板看不到不是协议问题是浏览器根本不让扩展加载。我见过有人花了两个小时怀疑自己的项目配置最后发现扩展在管理页里是灰的。devtools 版本扩展清单版本认 Vue 2认 Vue 3典型使用场景5.3.xManifest V2是否内网、离线、内核被锁的老环境6.xManifest V3兼容是过渡期版本界面重写行为差别较大7.xManifest V3兼容是现在的主流版本Vue 3 生态首选提示表格里 6.x/7.x 对 Vue 2 的兼容是保留旧协议分支实现的实测大部分 Vue 2 项目能被识别但对老版本比如 2.0 早期的支持不如 5.3.4 稳涉及functional component和自研渲染层的项目尤其容易出怪问题。1.2 哪些人还在真的用 5.3.4我在不同公司见过四类典型情况。第一类是物理隔离的内网扩展包只能走 U 盘或者内部制品库每次升级都要层层审批索性就把版本钉死。第二类是测试机内核版本统一CI 里跑的自动化脚本依赖 devtools 某些老行为比如对 iframe 里组件树的展示方式一换版本脚本就挂。第三类是截图对齐团队里做技术方案评审要用组件树的截图有人用新版有人用旧版同一棵树显示层级不一样沟通成本飙升。第四类最少见但最麻烦基于 5.3.4 改过源码比如把某些内部字段从面板里屏蔽掉、给特定组件加白名单标记这种只能自己维护构建产物商店里根本没有。1.3 它能给你什么给不了什么能给的挺实在完整组件树、每个组件的 props/data/computed 查看与实时编辑、Vuex 状态面板、组件间事件流、性能采样、配合 vue-router 的路由面板以及在 Elements 里选中 DOM 后反向定位到组件实例。最后一个功能对排查这个样式到底是谁改的这类问题几乎是降维打击。给不了的说清楚省得你返工Vue 3 的setup内部变量、script setup的组件名推断5.x 下一律显示 anonymous、Pinia 的状态树Pinia 走的是新协议需要新版面板。所以如果你的项目是 Vue 3 Vite别折腾了直接上新版5.3.4 的主场就是 Vue 2。2. 装之前先搞清检测链路全局钩子与 devtools 开关2.1 钩子是扩展先埋Vue 后来认领浏览器扩展的注入脚本可以在页面里任何业务脚本之前执行5.3.4 就是这么干的它会在文档最早期先往window上挂一个调试钩子对象这个对象带一套事件收发机制等着别人来认领。Vue 2 启动的时候会先看看这个全局变量在不在在的话就把它自己注册进去之后每创建一个组件实例都往钩子上登记一次。面板读的就是这份登记表。这就解释了一个特别常见的问题装完扩展必须刷新页面。扩展是在页面加载时才注入钩子的你当前这个已经渲染完的页面Vue 早就启动完了钩子是空的面板自然什么都没有。很多人装完看到没反应就直接下结论说这版本不好使。2.2 生产构建为什么一定检测不到这是Vue.js not detected里占比最高的原因。Vue 2 里那个 devtools 开关的默认值就是非生产环境才为真而注册钩子的那段代码同样被这个环境判断包着生产构建的时候打包器会把整段代码剪掉死代码消除。也就是说构建产物里根本没有认领钩子这个动作。所以网上流传的在入口文件加一行Vue.config.devtools true就能调生产包绝大多数情况下是无效的——那行赋值在代码没了。这条答案能生效的前提是页面加载的是完整版且未压缩的vue.js而现在的项目基本不会这么干。想快速定性打开你要调试页面的控制台跑这三行const hook window.__VUE_DEVTOOLS_GLOBAL_HOOK__ console.log(钩子是否存在:, !!hook) console.log(钩子上挂了哪些字段:, hook ? Object.keys(hook) : (空)) console.log(登记的实例数量:, hook hook.instances ? hook.instances.length : n/a)判读逻辑很简单钩子不存在 → 扩展没注入到这个页面要么没装、要么被禁用、要么当前页面对扩展不可见。钩子存在但没有任何 Vue 相关字段 → 钩子埋好了没人来认领八成是生产构建。字段名在不同版本的扩展里不完全一样老版本你会看到类似Vue、instances、store这样的字段新版本更多是apps之类的结构看字段名基本就能判断扩展版本和框架版本对不对得上。2.3 一张表看清什么页面能调、什么页面不能页面运行的是什么开关默认值会不会认领钩子面板表现本地开发服务器vue-cli-service serve真会组件树正常可编辑生产构建后本地起静态服务假不会代码已被剪掉面板在提示未检测到CDN 引入未压缩的 vue.js真会正常CDN 引入 vue.min.js假不会提示未检测到用 file:// 直接打开本地 html真取决于扩展权限常见提示未检测到见第 5 节第三方站点上别人的 Vue 页面视构建而定视构建而定生产包一样看不到注意有些人为了调生产环境的问题会把构建模式临时改成 development 再发到测试机。这个做法在排查阶段没问题但别顺手带上线——开发构建去掉了压缩和部分优化体积和性能都不是一个量级。3. 把 5.3.4 装进 Chromium 内核浏览器的三种做法3.1 商店路线能装但装到的不是 5.3.4应用商店里永远只挂当前版本你搜Vue.js devtools装下来的基本是 7.x。对 Vue 2 项目来说这条路很多时候也能用但如果你确实需要 5.3.4前面说的四类场景就只能走离线。有个折中办法先用商店版确认问题不在你的项目配置上确认完了再去折腾固定版本能省很多时间。另外商店的自动更新是关不掉的团队要版本统一的话商店路线本身就不合适。3.2 CRX 离线包改后缀、解压、加载已解压目录拿到.crx之后直接往扩展管理页拖新版本浏览器大概率弹一句无法从该网站添加应用、扩展程序和用户脚本。别在这个提示上纠结绕过去就行# 1. 复制一份改后缀 cp vue-devtools-5.3.4.crx vue-devtools-5.3.4.zip # 2. 解压到一个固定目录别放下载目录会被清理 mkdir -p ~/tools/vue-devtools-5.3.4 unzip vue-devtools-5.3.4.zip -d ~/tools/vue-devtools-5.3.4然后打开扩展管理页右上角把开发者模式打开点加载已解压的扩展程序选中解压后带 manifest.json 的那一层目录。这里有个细节解压出来有的包外面还套了一层文件夹你要选的是 manifest.json 直接所在的目录选错层级加载会直接报错。三个实测坑。第一解压目录不能移动或删除扩展是引用这个路径的你把它挪走扩展就失效而且要重新加载一遍。第二用开发者模式加载的扩展每次启动浏览器会有一个提示条忍一下或者把它固定到工具栏上减少存在感。第三_metadata之类的目录不用管是打包工具带的。3.3 源码构建从 clone 到生成扩展目录的完整过程离线包来源不明的时候我不建议用尤其是要给全组发的情况。自己构建最可控步骤也不多只是有几个版本坑一定得躲开。# 0. 先看 Node 版本这一步决定后面顺不顺 node -v # v5 时代的代码库依赖比较老Node 14.x / 16.x 最省事 # Node 18 以上大概率会遇到 openssl 相关的构建报错 # 1. 拿源码并切到 5.3.4 git clone https://github.com/vuejs/vue-devtools.git cd vue-devtools git tag | grep 5\.3 # 先确认 tag 到底叫什么别凭记忆敲 git checkout v5.3.4 # 2. 装依赖 npm install # 或者 yarn install这个年代的代码库两个都能过 # 3. 构建 npm run build如果你只能用新版本 Node装依赖和构建之前加个兼容开关通常能救回来# macOS / Linux export NODE_OPTIONS--openssl-legacy-provider # Windows cmd set NODE_OPTIONS--openssl-legacy-provider npm run buildnpm install卡在某个老依赖上是另一个高频问题常见的是 node-sass 这类需要编译原生模块的包。处理思路按优先级来能切 Node 版本就切用 nvm 切到 16 最干净不能切就加--ignore-scripts跳过安装脚本构建阶段如果不需要那个模块通常能过再不行就找一个同事的构建产物拷过来别在这一步耗一整天。构建完之后去packages/下面找那个名字里带shell和 chrome 的目录认准 manifest.json 所在的那一层用它去加载已解压的扩展程序。不同的小版本目录名可能略有差别可能叫shell-chrome也可能在别的层级判断标准就是 manifest.json。想给另一个浏览器装的话构建脚本通常也提供了对应目标输出目录会换成 firefox 那一份加载方式是在浏览器的调试页里选临时载入附加组件——这种方式重启就失效正好适合临时排查也不会污染你日常使用的浏览器配置。构建完先自检两件事扩展管理页里显示的版本号是不是 5.3.4然后随便开一个本地开发服务器跑的 Vue 2 页面刷新一下面板里应该能出组件树。这两步都过了再发给同事能省掉很多我这边不行啊的来回。4. Manifest V2 这道硬墙以及绕过它的几种务实选择4.1 现象不是装不上是浏览器不让用最典型的画面是扩展管理页里卡片变灰旁边写着此扩展程序不再受支持或者已停用点启用没反应或者启用后立刻又被停掉。这不是你的包坏了也不是加载方式错了而是浏览器内核已经不再接受这种清单格式的扩展。具体从哪个版本开始生效各内核、各分支的时间点不完全一致所以同一份包在 A 同事机器上好好的在 B 同事机器上直接灰掉这非常正常。碰到这种情况先别怀疑包去扩展管理页看一眼状态。灰的就是清单版本问题往下看绕过方案不是灰的跳到第 5 节的排查链路。4.2 独立壳模式8098 端口加一行 script这是我觉得最值得掌握的一条路因为它同时绕开了扩展加载限制和浏览器版本限制。原理不复杂本地跑一个独立的调试后端页面里引一个脚本两边连起来之后组件树在独立的应用窗口里显示。v5 时代的做法大概是这个样子本地起独立壳之后它会监听一个端口8098 是那会儿的默认值具体以你那份构建的控制台输出为准!-- 只在本地调试时临时加上线前务必删掉 -- script srchttp://localhost:8098/script引进去之后刷新页面独立壳里就会冒组件树。这套玩法的价值在于调试对象可以是任何能跑 JS 的地方——手机里的 WebView、内嵌的浏览器控件、桌面客户端里的页面只要那边能访问到你本机的这个端口就行。移动端还有一个替代方案是用远程设备调试把页面接进桌面浏览器的 DevTools那时候 Vue 面板能不能用取决于页面里跑的 Vue 是不是开发构建这一点跟第 2 节讲的是同一个道理。注意调试结束记得把那行 script 从代码里删掉别让它进版本库。线上页面加载本机端口的脚本除了可能报错之外也容易带来不必要的隐患。4.3 换内核、换浏览器、改版本的取舍方案成本适用情况代价降级/固定浏览器版本中测试机统一、能锁版本安全更新落后得单独维护一套安装包换用仍接受旧清单的浏览器低个人临时排查面板行为可能有细微差异截图不统一升级到新版 devtools低纯 Vue 3 项目Vue 2 老项目可能识别不稳走独立壳模式中内网、移动端、客户端内嵌页需要在页面里加脚本多一个进程要管基于源码自己改清单格式高有维护能力且必须留在 5.3.4升级一次要重新适配一次我的实际选择顺序是能升级就先升级必须留在 5.3.4 的优先用独立壳模式给核心同学用因为它不依赖浏览器策略剩下确实需要浏览器面板的再去折腾固定浏览器版本。最后那个改清单格式的路子我做过一次翻译 manifest 字段、调接口权限、改背景脚本的生命周期一套下来小半天除非有明确需求不建议。5. Vue.js not detected 的排查链路按命中率从高到低走一遍5.1 第一梯队生产构建、协议不匹配、file 协议按我自己的统计前三个原因能覆盖八成以上的情况。第一是生产构建判定方法在第 2.2 节控制台看钩子上有没有 Vue 字段没有就是它。第二是协议不匹配Vue 3 项目装 5.3.4表现是面板出来了但永远空白反过来老版本 Vue 装最新面板也可能识别不到。第三是用 file:// 直接打开本地 html这个坑特别隐蔽因为扩展默认没有访问文件网址的权限钩子根本注入不进去。解决方式是在扩展的详情页里把允许访问文件网址打开然后刷新页面。5.2 第二梯队没刷新、标签被折叠、选错 frame装完扩展没刷新页面前面说过识别不了是必然的。标签被折叠这个更气人DevTools 顶部标签太多的时候Vue 那个会被收进溢出菜单里很多人扫一眼没看到就以为面板没出来。选错 frame也是高频页面里有 iframe 的时候DevTools 顶部有个执行上下文选择器面板默认跟随当前选中的 frame你的 Vue 应用在 iframe 里而上下文停在顶层就是一片空白。切一下上下文再刷新组件树就出来了。还有两个低频但要知道的一是同一个页面被打包器塞进了两份 Vue钩子只认第一个组件树里会出现重复的根二是组件是函数式的或者被v-if关掉了树里看不到是正常的不代表没检测到。5.3 一份可以照着敲的排查清单// 在目标页面控制台逐条跑对照结果定位 // 1. 钩子在不在 !!window.__VUE_DEVTOOLS_GLOBAL_HOOK__ // 2. 钩子上有没有东西 Object.keys(window.__VUE_DEVTOOLS_GLOBAL_HOOK__ || {}) // 3. 页面跑的 Vue 是哪个版本项目把 Vue 挂到全局才有 window.Vue window.Vue.version // 4. 有没有多份 Vue 的痕迹看看根节点上挂的实例 id document.querySelector(#app) document.querySelector(#app).__vue__观察结果最可能的原因处理动作钩子为 undefined扩展被禁用或当前页面对扩展不可见检查管理页状态打开文件网址权限钩子存在但字段为空生产构建没认领钩子换开发服务器调试或临时用开发模式构建钩子有字段面板仍空白扩展到框架的协议不匹配确认 Vue 大版本必要时换面板版本组件树不对/重复页面里有多份 Vue检查依赖去重和 alias 配置面板压根没这个标签被折叠、或者扩展加载失败展开重新加载扩展后刷新页面顺一句题外话在控制台里粘贴来源不明的代码之前先读懂它浏览器自己都会弹一句警告提醒你。调试工具权限很大这个习惯该养。6. 装好之后值得花十分钟配的几件事6.1 从组件树一键跳到源码面板里选中一个组件右上角有跳转到编辑器的入口但默认是不通的需要手动配置编辑器路径和项目根路径。配好之后排查组件时的效率提升非常明显你从组件树里点到某个组件直接就到对应的.vue文件那一行不用再靠组件名去全局搜索。配置的关键点是项目根路径要填对填成子目录会导致定位偏移路径不对的时候点击会报找不到文件这时候先检查根路径而不是怀疑扩展坏了。6.2 用 $vm0 直接操作组件以及改了为什么没用在 Elements 里选中一个 DOM 元素然后切到 Vue 面板点一下定位按钮控制台里会出现一个$vm0变量它指向这个 DOM 对应的组件实例。有了它你可以直接读$vm0.$data、调$vm0.someMethod()、甚至改一个值看页面反应。这比在代码里插一堆打印舒服太多。但有两个坑必须说清楚。第一面板里改数据是真实生效的改了页面就变但它只存在于当前运行时刷新就没了所以别指望改完就能顺手提个 PR还是得回代码里改。第二生产构建下这套操作是无效的因为实例注册根本没发生$vm0会一直是 undefined这不是面板的锅。6.3 把安装步骤固化进项目文档这件事看着琐碎收益却最高。我现在的习惯是在项目仓库根目录放一个简短的调试环境说明写清楚三件事本项目的 Vue 大版本、应该用哪个版本的调试面板、以及扩展的获取方式和加载步骤如果是离线包把包放在内部制品库的固定地址上。新同学接手老项目的时候按这个文档五分钟能把面板跑起来没有这份文档每个人都得自己撞一遍扩展是灰的面板没出来提示未检测到这三堵墙。版本号也写死别写用最新版半年后你根本不知道当时是什么环境截图对不上的时候会很被动。如果你手上正好有内网环境要交付建议顺带把构建好的扩展目录整份打个压缩包存档附上构建时的 Node 版本和 tag 名。我吃过这个亏一年后要复现一个老 bug源码还在但当时用的构建环境已经找不回来了重新拉依赖折腾了小半天才生出一样的产物。