knip

Knip 代码清理

运行 knip，查找并移除此代码库中未使用的文件、依赖项和导出项。

设置

1. 检查 knip 是否可用：

   • 运行 npx knip --version 进行测试
   • 如果失败或耗时很长，检查 package.json 的 devDependencies 中是否有 knip
   • 如果本地未安装，请使用 npm install -D knip 安装（或根据现有锁文件使用 pnpm/yarn/bun 对应的命令）

2. Knip 不会移除文件中未使用的导入项或变量——这是代码检查工具的工作。Knip 会查找项目中未使用的文件、依赖项和导出项。

工作流

始终遵循此配置优先工作流。即使是简单的“运行 knip”或“清理代码库”请求，也要先正确配置 knip，再处理它报告的问题。

步骤 1：了解项目

• 检查项目使用的框架和工具（查看 package.json）
• 检查是否存在 knip 配置（knip.json、knip.jsonc 或 package.json 中的 knip 键）
• 如果存在配置，请根据下方的配置最佳实践检查是否有改进空间

步骤 2：运行 knip，并先阅读配置提示

npx knip

优先关注配置提示。这些提示会出现在输出的顶部，并建议调整配置以减少误报。

步骤 3：通过调整 knip.json 处理提示

处理报告的问题之前，先修复配置提示。常见调整包括：

• 为检测到的框架启用或停用插件
• 为非标准入口点添加入口模式
• 为单体仓库配置工作区设置

步骤 4：重复步骤 2～3

每次更改配置后都重新运行 knip。重复此过程，直到解决配置提示并尽可能减少误报。

步骤 5：处理实际问题

配置确定后，逐一处理报告的问题。按以下顺序优先处理：

1. 未使用的文件——优先处理（“清空收件箱”方法可减少最多噪声）
2. 未使用的依赖项——从 package.json 中移除
3. 未使用的 devDependencies——从 package.json 中移除
4. 未使用的导出项——移除或标记为内部使用
5. 未使用的类型——移除，或配置 ignoreExportsUsedInFile（见下文）

步骤 6：重新运行并重复

每批修复后都重新运行 knip。移除未使用的文件通常会暴露出新出现的未使用导出项和依赖项。

配置最佳实践

检查或创建 knip 配置时，请遵循以下规则：

• 绝不要使用 ignore 模式——ignore 会隐藏真实问题，几乎不应该使用。始终优先采用有针对性的解决方案。其他 ignore* 选项（如 ignoreDependencies、ignoreExportsUsedInFile）可以使用，因为它们针对特定的问题类型。
• 存在许多未使用的导出类型？ 添加 ignoreExportsUsedInFile: { interface: true, type: true }——这适用于类型仅在同一文件中使用的常见情况。相比范围更广的 ignore 选项，应优先使用此设置。
• 移除冗余模式——Knip 已遵循 .gitignore，因此忽略 node_modules、dist、build、.git 是多余的。
• 移除被默认配置涵盖的入口模式——自动检测的插件已添加标准入口点。不要重复添加。
• 配置文件被标记为未使用（例如 vite.config.ts）——明确启用或停用对应的插件，而不是忽略该文件。
• 与 Node.js 内置模块同名的依赖项（例如 buffer、process）——添加到 ignoreDependencies。
• 路径别名导致导入无法解析——在 knip 配置中添加 paths（采用 tsconfig.json 语义）。

生产模式

使用 --production，仅检查生产代码：

npx knip --production

这会排除测试文件、配置文件和其他非生产入口点。不要使用 project 或 ignore 模式来排除测试文件——应改用 --production。

清理置信度级别

自动删除（高置信度）：

• 明确属于内部内容（不属于公共 API）的未使用导出
• 未使用的类型导出
• 未使用的依赖项（从 package.json 中删除）
• 明确已无关联的未使用文件（不是入口点，也不是配置文件）

先询问（需要澄清）：

• 可能是入口点或动态导入的文件
• 可能属于公共 API 的导出（index.ts、lib 导出）
• 可能通过 CLI 或对等依赖项使用的依赖项
• 路径中包含 src/index、lib/，或文件名中包含 "public" 或 "api" 的任何内容

删除这些内容前，请使用 AskUserQuestion 工具进行澄清。

自动修复

配置确定且你对结果有信心后：

# Auto-fix safe changes (removes unused exports and dependencies)
npx knip --fix

# Auto-fix including file deletion
npx knip --fix --allow-remove-files

仅当配置优先工作流完成后，才使用 --fix。

错误处理

如果 knip 以代码 2 退出（出现“error loading file”等意外错误）：

• 检查是否存在配置文件；如果不存在，请在项目根目录创建 knip.json
• 在 knip.dev 查看已知问题
• 检查配置参考，确认语法和选项没有错误
• 修复后再次运行 knip

常用命令

# Basic run
npx knip

# Production only (excludes test/config entry points)
npx knip --production

# Auto-fix what's safe
npx knip --fix

# Auto-fix including file deletion
npx knip --fix --allow-remove-files

# JSON output for parsing
npx knip --reporter json

注意事项

• 留意 monorepo 设置——可能需要使用 --workspace 标志
• 某些框架需要在配置中启用插件
• Knip 不会处理文件内部未使用的导入/变量；请使用 ESLint 或 Biome 处理