knip-dead-code

Knip 死代码检测

Knip 是一款全面的工具，可用于查找 JavaScript 和 TypeScript 项目中未使用的代码、依赖项和导出项。它有助于保持代码库整洁，并在死代码不断累积前发现它们。

Knip 查找的是静态不可达代码。对于未使用的 CSS（PurgeCSS）、运行时死代码路径、精简打包体积（打包工具的 tree-shaking）或重复依赖项（npm-dedupe），请使用其他工具。

核心能力

什么是 Knip？

• 未使用项检测：文件、依赖项、导出项、类型、枚举成员
• 插件系统：支持 80 多种框架和工具
• 快速：几秒内即可分析大型代码库
• 结果可操作：提供包含文件位置的清晰报告
• 适用于 CI：构建失败时返回退出码

安装

# Project-local (recommended)
bun add --dev knip

# Verify installation
bunx knip --version

基本用法

# Run Knip (scans entire project)
bunx knip

# Show only unused dependencies
bunx knip --dependencies

# Show only unused exports
bunx knip --exports

# Show only unused files
bunx knip --files

# Production mode (only check production dependencies)
bunx knip --production

# Exclude specific issue types
bunx knip --exclude-exports-used-in-file

# Output JSON (for CI)
bunx knip --reporter json

# Debug mode (show configuration)
bunx knip --debug

配置

自动检测（零配置）

Knip 会自动检测：

• 入口点（package.json 中的 main、exports、bin）
• 框架（Next.js、Vite、Remix 等）
• 测试运行器（Vitest、Jest、Playwright）
• 构建工具（ESLint、TypeScript、PostCSS）

标准项目无需配置。

knip.json（显式配置）

{
  "$schema": "https://unpkg.com/knip@latest/schema.json",
  "entry": ["src/index.ts", "src/cli.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["**/*.test.ts", "scripts/**"],
  "ignoreDependencies": ["@types/*"],
  "ignoreBinaries": ["npm-check-updates"]
}

knip.ts（TypeScript 配置）

// knip.ts
import type { KnipConfig } from 'knip';

const config: KnipConfig = {
  entry: ['src/index.ts', 'src/cli.ts'],
  project: ['src/**/*.ts', 'scripts/**/*.ts'],
  ignore: ['**/*.test.ts', '**/*.spec.ts', 'tmp/**'],
  ignoreDependencies: [
    '@types/*', // Type definitions
    'typescript', // Always needed
  ],
  ignoreExportsUsedInFile: true,
  ignoreWorkspaces: ['packages/legacy/**'],
};

export default config;

常见模式

仅检查未使用的依赖项

# Fastest check - only dependencies
bunx knip --dependencies

# Exit with error if any unused dependencies
bunx knip --dependencies --max-issues 0

可在 CI 中使用，以严格管理依赖项。

仅检查导出项（库开发）

# Check for unused exports
bunx knip --exports

# Allow exports used in same file
bunx knip --exports --exclude-exports-used-in-file

适用于库，确保公开 API 整洁。

生产依赖项与开发依赖项

# Check production code only
bunx knip --production

# Check everything (including dev dependencies)
bunx knip

解读结果

输出示例

No unused files
No unused dependencies
2 unused exports

src/utils.ts:
  - calculateTax (line 42)
  - formatDate (line 58)

src/types.ts:
  - UserRole (line 12)

问题类型

类型	描述	操作
未使用的文件	文件未在任何地方导入	删除或添加到入口点
未使用的依赖项	package.json 中的包未被使用	从依赖项中移除
未使用的导出项	已导出但从未导入	移除导出项或设为私有
未使用的类型	导出的类型／接口未被使用	移除或设为内部类型
未使用的枚举成员	从未引用的枚举成员	移除该成员
重复导出项	同一导出项来自多个文件	合并导出项

Agent 化优化

场景	命令
快速扫描	bunx knip
仅检查依赖项	bunx knip --dependencies
仅检查导出项	bunx knip --exports
CI 严格模式	bunx knip --max-issues 0
生产环境检查	bunx knip --production
JSON 输出	bunx knip --reporter json
调试配置	bunx knip --debug
已更改的文件	bunx knip --changed --base main

快速参考

标志	描述
--dependencies	仅检查未使用的依赖项
--exports	仅检查未使用的导出项
--files	仅检查未使用的文件
--production	仅检查生产依赖项
--max-issues N	问题数量超过 N 时失败
--reporter json	为 CI 输出 JSON
--reporter compact	紧凑输出
--debug	显示配置详情
--changed	仅检查已更改的文件
--changed --base main	检查自 main 以来更改的文件
--workspace NAME	检查指定的工作区
--exclude-exports-used-in-file	忽略同一文件中的导出项

如需查看详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。

参考资料

• 官方文档：https://knip.dev
• 配置：https://knip.dev/reference/configuration
• 插件：https://knip.dev/reference/plugins
• CLI 参考：https://knip.dev/reference/cli
• 常见问题：https://knip.dev/reference/faq