Nx 单体仓库安全审计与移除未使用依赖：静态分析、验证脚本与构建校验

在 Nx 单体仓库（monorepo）中管理依赖是一个常见挑战。随着项目规模扩大，未使用的依赖会悄然积累，导致安装时间延长、bundle 大小膨胀，甚至引入潜在的安全漏洞。安全审计和移除这些依赖不仅是优化性能的必要步骤，更是维护代码健康的关键。本文聚焦于通过静态分析工具 Knip 进行审计，结合验证脚本和构建校验，确保移除过程无破坏性变更，实现 bundle 大小显著减少。

未使用依赖的隐患与审计必要性

Nx 作为一款强大的 monorepo 工具，支持 Angular、React 等框架的多项目管理，但其工作区（workspaces）结构往往导致依赖散布在根目录和各个 apps/libs 中。未使用依赖可能源于历史遗留、实验性安装或团队协作不畅。根据静态分析原理，这些依赖虽未在代码中显式导入，却可能通过配置文件或间接引用隐藏存在。忽略它们会放大风险：Yarn 或 npm 安装时间可能增加数分钟，CI/CD 管道变慢；同时，过多的包会提升 CVE（常见漏洞与暴露）警报噪音，分散安全团队注意力。

观点上，定期审计能将这些隐患转化为机会。通过 Knip 等工具，我们可以构建一个依赖使用图谱，量化未使用比例。在一个典型 Nx 项目中，未使用依赖占比可达 20%-40%，移除后安装速度可提升 20%以上。这不仅是性能优化，更是工程实践的体现，避免“依赖债”积累。

选择合适的静态分析工具：Knip 的优势

传统工具如 depcheck 虽简单，但对现代 monorepo 支持不足，常因动态导入或配置文件引用产生大量假阳性。Knip 则专为 TypeScript/JavaScript 项目设计，支持 Nx 工作区结构，能解析入口点（如 tsconfig.json、jest.config.js）和常见框架约定。“Knip 通过构建导入图并与 package.json 比较，识别未使用依赖”，这使其在 monorepo 场景下准确率更高。

安装 Knip 非常便捷，无需全局安装，直接使用 yarn dlx knip 即可启动扫描。对于 Nx 项目，建议在根目录运行，以覆盖所有工作区。Knip 的输出包括未使用 dependencies 和 devDependencies 列表，便于分类处理。

Knip 配置参数：适应 Nx monorepo

要最大化 Knip 的效用，需要自定义配置。创建一个 knip.config.ts 文件，放置在项目根目录：

import type { KnipConfig } from 'knip';

const config: KnipConfig = {
  include: ['dependencies', 'devDependencies'],  // 只检查生产和开发依赖
  ignoreWorkspaces: ['packages/eslint-config'],  // 忽略特定工作区，如工具包
  ignoreDependencies: [
    'ts-node',  // Jest 配置中字符串引用
    'cross-env',  // 仅用于 scripts
  ],
  workspaces: {
    'apps/cms': {
      ignoreDependencies: ['@sanity/vision'],  // 应用特定忽略
    },
    'packages/ui': {
      ignoreDependencies: [
        'tw-animate-css',  // CSS @import 间接使用
        '@tailwindcss/typography',
      ],
    },
  },
  // 其他选项：project: 'tsconfig.json' 以指定根配置
};

export default config;

这些参数确保 Knip 理解 Nx 的多工作区布局。ignoreDependencies 用于排除假阳性，如仅在 package.json scripts 中引用的 CLI 工具。运行 yarn dlx knip --config knip.config.ts 后，输出将更精确。阈值设置：若未使用依赖超过 10%，建议立即介入；对于大型 repo，扫描时间控制在 30 秒内，通过缓存选项优化。

安全移除流程：静态分析到验证脚本

审计后，移除过程需谨慎分步执行，避免批量操作导致不可逆错误。核心观点：将 Knip 输出视为“提示”，而非绝对命令，通过自动化验证脚本确认。

生成审计报告：运行 Knip，导出 JSON 输出（knip --reporter json > audit.json）。解析文件，列出候选依赖列表，例如 lodash、moment 等。
逐个移除与验证：
- 对于每个候选：yarn remove （或 npm uninstall）。
- 立即运行 Nx 受影响命令：nx affected:build、nx affected:test、nx affected:lint。这些命令利用 Nx 的依赖图，仅构建/测试变更部分，效率高。
- 附加 e2e 测试：nx affected:e2e，确保端到端流程无中断。
- 启动应用：nx run :serve 或 :dev，模拟真实环境，检查控制台错误或功能缺失。
脚本自动化：编写一个 Node.js 脚本 verify-removal.js 来封装验证：

const { execSync } = require('child_process');
const candidates = ['lodash', 'moment'];  // 从 audit.json 加载

candidates.forEach(pkg => {
  try {
    execSync(`yarn remove ${pkg}`, { stdio: 'inherit' });
    console.log(`Removed ${pkg}, verifying...`);
    execSync('nx affected:build', { stdio: 'inherit' });
    execSync('nx affected:test', { stdio: 'inherit' });
    execSync('nx run my-app:serve --port=4200 & sleep 5; curl http://localhost:4200', { stdio: 'inherit' });  // 简单健康检查
    console.log(`${pkg} safe to remove.`);
  } catch (error) {
    console.error(`${pkg} breaks something, restoring...`);
    execSync(`yarn add ${pkg}`, { stdio: 'inherit' });
    // 更新忽略列表
  }
});

此脚本参数化阈值：超时 60 秒，失败率 >5% 则中止。适用于 CI 预览分支。

构建校验清单：
- 检查 bundle 大小：使用 webpack-bundle-analyzer 前后对比，目标减少 5%-15%。
- 监控安装时间：time yarn install，基准 <2 分钟。
- 安全扫描：运行 yarn audit，减少高危 CVE 数量。

整个流程预计处理 100+ 依赖需 1-2 天，视 repo 复杂度而定。

风险控制与回滚策略

移除依赖并非零风险。常见 pitfalls 包括间接使用（如插件自动加载）和跨工作区影响。风险限：假阳性率可达 40%，需手动审核；monorepo 中，一处移除可能波及多个 apps。

缓解措施：

渐进式 PR：分批提交，每批 <20 个依赖，包含前后基准数据。
回滚参数：保留 yarn.lock 备份，失败时 yarn install --frozen-lockfile 恢复。设置 Git 钩子 pre-push 运行 Knip 校验。
监控要点：集成到 CI（如 GitHub Actions），每周运行 Knip 报告；使用 Sentry 或日志聚合监控生产异常，阈值：错误率 >1% 触发警报。
团队协作：文档化忽略原因，如“ts-node: Jest 配置引用”，避免重复争议。

通过这些，可落地参数确保 99% 置信度下无破坏变更。

结语：持续优化依赖生态

在 Nx monorepo 中，安全移除未使用依赖不仅是清理，更是构建高效工程文化的起点。结合 Knip 的静态分析、Nx 的 affected 命令和自定义验证脚本，你能显著降低 bundle 大小（典型 10%-20%），加速开发迭代。建议每月审计一次，视作 routine maintenance。最终，这将让团队聚焦核心创新，而非依赖琐事。

（字数：1028）