depcheck 依赖检测

depcheck是Node.js 项目专属的依赖检测工具，核心作用是静态分析项目代码与package.json，自动找出未使用、缺失、冗余的依赖，解决项目迭代中依赖臃肿（装了没用）、漏装依赖（代码用了但没在package.json声明）、生产 / 开发依赖放错位置等问题，是清理项目依赖、优化package.json的常用工具。

简单说：项目开发久了，常会出现「装了依赖从没用到」「代码里用了某个包但忘了 npm install」的情况，depcheck能一站式检测这些问题，让依赖清单更干净，减少安装耗时和项目体积。

一、depcheck 核心作用

核心围绕package.json的dependencies（生产依赖）、devDependencies（开发依赖）、peerDependencies展开，共 4 个核心能力，都是实际开发中高频刚需：

1. 检测未使用的依赖：找出dependencies/devDependencies里声明了，但项目代码中从未引用的包（最核心功能）；

1. 检测缺失的依赖：找出项目代码中实际用到了，但package.json里未声明（忘了装）的包；

1. 识别冗余的依赖配置：比如peerDependencies里声明了但项目无需的包，或重复声明的依赖；

1. 校验依赖分类：间接提醒是否把开发依赖（如eslint、webpack）误放到生产依赖，或反之。

⚠️ 注意：depcheck是静态分析工具，无法检测运行时动态加载（如require(${变量})）、全局依赖、框架 / 插件自动引入的依赖，可能出现少量误报，后续会讲解决方法。

二、depcheck 基础用法（开箱即用）

1. 安装方式

支持全局安装（推荐，所有项目可直接用）或局部安装（适合项目协作，写入开发依赖），二选一即可：

# 全局安装（推荐，一次安装，所有项目使用） npm install -g depcheck # 或 yarn 全局安装 yarn global add depcheck # 局部安装（项目专属，写入devDependencies，适合团队协作） npm install depcheck --save-dev # 或 yarn 局部安装 yarn add depcheck -D

2. 基础使用（核心命令）

进入Node.js 项目根目录（必须有package.json的目录），直接执行命令即可，无需任何配置：

# 全局安装后，直接执行 depcheck # 局部安装后，通过npm脚本执行（需先在package.json的scripts中配置） # package.json 中添加："scripts": { "depcheck": "depcheck" } npm run depcheck # 或 yarn 执行 yarn depcheck # 临时使用（无需安装，通过npx直接调用，适合偶尔检测） npx depcheck

3. 核心输出解读

执行后会直接打印检测结果，分为 4 个核心模块，一目了然，以下是典型输出示例：

# depcheck 执行后的输出 Unused dependencies: # 未使用的生产依赖（可直接npm uninstall 删除） - lodash - axios Unused devDependencies: # 未使用的开发依赖（可直接删除） - sass-loader - @types/node-old Missing dependencies: # 缺失的依赖（代码里用了但没装，需npm install 安装） - moment: ./src/utils/date.js # 标注了依赖的使用文件路径 - uuid: ./src/components/IDGenerator.js Missing devDependencies: # 缺失的开发依赖 - @types/moment: ./src/utils/date.js

关键操作建议：

• 未使用的依赖：直接执行npm uninstall 包名删除，清理臃肿；

• 缺失的依赖：执行npm install 包名（生产依赖）或npm install 包名 --save-dev（开发依赖）补装。

三、depcheck 高级用法（解决误报 / 定制检测）

实际开发中，部分依赖是运行时使用（如 Webpack 插件、Express 中间件），depcheck静态分析无法识别，会出现误报未使用，此时需要通过「忽略依赖」「定制检测规则」解决，以下是高频高级用法：

1. 忽略指定依赖（解决误报核心）

通过--ignore-deps（忽略生产依赖）、--ignore-dev-deps（忽略开发依赖）参数，指定无需检测的包，多个包用逗号分隔：

# 忽略生产依赖lodash、axios，忽略开发依赖webpack-cli depcheck --ignore-deps lodash,axios --ignore-dev-deps webpack-cli

2. 指定检测的文件目录

默认检测项目根目录下的所有文件，可通过--dirs指定特定目录（如只检测 src、lib），减少检测范围：

# 只检测src和lib目录的依赖使用情况 depcheck --dirs src,lib

3. 排除无需检测的目录

通过--ignore-dirs排除无关目录（如 node_modules、dist、build，默认已排除，可自定义）：

# 排除test、mock目录，不检测这些目录的依赖 depcheck --ignore-dirs test,mock

4. 输出 JSON 格式（方便脚本 / 工具处理）

通过--json参数将检测结果输出为 JSON 格式，适合后续写脚本自动处理（如批量删除未使用依赖）：

# 输出JSON格式结果，可重定向到文件保存 depcheck --json > depcheck-result.json

5. 配置文件统一管理规则（推荐团队协作）

频繁使用的忽略规则、目录配置，可在项目根目录创建配置文件，无需每次写长命令，支持 2 种配置方式（二选一）：

• 方式 1：创建.depcheckrc文件（JSON 格式）

{ "ignoreDeps": ["lodash", "axios"], // 忽略的生产依赖 "ignoreDevDeps": ["webpack-cli", "sass-loader"], // 忽略的开发依赖 "dirs": ["src", "lib"], // 检测的目录 "ignoreDirs": ["test", "mock", "dist"] // 排除的目录 }

• 方式 2：在package.json中添加depcheck字段

{ "name": "your-project", "depcheck": { "ignoreDeps": ["lodash"], "ignoreDevDeps": ["webpack-cli"] } }

配置完成后，直接执行depcheck，会自动读取配置规则。

四、常见问题与解决

1. 依赖明明在用，却被标记为「未使用」（误报）

原因：depcheck是静态分析，无法识别动态加载（如require(${name})）、框架自动引入（如 Vue 插件、React 高阶组件）、运行时依赖（如 Express 中间件）。

解决：通过上述「忽略依赖」的方式，将误报的包加入忽略列表。

2. 检测不到部分缺失的依赖

原因：代码中通过 CDN 引入、或全局安装的依赖，depcheck无法检测。

解决：这类依赖本身无需在package.json声明，可忽略；若为项目内局部使用，需手动npm install并声明。

3. 检测速度慢

原因：项目目录过大，或包含大量无关文件。

解决：通过--dirs指定核心代码目录，--ignore-dirs排除 dist、node_modules、mock 等无关目录。

五、适用场景

1. 项目迭代久了，清理package.json中的无用依赖，减少npm install耗时；

1. 接手别人的项目，快速梳理依赖的使用情况，避免漏装 / 冗余；

1. 项目打包前，优化依赖清单，减少生产环境的包体积；

1. 团队协作时，规范package.json的依赖声明，避免「本地能用，部署报错」（缺失依赖）。

总结

1. depcheck是 Node.js 项目的依赖体检工具，核心解决「依赖臃肿、漏装、分类错误」问题，静态分析为主，少量误报可通过忽略规则解决；

1. 基础用法极简：全局安装后，项目根目录执行depcheck，按输出清理 / 补装依赖即可；

1. 高级用法核心是「解决误报」（忽略依赖）和「定制检测」（配置文件 / 命令行参数），适合复杂项目；

1. 适合项目重构、依赖优化、团队协作等场景，是 Node.js 开发的常用效率工具。