peerDependencies 冲突是 VSCode 插件启动失败、补全失效、语言服务挂起的常见根因，本质是插件声明的 peerDependencies 版本范围与项目实际安装版本无交集，导致插件运行时 require 失败；需通过 npm ls 验证 UNMET PEER DEPENDENCY，再按升级宿主、降级插件或谨慎使用 --legacy-peer-deps 修复。
peerDependencies 冲突不是 npm 报错就完事了，而是 VSCode 插件启动失败、补全失效、语言服务挂起的常见根因——根本在于插件声明的 peerDependencies 范围和你项目里实际装的版本不重叠。
为什么 VSCode 插件会卡在 peerDependencies 上
VSCode 插件（尤其是语言服务器类，比如 Volar、Pylance、ESLint）通常不把宿主框架（如 vue、react、typescript）打进 .vsix 包，而是靠 peerDependencies 声明“我需要你项目里有某个版本的 typescript”。npm v7+ 会在安装时校验这个范围，一旦不满足，就拒绝安装或静默跳过依赖解析。
- 典型现象：插件状态栏显示 “Activating…” 卡住、输出面板里看不到
Starting language server日志、Developer: Show Running Extensions中该插件显示Activation failed - 关键线索：打开终端执行
npm ls typescript或npm ls vue，看输出里有没有UNMET PEER DEPENDENCY提示 - 注意：VSCode 自身不运行
npm install，它只加载已打包好的插件；所以冲突实际发生在你本地项目中——插件运行时去require()宿主包，却找不到匹配版本
如何快速验证是不是 peerDependencies 版本不匹配
别先删插件，先确认你的项目依赖是否真和插件要求对得上。插件的 peerDependencies 声明藏在它的 package.json 里（可通过 ~/.vscode/extensions/xxx/package.json 查看），但更直接的是查官方文档或 GitHub README。
- 例如
Volarv2.x 要求vue@^3.3.0，而你项目是vue@2.7.16→ 直接不激活 - 例如
@typescript-eslint/eslint-plugin插件要求typescript@^5.0.0，但你装的是typescript@4.9.5→ ESLint 语言服务启动失败 - 执行
npm view @volar/vue2 peerDependencies或npm view @volar/vue3 peerDependencies可直接看到官方声明的版本范围 - 用
npm ls --depth=0看当前 workspace 顶层装了哪些包及其版本，再比对插件要求
修复 peerDependencies 冲突的三种实操路径
不是所有冲突都要升级项目，也不是所有插件都必须用最新版。关键是让版本范围交集非空。
- 路径一：升级宿主框架（最稳妥）
执行npm install vue@^3.4.0或npm install typescript@5.4.5，确保满足插件声明的最小版本 - 路径二：降级插件（适合老项目）
查插件历史版本的peerDependencies，比如Volarv1.5.x 支持vue@^2.7.0，那就npm install @volar/vue2@1.5.1，再手动指定插件版本安装（VSCode 扩展面板 → 搜索 Volar → 点右下角 ⋯ → Install Another Version） - 路径三：强制覆盖（慎用）
仅当确认兼容且无副作用时，加--force或--legacy-peer-deps：npm install --legacy-peer-deps。这会让 npm 忽略校验，但可能引发运行时Cannot find module 'vue'或类型错误
容易被忽略的坑：WSL2 / 多 Node 版本 + peerDependencies 的连锁反应
你在 WSL2 里用 nvm 切了 node@20.14.0，但 VSCode 启动时默认用 Windows 的 node@18.17.0，导致插件加载时读到的 typescript 版本和你 npm ls 看到的不一致——这是真实发生的隐性断裂点。
- 验证方式：在 VSCode 终端里运行
which node和node -v，对比你命令行里看到的结果 - 修复动作：在 VSCode 设置里搜
terminal.integrated.defaultProfile.linux，确保指向 WSL2 的 shell；或在settings.json加"terminal.integrated.env.linux": { "PATH": "/home/xxx/.nvm/versions/node/v20.14.0/bin:${env:PATH}" } - 额外提醒：某些插件（如旧版
ms-python.python）会硬编码调用python -m mypy，如果 Python 环境里没装对应版本的mypy，也会表现为peerDependencies类似症状——本质都是运行时依赖链断裂
