Qoder插件依赖冲突可由多版本共存引发，需通过npm ls/yarn why定位、overrides/resolutions统一版本、清理重建node_modules、隔离插件依赖及禁用peer依赖注入五步解决。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 Qoder 插件时遇到模块加载失败、运行时报错或功能异常，且错误信息中反复出现同一包的多个版本（如 lodash@4.17.11 与 lodash@4.17.21 并存）、Cannot resolve module 或 peer dep missing 提示，则很可能是由 node_modules 中的依赖版本纠纷导致。以下是手动管理 node_modules 解决此类冲突的多种方法：
一、执行依赖树诊断与冲突定位
在干预前必须明确冲突源头：哪些包引入了不兼容版本？冲突是否集中在某一个间接依赖路径？盲目删除或覆盖可能破坏功能链路。使用标准化工具快速提取结构化信息，避免人工翻查 package-lock.json 的低效方式。
1、在项目根目录终端中运行：
npm ls lodash --depth=5
2、若使用 Yarn，则执行：
yarn why lodash
3、观察输出中是否出现多条不同路径指向不同版本，例如：
├─ qoder-core@1.2.0 → lodash@4.17.11
└─ @qoder/agent-runtime@0.8.3 → react-slick@0.29.0 → @types/react@18.0.27 → lodash@4.17.21
4、记录下引发冲突的顶层依赖名（如 @qoder/agent-runtime）及其所拉取的冲突子依赖全路径。
二、强制统一版本：通过 overrides/resolutions 声明式覆盖
该方法不修改 node_modules 文件系统，而是通过包管理器原生机制在解析阶段重写依赖版本映射，确保整个树中仅存在一个指定版本实例，且 lock 文件可追溯、CI 可验证。
1、打开项目根目录下的 package.json 文件。
2、在根对象中添加 overrides 字段（npm v8.3+）：
{"overrides": {"lodash": "4.17.21"}}
3、若使用 Yarn v1/v3+，则添加 resolutions 字段：
{"resolutions": {"lodash": "4.17.21"}}
4、保存文件后，删除 package-lock.json（npm）或 yarn.lock（Yarn）。
5、重新执行：
npm install
或
yarn install
6、再次运行 npm ls lodash，确认输出中仅显示单一版本且路径全部归一至顶层。
三、手动清理嵌套冗余：重建扁平化 node\_modules
当 lock 文件残留旧版本引用、或混合使用过多种包管理器导致结构污染时，需彻底清除并重建依赖目录，强制触发现代包管理器的扁平化策略，消除深层嵌套带来的隐式多版本共存。
1、关闭所有正在运行的 Qoder CN IDE 实例及关联进程（包括后台 Node 子进程）。
2、在项目根目录执行：
rm -rf node_modules package-lock.json
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
3、若为 Windows 系统，则执行：
rd /s/q node_modules
del package-lock.json
4、清空 npm 缓存（防止缓存中损坏包被复用）：
npm cache clean --force
5、重新安装全部依赖：
npm install --no-package-lock --legacy-peer-deps
6、安装完成后，检查 node_modules/lodash 是否仅存在一个文件夹，且其 package.json 中 version 字段与 overrides 指定值一致。
四、隔离插件依赖：启用独立 node\_modules 分区
Qoder CN 插件通常以独立模块形式集成于 JetBrains IDE 中，其运行时可能加载宿主项目 node_modules，也可能加载自身内嵌依赖。当插件自带的 node_modules 与项目依赖发生命名空间碰撞时，需将其物理隔离，避免模块解析顺序干扰。
1、进入 Qoder CN 插件安装目录（JetBrains 默认路径示例）：
Windows：C:\Users\[用户名]\AppData\Roaming\JetBrains\IntelliJIdea2023.3\plugins\qoder\
macOS：~/Library/Caches/JetBrains/IntelliJIdea2023.3/plugins/qoder/
2、查找是否存在 node_modules 子目录；若存在，重命名为 node_modules.bak。
3、在该插件目录下新建空文件夹：qoder-external-deps。
4、将插件实际运行所需的最小依赖集（如 axios@1.6.8、semver@7.6.0）单独安装至此目录：
cd qoder-external-deps && npm init -y && npm install axios@1.6.8 semver@7.6.0
5、在插件配置文件（如 plugin.xml 或环境变量注入脚本）中，通过 NODE_PATH 显式指向该目录：
NODE_PATH=/path/to/qoder-external-deps/node_modules
五、禁用自动 peer 依赖注入：规避宿主项目干扰
部分 Qoder 插件（尤其是涉及 React UI 组件或 MCP 服务桥接的模块）会声明 peerDependencies，期望由宿主项目提供对应版本。但若宿主未安装或版本不匹配，插件内部模块解析器可能回退至 node_modules 深层嵌套路径，意外加载错误版本。
1、在项目根目录创建临时配置文件：.qoderignore。
2、在该文件中逐行列出需屏蔽的 peer 依赖名：
react
react-dom
@types/react
3、启动 Qoder CN 前，在终端中设置环境变量：
export QODER_IGNORE_PEERS=true
4、启动 IDE 后，检查插件日志中是否不再出现 Missing peer dependency 警告，且相关功能模块加载路径变为插件内置副本（如 qoder-core/dist/react-shim.js）。
