Adonis0123 Code Inspector Init
Overview
在开发环境为前端项目接入 code-inspector-plugin，实现按组合键后点击 DOM 跳转到源码位置。优先给出最小改动、可复制、可回滚的迁移方案，默认使用插件原生开关策略：needEnvInspector: true + .env.local 中设置 CODE_INSPECTOR=true；但 Next.js >=15.3 主模板默认使用 hotKeys: ["altKey"] + needEnvInspector: false。
Trigger Phrases
- 帮我接入
code-inspector-plugin - 帮我迁移
codeInspectorPlugin到新项目 - Next.js/Vite/Webpack 怎么配 code inspector
- 点击页面元素跳不到 IDE
- Alt+Shift 没反应 / 快捷键怎么改
Decision Tree
- 识别框架与 bundler。
- 从
package.json、配置文件名、构建命令确认是 Next.js、Vite、Webpack、Rspack、Rsbuild、Esbuild、Mako、Umi、Nuxt、Astro 中哪一种。
- 如果是 Next.js，先判断版本区间。
<=14.x：使用 webpack 插件接入。15.0.x ~ 15.2.x：使用experimental.turbo.rules。>=15.3.x（包含 16）：使用turbopack.rules。
- 选择开关策略。
- 默认：
needEnvInspector: true（推荐，迁移一致性最好）。 - Next.js
>=15.3主模板特例：默认needEnvInspector: false，并使用hotKeys: ["altKey"]做最小接入。 - 用户明确要求项目自定义开关时，再补充
ENABLE_CODE_INSPECTOR等外层条件。
- 判断是否需要高级选项。
- 只有用户明确提出需求才调整
hotKeys、hideConsole、openIn、launchType、include/exclude、mappings、pathType、skipSnippets。
Execution Workflow
- 识别项目环境。
- 确认框架、bundler、配置文件路径、是否 dev-only 配置。
- 安装依赖。
- 给出单行命令：
pnpm add -D code-inspector-plugin（如项目使用 npm/yarn，则给对应命令）。
- 注入配置。
- 从
references/bundler-recipes.md选择对应片段。 - 配置中必须包含正确的
bundler值。
- 设置
.env.local。
- 仅当模板显式使用
needEnvInspector: true时，添加CODE_INSPECTOR=true。 - 对 Next.js
>=15.3主模板（hotKeys: ["altKey"]+needEnvInspector: false）不强制配置.env.local。
- 本地验证。
- 启动 dev。
- 在页面按默认组合键（多数模板为 Mac:
Option+Shift/ Windows:Alt+Shift；Next.js>=15.3主模板为Option/Alt单键）后悬浮并点击 DOM。 - 观察浏览器控制台提示和 IDE 跳转结果。
- 故障排查。
- 出现 IDE 无法打开、快捷键无效、路径错误、端口冲突时，按
references/troubleshooting.md分步排查。
Reference Routing
- 需要框架配置代码片段时：读取
references/bundler-recipes.md。 - 需要定制参数与风险评估时：读取
references/options-cheatsheet.md。 - 需要排障步骤时：读取
references/troubleshooting.md。 - 不要一次性加载全部 references，只按当前请求场景读取对应文件。
Output Contract
输出必须严格包含以下四部分，且顺序固定：
- 改动点清单
- 说明要改哪些文件、每个文件做什么。
- 可复制代码块
- 给完整可用的配置片段，不给伪代码。
- 代码块里保留英文 API 名与配置键。
- 验证命令
- 提供可直接执行的单行命令。
- 给出成功判定标准。
- 回滚说明
- 说明如何移除插件配置和环境变量。
Guardrails
- 默认只在开发环境启用，不在生产构建开启 inspector。
- 修改保持最小化，不顺带重构无关代码。
- 不确定框架版本时，先读取
package.json与 lockfile 再下结论。 - 涉及
node_modules源码映射时，优先使用mappings且给出风险说明。