如何用Vite检测package.json中未使用的依赖？

Question

如何在 Vite 项目中检测 `package.json` 中未使用的依赖？虽然 Vite 本身不提供直接的依赖分析功能，但可结合工具如 `depcheck` 或 `unimported` 静态分析项目代码，识别未被引用的 npm 包。常见问题是：某些动态导入、Vite 插件依赖或类型声明（如 TypeScript 的 `devDependencies`）被误判为“未使用”。如何准确配置排除规则，避免误报，同时确保 tree-shaking 不影响检测结果？这是开发者常面临的挑战。

Answer 1

1. 背景与挑战：为何在 Vite 项目中检测未使用依赖至关重要

随着前端工程化的发展，现代项目普遍依赖大量 npm 包。Vite 作为新一代构建工具，虽然具备高效的开发服务器和基于 ES 模块的打包能力，但其本身并未提供 package.json 中依赖项的使用分析功能。这导致开发者难以判断哪些依赖是真正被引用的，哪些已成为“僵尸依赖”。

未使用的依赖不仅增加项目体积、拖慢安装速度，还可能引入安全漏洞。静态分析工具如 depcheck 和 unimported 成为解决该问题的关键手段。然而，在实际应用中，常因动态导入、插件机制或类型声明等特性产生误报。

2. 常见技术问题剖析

• 动态导入（Dynamic Imports）：如 import(`./modules/${name}.js`)，静态分析无法追踪具体模块路径，导致相关依赖被标记为未使用。
• Vite 插件依赖：某些插件（如 vite-plugin-svg-icons）仅在构建时通过配置调用，并不在代码中显式 import，因此被误判。
• TypeScript 类型依赖：devDependencies 中的类型包（如 @types/react）虽不参与运行时，但对类型检查至关重要，却常被工具忽略其“使用状态”。
• Tree-shaking 干扰：Rollup/Vite 的 tree-shaking 会移除未引用的导出，但静态分析工具通常不模拟这一过程，可能错误地认为某些模块未被使用。

3. 分析流程与工具选型对比

工具	原理	支持 Vite	误报处理能力	配置灵活性
depcheck	静态 AST 扫描 + 规则匹配	✅ 需手动配置解析器	中等（可通过 ignore 配置）	高（支持多种 ignore 规则）
unimported	基于文件依赖图分析	✅ 支持 ESM	较高（可排除特定模式）	中等
npm-check	交互式扫描	⚠️ 对 Vite 支持较弱	低	低

4. 实践方案：以 depcheck 为例进行精准检测

以下是集成 depcheck 到 Vite + TypeScript 项目的标准流程：

1. 安装依赖：
   npm install depcheck --save-dev
2. 创建配置文件 .depcheckrc.json：

{
  "parsers": {
    "**/*.ts": ["@depcheck/parser-typescript"],
    "**/*.tsx": ["@depcheck/parser-typescript"],
    "**/*.vue": ["@depcheck/parser-vue"]
  },
  "specials": [
    "@depcheck/special-vite",
    "@depcheck/special-typescript"
  ],
  "ignoreMatches": [
    "@types/*",
    "typescript",
    "vite",
    "vitest",
    "eslint",
    "prettier",
    "unplugin-*",
    "*-vite-plugin"
  ],
  "ignorePaths": [
    "tests",
    "mocks",
    "node_modules",
    "dist"
  ]
}

上述配置明确指定了 TypeScript 和 Vue 文件的解析器，并启用 Vite 和 TS 特殊规则处理器，避免将插件或类型依赖误判为未使用。

5. 排除规则设计策略

为减少误报，需结合项目结构制定精细化排除策略：

• 命名模式排除：使用通配符忽略常见插件，如 unplugin-* 或 *-vite-plugin。
• 路径排除：测试、构建脚本目录中的依赖不应纳入主项目分析范围。
• 特殊处理器注入：depcheck 允许自定义 special 函数，用于识别 Vite 插件配置中的隐式依赖。

6. 工作流整合与自动化检测

将依赖检测嵌入 CI/CD 流程可提升项目健康度。示例 GitHub Actions 配置片段：

jobs:
  lint-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npx depcheck --json > depcheck-report.json
      - run: |
          if [[ $(cat depcheck-report.json | jq '.dependencies | length') -gt 0 ]]; then
            echo "未使用依赖发现，请清理 package.json"
            exit 1
          fi

7. 可视化依赖关系图（Mermaid 流程图）

graph TD A[package.json] --> B{静态分析工具} B --> C[depcheck] B --> D[unimported] C --> E[AST 解析] D --> F[ESM 依赖图] E --> G[识别 import/export] F --> G G --> H[生成未使用列表] H --> I[人工审核] I --> J[清理或排除] J --> K[提交变更]

8. 进阶优化：结合 TypeScript 类型检查增强准确性

由于 depcheck 默认不深入类型层级，建议配合 tsc --noEmit --watch 验证类型依赖的实际使用情况。可通过编写脚本提取 tsconfig.json 中引用的类型包，并与 depcheck 结果交叉比对，实现更精准的判断。

此外，利用 unimported 的 --ignore 参数可跳过特定模式：

npx unimported --ignore 'types*,vitest,vue-router'

9. Tree-shaking 对检测结果的影响与规避

尽管 tree-shaking 是打包阶段的行为，但它会影响模块的实际引用链。静态分析工具运行于源码层面，无法模拟 Rollup 的摇树逻辑。因此，某些仅通过命名空间导入（如 import * as utils from './utils'）但后续未展开使用的模块，可能被误判为“未使用”。

解决方案包括：

• 在 depcheck 中启用 skipUnused 配置项，跳过未导出模块的检查。
• 结合 bundle analyzer（如 rollup-plugin-visualizer）反向验证哪些模块最终被打包，辅助判断依赖必要性。