Knip 完全指南：检测并修复 JS/TS 项目中未使用的依赖、导出与文件

代码质量静态分析CLI【免费下载链接】knip✂️ Find unused files, dependencies and exports in your JavaScript and TypeScript projects. Knip it before you ship it!项目地址https://gitcode.com/gh_mirrors/kn/knip点击查看免费下载Knip发音 /knɪp/荷兰语意为 (to) cut重音在硬 K是一款面向 JavaScript 与 TypeScript 项目的静态分析工具用于查找并修复未使用的依赖unused dependencies、未使用的导出unused exports与未使用的文件unused files。更少的代码与依赖意味着更快的构建、更低的维护成本与更安全的重构。本文以本仓库webpro-nl/knip 的镜像为对象从安装配置、CLI 参数、配置项语义到源码实现与 CI 集成系统讲解如何把 Knip 真正用起来。一、核心主张Knip 到底做什么仓库根 README.md 对项目定位只有一句话却是全项目的主干Knip finds and fixes unused dependencies, exports and files。其价值主张可以拆解为三点Less code删除未被引用的文件与导出缩小代码面Less dependencies清理package.json中未被真实使用的依赖减小安装体积与供应链面Easier refactorings当你知道某个导出没有任何使用者时可以放心删除或修改它。项目整体为 pnpm workspace 单体仓库见 package.json核心包packages/knip之外还维护了knip/create-config初始化脚手架、knip/language-server语言服务器、knip/mcpMCP 服务器以及 VS Code 扩展vscode-knip构成从 CLI 到编辑器、再到 AI Agent 的完整工具链。二、安装与首次运行2.1 推荐方式create-config 脚手架knip/create-config会一次性完成安装并把 Knip 及其 peer 依赖加入devDependencies同时向package.json写入knip脚本参考 packages/create-config/README.mdnpm init knip/config # npm pnpm create knip/config # pnpm bun create knip/config # bun yarn create knip/config # yarn安装完成后package.json中会出现如下内容{ name: my-package, scripts: { knip: knip }, devDependencies: { types/node: ^20.14.8, knip: ^5.30.1, typescript: ^5.5.4 } }随后运行npm run knip或pnpm knip/bun knip/yarn knip即可开始扫描项目。2.2 手动安装Knip 使用typescript与types/node作为 peer 依赖以保持与你项目的 TypeScript 版本兼容npm install -D knip typescript types/node再向package.json添加脚本knip: knip。注意Knip v6 要求 Node.js v20.19.0 或更高版本或使用 Bun本仓库根package.json的engines字段要求node 22.0.0实际以你所安装版本发布的引擎要求为准。2.3 免安装体验不想把 Knip 加入项目时可直接用包管理器执行npx knip # npm pnpm dlx knip # pnpm bunx knip # bun此场景下typescript与types/node需要已存在于项目的node_modules中。2.4 运行流程与退出码从 packages/knip/src/cli.ts 可以看到 CLI 的完整主流程解析参数 →createOptions合并配置 →run()执行扫描 → 预处理结果 → 需要时调用fix()自动修复 →runReporters输出报告 → 根据结果设置退出码存在配置加载错误退出码2问题总数超过--max-issues默认0或配置提示/标签提示被设为错误退出码1一切正常退出码0。这意味着 Knip 天然适合接入 CI——非零退出码即可让流水线失败。三、问题类型全景17 种可检测的 IssueKnip 的能力不仅限于依赖、导出、文件三大类。在 packages/knip/src/constants.ts 的ISSUE_TYPES与ISSUE_TYPE_TITLE中定义了完整的报告分组问题类型报告标题含义filesUnused files未被任何入口可达的文件dependenciesUnused dependenciesdependencies中未被使用的包devDependenciesUnused devDependenciesdevDependencies中未被使用的包optionalPeerDependenciesReferenced optional peerDependencies被引用的可选 peer 依赖unlistedUnlisted dependencies源码用到但未声明在package.json的依赖binariesUnlisted binaries脚本用到但未声明的二进制命令unresolvedUnresolved imports无法解析的导入路径exportsUnused exports未被引用的导出值nsExportsExports in used namespace被使用的命名空间中的导出typesUnused exported types未使用的导出类型nsTypesExported types in used namespace被使用的命名空间中的导出类型enumMembersUnused exported enum members未使用的导出枚举成员namespaceMembersUnused exported namespace members未使用的导出命名空间成员duplicatesDuplicate exports重复导出catalogUnused catalog entries未使用的 pnpm catalog 条目catalogReferencesUnresolved catalog references无法解析的 catalog 引用cyclesCircular dependencies循环依赖默认排除动态import()边在检测不同语法形态时符号被分为class、enum、function、interface、member、namespace、type、variable等类型见SYMBOL_TYPE这也解释了为什么ignoreExportsUsedInFile等选项可以按符号类型做细粒度配置。四、配置文件位置、结构与本仓库实战4.1 配置文件查找顺序Knip 会自动按以下位置查找配置见 packages/knip/src/constants.ts 的KNIP_CONFIG_LOCATIONS也可通过-c, --config显式指定knip.json → knip.jsonc → .knip.json → .knip.jsonc knip.ts → knip.js → knip.config.ts → knip.config.js package.json#knipJSON 格式建议使用$schema字段以获得 IDE 校验与补全.json用schema.json支持注释与尾逗号的.jsonc用schema-jsonc.json两个 schema 文件位于 packages/knip/){ $schema: https://unpkg.com/knip6/schema.json }4.2 核心配置项以下配置项的字段定义、默认值与示例均可在 packages/knip/src/schema/configuration.ts 的 zod schema 注释中找到是权威参考entry入口文件 glob 数组支持!取反。Knip 从入口出发做引用分析因此入口决定了哪些文件可达。示例[src/index.ts, scripts/*.ts, !scripts/except-this-one.ts]project参与分析的项目文件 glob未被匹配的文件不会进入扫描范围paths模块路径别名。TypeScript 的compilerOptions.paths会被自动读取其他别名需手动配置遵循 TS 语义值为相对路径数组无*的为精确匹配{ lib: [./lib/index.ts], lib/*: [./lib/*] }ignore按 glob 忽略匹配文件中的所有问题类型与ignoreFiles有本质区别见下ignoreFiles仅从 Unused files 报告中排除匹配文件文件仍会参与依赖、导出等其他分析ignoreBinaries忽略脚本中用到但无依赖提供、且确实全局可用的二进制名支持正则[zip, docker-compose, pm2-.]ignoreDependencies从报告中排除的包名支持正则[hidden-package, org/.]ignoreMembers/ignoreUnresolved分别忽略枚举/命名空间成员与无法解析的 specifierignoreExportsUsedInFile默认false文件内既被导出又被内部使用的符号不再上报为未使用导出可整体开启或按符号类型细粒度配置{ interface: true, type: true }ignoreIssues按文件 glob 忽略指定问题类型适合放行生成代码中的特定告警cycles循环依赖检测配置dynamicImports控制是否包含动态import()边allow可放行精确路径环ignoreWorkspaces忽略的工作区 globincludeEntryExports默认false自包含/私有仓库可开启让入口文件中的未使用导出也被上报同时启用导出类/枚举成员检测compilers覆盖内置编译器或为额外文件类型注册自定义编译器tags通过 JSDoc/TSDoc 标签如internal、lintignore过滤导出tag只报告带该标签的导出-tag排除带该标签的导出preprocessor/preprocessorOptions在报告前对结果做自定义预处理treatConfigHintsAsErrors/treatTagHintsAsErrors默认false存在配置/标签提示时以非零码退出include/exclude按问题类型过滤报告范围。4.3 工作区配置与本仓库自检示例在 monorepo 中可为每个 workspace 单独配置entry、project、paths、各类ignore*与插件配置。本仓库根 knip.json 就是 Knip 用 Knip 检查自身的真实范例{ $schema: https://unpkg.com/knip6/schema.json, workspaces: { .: { project: [!templates] }, packages/knip: { entry: [test/**/*.ts], project: [src/**/*.ts!, !src/util/empty.ts, !**/_template], ignoreDependencies: [prettier] }, packages/docs: { entry: [{plugins,scripts}/*.ts] }, packages/vscode-knip: { entry: [src/index.js!, scripts/*.js, test/*.mjs], project: [**!, !test/fixtures], ignoreBinaries: [vsce, ovsx] } } }从中可以学到几个实战技巧用entry: [...!]让某个入口同时匹配扩展名变体用project: [src/**/*.ts!]表示src 下所有 TS 文件及其同形扩展对测试目录、生成文件、脚手架模板用!取反排除对全局可用的发布工具如vsce、ovsx用ignoreBinaries放行。五、CLI 全参数参考完整参数列表定义在 packages/knip/src/util/cli-arguments.ts 的helpText与parseCLIArgs中分类整理如下分类参数说明基础-h, --help/-V, --version帮助 / 版本-c, --config [file]指定配置文件路径-t, --tsConfig [file]指定 tsconfig默认tsconfig.json--use-tsconfig-files用 tsconfig 定义项目文件覆盖project模式-n, --no-progress关闭动态进度CI 中自动启用模式--cache/--cache-location启用缓存默认位置node_modules/.cache/knip--include-entry-exports报告入口文件中的未使用导出--no-gitignore不遵循.gitignore-p, --production仅分析生产源码排除测试文件、devDependencies-s, --strict只考虑工作区直接依赖不含 devDependencies 与其他工作区-w, --watch监听模式范围-W, --workspace [filter]按名称/目录/glob 过滤工作区可重复-D, --directory [dir]从其他目录运行默认 cwd--include/--exclude按问题类型包含/排除可逗号分隔或重复--dependencies/--exports/--files/--cycles上述过滤的快捷方式--tags包含或排除带标签的导出修复-f, --fix自动修复会修改仓库文件--fix-type只修复指定类型可修复类型dependencies, exports, types, files, catalog--allow-remove-files允许--fix删除文件-F, --format修复后用本地格式化工具格式化改动文件输出--preprocessor/--preprocessor-options报告前预处理结果--reporter/--reporter-options选择报告器可重复--no-config-hints/--no-tag-hints关闭配置/标签提示--treat-config-hints-as-errors/--treat-tag-hints-as-errors提示视为错误退出--max-issues问题总数超过该值则非零退出默认 0--max-show-issues每类问题最多显示条数--no-exit-code始终以 0 退出调试-d, --debug调试输出--memory/--memory-realtime测量/实时输出内存--performance/--performance-fn [name]关键函数耗时统计-u, --duration打印总耗时零开销--trace/--trace-dependency [name]/--trace-export [name]/--trace-file [file]追踪导出/依赖/文件的使用链常用命令示例同样出自helpTextknip knip --production knip --workspace packages/client --include files,dependencies knip --workspace myorg/* --workspace !myorg/legacy knip --workspace ./apps/* --workspace shared/utils knip -c ./config/knip.json --reporter compact knip --reporter codeowners --reporter-options {path:.github/CODEOWNERS} knip --tags-lintignore内置报告器内置报告器包括symbols默认、compact、codeowners、cycles、json、codeclimate、markdown、disclosure、github-actions、sarif。例如github-actions报告器可直接在 CI 中输出带注解的问题定位json报告器便于对接自定义流水线。六、自动修复与编辑器/Agent 生态6.1 --fix 自动修复--fix会直接修改仓库文件移除未使用的依赖声明、未使用的导出、未使用的文件等可修复类型限定为dependencies、exports、types、files、catalog。配合--fix-type限定范围、--allow-remove-files允许删除文件、--format在修复后用本地格式化器整理代码。修复流程在 packages/knip/src/IssueFixer.ts 中实现由cli.ts在报告前调用--fix模式下同样支持 watch/其他特殊模式的独立处理。6.2 语言服务器与 MCPKnip 不只是 CLI官方还提供knip/language-serverpackages/language-server实现诊断、代码动作等语言服务器能力是 VS Code 扩展的诊断后端测试覆盖见packages/language-server/test/knip/mcppackages/mcp-server提供 MCPModel Context Protocol服务器让编码 Agent 直接调用 Knip 的检查、修复能力vscode-knippackages/vscode-knipVS Code 扩展可在 Marketplace 与 Open VSX 获取提供依赖/导出悬停提示与导入/导出树视图。由此在编辑器中实时看到未使用导出、让 AI Agent 自动生成并维护knip.json都成为开箱即用的能力。七、功能全景与持续集成建议仓库文档 packages/docs/src/content/docs/overview/features.md 给出了一张完整能力表包括auto-fix、cache、catalog 支持、CommonJS 支持、compilersAstro/MDX/Svelte/Vue 及自定义编译器、配置提示、debug、过滤器、format、JSDoc 标签、内存测量、monorepo 一等公民支持、性能分析、超过 100 个插件为各种框架提供入口与配置解析、输入机制、CLI 参数解析、预处理、production 模式、多种报告器、rules、脚本解析、source mapping把dist文件映射回src、strict 模式、trace、watch 模式与 workspace 过滤。落地到 CI 时推荐组合knip --production # 只看生产代码避免测试文件的干扰 knip --reporter compact # 精简输出 knip --no-exit-code # 只报告不失败灰度期 knip --max-issues 10 # 允许一定量存量问题配合--cache可显著加快重复运行的耗时--performance/--memory可在仓库规模很大时辅助定位瓶颈。若希望增量治理先用--no-exit-code或--exclude收敛存量告警再用--max-issues 0严格化。八、License 与致谢Knip 是免费开源软件采用 ISC License。其部分实现受以下项目启发或引用了其代码片段npmcli/package-jsonISC、pnpm/deps.graph-sequencerMIT、file-entry-cacheMIT、json-parse-even-better-errorsMIT。项目由 Lars Kappertwebpro维护仓库根 README.md 对各贡献者表达了感谢。总结Knip 的价值不在一行标语而在于它把未使用的依赖、导出、文件这一维护难题拆解成 17 种可检测、可过滤、可修复的问题类型并通过配置 schema、完整 CLI 参数、--fix自动修复、语言服务器与 MCP 生态让清理工作从手工翻代码变成一条命令 一次审查。无论你维护的是单包项目还是大型 monorepo都可以从本仓库根 knip.json 的自检配置出发为自己的仓库建立一套可持续的整洁度基线。赞分享代码质量静态分析CLI【免费下载链接】knip✂️ Find unused files, dependencies and exports in your JavaScript and TypeScript projects. Knip it before you ship it!项目地址https://gitcode.com/gh_mirrors/kn/knip点击查看免费下载相关推荐如何用Python工具轻松下载B站大会员4K视频解锁充电专属内容的完整指南如何用Python工具轻松下载B站大会员4K视频解锁充电专属内容的完整指南 你是否曾遇到过这样的困扰在地铁上网络不稳定无法观看收藏的视频或者想保存喜欢的U代码质量静态分析CLI上一篇Verified-Smart-Contracts项目技术深度SMT求解器在形式化验证中的作用下一篇SilentPatch for Bully: Scholarship Edition 教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考