在管理 Node.js 项目依赖时，depcheck 是一款非常实用的工具，专门用于扫描项目中未使用、缺失以及冗余的依赖包。它对 Vue、React、TypeScript 等主流前端框架项目都表现出色，几乎可以实现零配置、开箱即用。其核心功能是精准识别 package.json 中声明过、但在源码里从未被 import 或 require 引用的包。结合 webpack-bundle-analyzer 和 Knip 等工具，能够构建一套“扫描 + 验证 + 确认”的依赖清理闭环流程。

在跨平台开发 Codex 项目时，一个常见且令人困扰的问题是：package.json 中混入了大量未曾被实际引用的依赖包。这会导致项目构建体积膨胀、安全扫描告警频繁出现、CI 流程运行速度变慢，甚至在 macOS 与 Windows 系统之间，由于路径解析机制差异，还可能引发一些难以排查的运行时异常。

通过 depcheck 在双平台扫描未使用依赖

具体操作流程如下：

第一步，务必确保项目根目录下包含完整的 package.json 文件和 src/ 目录结构。否则 depcheck 可能会遗漏部分全局 require 或动态加载路径中的依赖。

第二步，运行命令行扫描命令。需要注意的是，该命令会自动适配 Windows 与 Mac 系统在文件系统上的差异：npx depcheck --ignore-bin-package --ignore-patterns="test,tests,__tests__,e2e,dist,build"。添加这些参数的作用，是跳过测试和构建产物目录，避免将 jest、webpack 这类工具误判为“未使用”依赖。

第三步，仔细查看输出结果。重点关注 Unused dependencies 和 Unused devDependencies 这两个区块——它们才是真正的冗余目标。而 Missing dependencies 中列出的包必须立即补充完整，否则后续运行项目时一定会出现报错。

手动复核动态依赖是否真实可用

有一个关键点需要特别说明：depcheck 无法识别类似 eval('require("'+pkgName+'")') 或 import(`${pkgName}/index.js`) 这类通过字符串拼接方式加载的依赖。

那么，应该如何手动验证呢？以下几种方法值得尝试：

• 全局搜索所有 require() 和 import() 调用：grep -r "require.*[" src/ node_modules/ | grep -v "node_modules/"
• 检查 Webpack 配置中的 externals、resolve.alias 以及 plugins 项，确认是否有插件（例如 CopyPlugin、DefinePlugin）间接引入了某个包，但没有显式地进行 import 引用。
• 查看 .codexrc、codex.config.js 或 package.json 中的 scripts 字段，判断是否调用了某个包的 CLI 命令行工具（如 prettier、eslint）。这类依赖属于“运行时脚本依赖”，绝对不能轻易删除。

安全移除冗余依赖包

一旦确认某个包确实没有被任何代码引用、配置引用或脚本引用，就可以放心地进行卸载操作：
npm uninstall lodash（针对生产依赖）
npm uninstall @types/node --sa ve-dev（针对开发依赖）

重要提醒：请勿使用 npm prune 命令。该命令仅会清理 node_modules 中未声明的包，并不会修改 package.json，因此无法从根源上解决依赖冗余问题。
卸载完成后，务必立即执行 npm install 来更新 lock 文件并重建依赖树——这一步绝对不能省略，否则 CI 环境很容易因 lock 文件版本不一致而导致构建失败。

验证跨平台兼容性

最后一步，也是检验“清理成果”的关键环节。需要在 Windows 和 macOS 两台设备上分别执行以下操作：

• npm run build —— 检查是否出现 Module not found 错误
• npm test —— 确保所有单元测试顺利通过，尤其注意 mock 文件中是否引用了刚刚删除的依赖包
• 启动 Codex 开发服务器：npm run dev —— 观察控制台是否报错，页面功能是否运行正常

只要任一平台出现失败情况，请立即回退操作：执行 git checkout package.json 恢复依赖列表，然后逐个排查遗漏的依赖点，不要急于再次尝试删除。