Knip 代码清理工具：自动查找并移除未使用的文件、依赖和导出

knip by brianlovin/agent-config

211 周安装量

314 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/brianlovin/agent-config --skill knip

自动化代码质量静态分析

🇨🇳中文介绍

Knip 代码清理

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

设置

检查 knip 是否可用：
- 运行 npx knip --version 进行测试
- 如果失败或非常慢，请检查 knip 是否在 package.json 的 devDependencies 中
- 如果未在本地安装，请使用 npm install -D knip 安装（或根据存在的 lockfile 使用 pnpm/yarn/bun 的等效命令）
Knip 不会移除文件内部未使用的导入/变量——那是 linter 的工作。Knip 查找整个项目中未使用的文件、依赖项和导出。

工作流程

始终遵循这个配置优先的工作流程。即使是简单的“运行 knip”或“清理代码库”提示，也要在根据报告的问题采取行动之前正确配置 knip。

步骤 1：了解项目

检查项目使用了哪些框架和工具（查看 package.json）
检查是否存在 knip 配置（knip.json、knip.jsonc 或 package.json 中的 knip 键）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

在关注其他任何问题之前，先关注配置提示。这些提示出现在输出的顶部，并建议调整配置以减少误报。

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

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

为检测到的框架启用/禁用插件
为非标准入口点添加入口模式
为 monorepo 配置工作区设置

步骤 4：重复步骤 2-3

每次配置更改后重新运行 knip。重复此过程，直到配置提示得到解决且误报最小化。

步骤 5：处理实际问题

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

未使用的文件 — 首先处理这些（“收件箱清零”方法可以消除最多的干扰）
未使用的依赖项 — 从 package.json 中移除
未使用的 devDependencies — 从 package.json 中移除
未使用的导出 — 移除或标记为内部使用
未使用的类型 — 移除，或配置 ignoreExportsUsedInFile（见下文）

步骤 6：重新运行并重复

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

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

切勿使用 ignore 模式 — ignore 会隐藏真正的问题，几乎永远不应该使用。始终优先使用具体的解决方案。其他 ignore* 选项（如 ignoreDependencies、ignoreExportsUsedInFile）是可以的，因为它们针对特定类型的问题。
许多未使用的导出类型？ 添加 ignoreExportsUsedInFile: { interface: true, type: true } — 这处理了类型仅在同一个文件中使用的常见情况。优先使用此选项而非更宽泛的忽略选项。
移除冗余模式 — Knip 已经遵循 .gitignore，因此忽略 node_modules、dist、build、.git 是多余的。
移除默认覆盖的入口模式 — 自动检测的插件已经添加了标准入口点。不要重复它们。
配置文件显示为未使用（例如 vite.config.ts） — 显式启用或禁用相应的插件，而不是忽略该文件。
依赖项匹配 Node.js 内置模块（例如 buffer、process） — 添加到 ignoreDependencies。
来自路径别名的未解析导入 — 将 paths 添加到 knip 配置（使用 tsconfig.json 语义）。

使用 --production 仅关注生产代码：

npx knip --production

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

清理置信度级别

自动删除（高置信度）：

明显是内部使用的未使用导出（不属于公共 API）
未使用的类型导出
未使用的依赖项（从 package.json 中移除）
明显是孤立的未使用文件（非入口点，非配置文件）

先询问（需要澄清）：

可能是入口点或动态导入的文件
可能是公共 API 一部分的导出（index.ts、lib 导出）
可能通过 CLI 或 peer dependencies 使用的依赖项
路径中包含 src/index、lib/ 或文件名中包含“public”或“api”的任何内容

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

一旦配置确定并且对结果有信心：

# 自动修复安全的更改（移除未使用的导出和依赖项）
npx knip --fix

# 自动修复包括文件删除
npx knip --fix --allow-remove-files

只有在配置优先的工作流程完成后才使用 --fix。

如果 knip 以代码 2 退出（意外错误，如“加载文件错误”）：

检查配置文件是否存在 — 如果不存在，在项目根目录创建 knip.json
在 knip.dev 上查看已知问题
审查配置参考以查找语法/选项错误
修复后再次运行 knip

# 基本运行
npx knip

# 仅生产环境（排除测试/配置入口点）
npx knip --production

# 自动修复安全的内容
npx knip --fix

# 自动修复包括文件删除
npx knip --fix --allow-remove-files

# JSON 输出用于解析
npx knip --reporter json

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

🇺🇸English

Knip Code Cleanup

Run knip to find and remove unused files, dependencies, and exports from this codebase.

Setup

Check if knip is available:
- Run npx knip --version to test
- If it fails or is very slow, check if knip is in package.json devDependencies
- If not installed locally, install with npm install -D knip (or pnpm/yarn/bun equivalent based on lockfile present)
Knip does NOT remove unused imports/variables inside files — that's a linter's job. Knip finds unused files, dependencies, and exports across the project.

Workflow

Always follow this configuration-first workflow. Even for simple "run knip" or "clean up codebase" prompts, configure knip properly before acting on reported issues.

Step 1: Understand the project

Check what frameworks and tools the project uses (look at package.json)
Check if a knip config exists (knip.json, knip.jsonc, or knip key in package.json)
If a config exists, review it for improvements (see Configuration Best Practices below)

Step 2: Run knip and read configuration hints first

npx knip

Focus on configuration hints before anything else. These appear at the top of the output and suggest config adjustments to reduce false positives.

Step 3: Address hints by adjusting knip.json

Fix configuration hints before addressing reported issues. Common adjustments:

Enable/disable plugins for detected frameworks
Add entry patterns for non-standard entry points
Configure workspace settings for monorepos

Step 4: Repeat steps 2-3

Re-run knip after each config change. Repeat until configuration hints are resolved and false positives are minimized.

Step 5: Address actual issues

Once the configuration is settled, work through reported issues. Prioritize in this order:

Unused files — address these first ("inbox zero" approach removes the most noise)
Unused dependencies — remove from package.json
Unused devDependencies — remove from package.json
Unused exports — remove or mark as internal
Unused types — remove, or configure ignoreExportsUsedInFile (see below)

Step 6: Re-run and repeat

Re-run knip after each batch of fixes. Removing unused files often exposes newly-unused exports and dependencies.

Configuration Best Practices

When reviewing or creating a knip config, follow these rules:

Never useignore patterns — ignore hides real issues and should almost never be used. Always prefer specific solutions. Other ignore* options (like ignoreDependencies, ignoreExportsUsedInFile) are fine because they target specific issue types.
Many unused exported types? Add ignoreExportsUsedInFile: { interface: true, type: true } — this handles the common case of types only used in the same file. Prefer this over broader ignore options.
Remove redundant patterns — Knip already respects .gitignore, so ignoring node_modules, dist, , is redundant.

Production Mode

Use --production to focus on production code only:

npx knip --production

This excludes test files, config files, and other non-production entry points. Do NOT use project or ignore patterns to exclude test files — use --production instead.

Cleanup Confidence Levels

Auto-delete (high confidence):

Unused exports that are clearly internal (not part of public API)
Unused type exports
Unused dependencies (remove from package.json)
Unused files that are clearly orphaned (not entry points, not config files)

Ask first (needs clarification):

Files that might be entry points or dynamically imported
Exports that might be part of a public API (index.ts, lib exports)
Dependencies that might be used via CLI or peer dependencies
Anything in paths like src/index, lib/, or files with "public" or "api" in the name

Use the AskUserQuestion tool to clarify before deleting these.

Auto-fix

Once configuration is settled and you're confident in the results:

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

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

Only use --fix after the configuration-first workflow is complete.

Error Handling

If knip exits with code 2 (unexpected error like "error loading file"):

Check if a config file exists — if not, create knip.json in the project root
Check for known issues at knip.dev
Review the configuration reference for syntax/option errors
Run knip again after fixes

Common Commands

# 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

Notes

Watch for monorepo setups — may need --workspace flag
Some frameworks need plugins enabled in config
Knip does not handle unused imports/variables inside files — use ESLint or Biome for that

Weekly Installs

Repository

brianlovin/agent-config

GitHub Stars

273

First Seen

11 days ago

Security Audits

Gen Agent Trust HubPass SocketWarn SnykPass

Installed on

opencode39

gemini-cli39

github-copilot39

codex39

amp39

cline39

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

46,600 周安装

Remove entry patterns covered by defaults — Auto-detected plugins already add standard entry points. Don't duplicate them.

Config files showing as unused (e.g. vite.config.ts) — Enable or disable the corresponding plugin explicitly rather than ignoring the file.

Dependencies matching Node.js builtins (e.g. buffer, process) — Add to ignoreDependencies.

Unresolved imports from path aliases — Add paths to knip config (uses tsconfig.json semantics).