清理 JS/TS 项目死代码：用 knip…

在 JavaScript/TypeScript 项目中清理未使用文件、依赖和导出时，先正确配置 knip，再按优先级修复并自动删除安全项。

适用场景

解决思路

1. 检查 knip 是否可用：运行 `npx knip --version`；如果失败或很慢，检查 `package.json` 的 `devDependencies` 中是否有 `knip`。
2. 如果未在本地安装，根据存在的 lockfile 使用 `npm install -D knip`（或 pnpm/yarn/bun 的等价命令）安装。
3. 明确 knip 不负责移除文件内部的未使用 import/变量，那是 linter 的职责；knip 只查找项目级未使用文件、依赖和导出。
4. 即使是简单的“运行 knip”或“清理代码库”提示，也始终先按 configuration-first 工作流配置 knip，再处理报告的问题。
5. 检查项目使用哪些框架和工具：查看 `package.json`。
6. 检查是否已有 knip 配置：`knip.json`、`knip.jsonc` 或 `package.json` 中的 `knip` 键。
7. 如果配置已存在，按 Configuration Best Practices 审查它是否可改进。
8. 运行 `npx knip`，并优先阅读输出顶部的 configuration hints，这些提示会建议调整配置以减少误报。
9. 先按 configuration hints 调整 `knip.json`；常见调整包括：为检测到的框架启用/禁用插件、为非标准入口点添加 entry patterns、为 monorepo 配置 workspace 设置。
10. 每次配置变更后重新运行 knip，重复步骤 2-3，直到 configuration hints 解决且误报最少。
11. 配置稳定后处理实际 issues，按此优先级：先处理未使用文件（采用 inbox zero 方式去除最多噪音），再处理未使用 dependencies 并从 `package.json` 移除，再处理未使用 devDependencies 并从 `package.json` 移除，再处理未使用 exports（移除或标记为 internal），最后处理未使用 types（移除或配置 `ignoreExportsUsedInFile`）。
12. 每批修复后重新运行 knip；移除未使用文件常会暴露新的未使用 exports 和 dependencies。
13. 永远不要使用 `ignore` patterns；`ignore` 会隐藏真实问题，几乎不应使用，始终优先具体解决方案；其他 `ignore*` 选项（如 `ignoreDependencies`、`ignoreExportsUsedInFile`）可以，因为它们针对特定问题类型。
14. 如果有很多未使用导出类型，添加 `ignoreExportsUsedInFile: { interface: true, type: true }`，处理仅在同一文件中使用的常见类型场景；优先于更宽泛的 ignore 选项。
15. 移除冗余 patterns：knip 已尊重 `.gitignore`，所以忽略 `node_modules`、`dist`、`build`、`.git` 是冗余的。
16. 移除默认已覆盖的 entry patterns；自动检测插件已添加标准入口点，不要重复添加。
17. 配置文件显示为未使用（如 `vite.config.ts`）时，显式启用或禁用对应插件，而不是忽略该文件。
18. 依赖匹配 Node.js 内置模块（如 `buffer`、`process`）时，将其加入 `ignoreDependencies`。
19. 路径别名导致 unresolved imports 时，向 knip 配置添加 `paths`（使用 tsconfig.json 语义）。
20. 使用 `npx knip --production` 只关注生产代码，它会排除测试文件、配置文件和其他非生产入口点。
21. 不要用 `project` 或 `ignore` patterns 排除测试文件；用 `--production` 代替。
22. 高置信度自动删除项：明显是内部的未使用 exports（不属于 public API）、未使用 type exports、未使用 dependencies（从 `package.json` 移除）、明显孤立的未使用文件（不是入口点、不是配置文件）。
23. 先询问再删除项：可能是入口点或动态导入的文件；可能属于 public API 的 exports（`index.ts`、`lib exports`）；可能通过 CLI 或 peer dependencies 使用的 dependencies；路径如 `src/index`、`lib/` 或文件名含 `public` 或 `api` 的内容；删除前用 AskUserQuestion 工具澄清。
24. 配置稳定且对结果有信心后自动修复：`npx knip --fix` 自动修复安全变更（移除未使用 exports 和 dependencies）。
25. `npx knip --fix --allow-remove-files` 自动修复并包括文件删除。
26. 仅在 configuration-first 工作流完成后才使用 `--fix`。
27. 如果 knip 以退出码 2 结束（意外错误如 `error loading file`）：检查配置文件是否存在，不存在则在项目根目录创建 `knip.json`。
28. 如果 knip 以退出码 2 结束，检查 `knip.dev` 上的已知问题。
29. 如果 knip 以退出码 2 结束，查看 configuration reference 中的语法/选项错误。
30. 修复后再次运行 knip。
31. 基础运行：`npx knip`。
32. 仅生产运行（排除测试/配置入口点）：`npx knip --production`。
33. 自动修复安全项：`npx knip --fix`。
34. 自动修复并删除文件：`npx knip --fix --allow-remove-files`。
35. JSON 输出便于解析：`npx knip --reporter json`。
36. 注意 monorepo 设置，可能需要 `--workspace` 标志。
37. 某些框架需要在配置中启用插件。
38. knip 不处理文件内部未使用 import/变量；用 ESLint 或 Biome 处理。

适用边界 · 注意事项

• 不要用于清理文件内部的未使用 import/变量；那是 ESLint 或 Biome 的职责。
• 不要在未完成 configuration-first 配置流程、未减少误报前直接使用 `--fix` 或删除文件/依赖。
• 不适用于非 JavaScript/TypeScript 项目，或没有 Node/npm 工具链与 `package.json` 的项目。