一、引言

1.1 node_modules：前端开发最大的黑盒

几乎所有前端项目都包含一个让人又爱又恨的文件夹——node_modules。爱它，是因为项目运行离不开它；恨它，是因为很少有人真正了解里面装了什么。坦白说，这或许是前端开发领域里最令人困扰的黑盒。

一个典型的中型 Vue 项目，node_modules 里通常包含上千个包，嵌套层级可达七八层深。当遇到依赖冲突、版本冗余或体积膨胀等问题时，我们常用的排查手段往往局限于：

npm ls lodash           # 输出大量嵌套文本，难以全面审视
pnpm why lodash         # 仅能查询单条链路，无法掌握全局
du -sh node_modules/*   # 仅显示大小，无法得知缘由

这些命令输出的碎片化信息，就像盲人摸象——你可能触及了局部，但无法洞察整体。更重要的是，它们难以回答那些真正关键的问题：

• 哪些依赖包存在多版本重复安装？
• 哪个依赖包是体积膨胀的罪魁祸首？
• 项目中 ESM 和 CJS 模块的占比如何？
• 是否存在已被废弃或潜藏安全风险的依赖？

1.2 Node Modules Inspector 登场

Node Modules Inspector 是由 Vue 核心团队成员 Anthony Fu（antfu）开发的可视化依赖分析利器。它通过交互式图形界面，彻底改变了我们与 node_modules 的互动方式——从「盲人摸象」升级为「一目了然」。

一条命令即可快速启动：

npx node-modules-inspector

无需全局安装，也无需额外配置文件，浏览器会自动弹出可视化界面。当前最新版本为 v2.1.2，已进入稳定迭代阶段。

项目地址：github.com/antfu/node-…在线体验：node-modules.dev

二、核心功能详解

2.1 四大视图：从不同维度审视依赖

Node Modules Inspector 提供了四种核心视图，每种视图都能从独特的角度帮助你审视项目依赖关系。

2.1.1 网格视图（Grid）

网格视图是默认视图，以卡片形式展示所有依赖包。每张卡片包含包名、版本号、体积大小、模块类型等关键信息。

上方的标签栏支持按多种维度进行分类：

这种多维度的分类方式，让你能够从不同视角审视同一份依赖树——切换一个标签，便是一次全新的洞察体验。

2.1.2 树形视图（Tree）

树形视图展示了依赖的层级结构，清晰呈现了父子包之间的引用关系。相较于 npm ls 的纯文本输出，其优势在于：

• 可折叠或展开任意层级
• 点击节点即可查看包的详细信息
• 高亮显示存在多版本共存的包

在 Vue 项目中，你可以直观地看到 @vue/compiler-sfc 与 @vue/compiler-core、@vue/runtime-dom 等包之间的关联脉络。

2.1.3 报告视图（Report）

报告视图从问题导向出发，自动分析依赖中的异常情况：

其中最实用的当属多版本依赖检测——它会自动标记同一包的多个版本，例如 lodash@4.17.21 和 lodash@3.10.1 同时存在时，会使用醒目的图标提示，帮你揪出隐藏的版本冲突问题。

2.1.4 图表视图（Graph）

图表视图利用节点和连线构建依赖关系图谱，是最直观的可视化方式。每个节点代表一个包，连线表示依赖关系。支持多种布局方式，每个元素都可悬停或点击查看详情。

它特别适合理解复杂的依赖链——当某个间接依赖引发问题时，你可以沿着图谱快速回溯到根本原因。

2.2 依赖对比：两个版本之间的差异一目了然

v2.x 版本新增了依赖对比功能。你可以选择任意两个版本或两个时间点，直观对比依赖结构、大小、引用关系的变化。这对于以下场景非常实用：

• 升级依赖版本前后的差异分析
• 不同分支之间的依赖差异检查
• CI/CD 流程中监控依赖漂移

2.3 依赖详情面板

无论在哪个视图中，点击任意依赖都会在左侧弹出详情面板，展示：

• 包名与用途简介
• 版本号
• 仓库地址
• 开源协议
• 作者信息
• 安装体积
• 模块类型（CJS/ESM/DUAL）
• 直接依赖与被依赖关系
• provenance 来源徽章（v2.1+ 新增，用于验证包是否来自可信源）

2.4 publint 集成：依赖健康检查

Node Modules Inspector 集成了 publint，可以对依赖进行健康检查，检测以下问题：

• 包的 package.json 导出配置是否正确
• 是否存在未维护的包
• ESM/CJS 兼容性是否规范

启用方式（在配置文件中）：

import { defineConfig } from 'node-modules-inspector'export default defineConfig({
  publint: true  // 启用 publint 集成
})

v2.1 新增了 Maintainer Actions Report，会给出具体的 dep-upgrade 和 publint 建议，方便维护者批量处理。

三、快速上手

3.1 安装与启动

无需全局安装，直接通过 npx 启动：

# npm 项目
npx node-modules-inspector# pnpm 项目（推荐）
pnpx node-modules-inspector# bun 项目
bunx node-modules-inspector

执行后，浏览器会自动打开本地可视化界面，默认端口为 3000。如果端口被占用，工具会自动寻找可用端口。

环境要求： Node.js 18+

3.2 在线体验

不想在本地运行？直接访问 node-modules.dev，基于 WebContainer 技术，在浏览器中运行完整的 Node.js 环境，实现在线分析依赖关系。

你只需输入包名（如 vue），工具便会自动安装依赖并生成可视化图谱，非常适合快速验证依赖结构。

3.3 生成离线静态报告

需要分享分析结果或进行归档存查？可以生成静态 SPA：

pnpx node-modules-inspector build

生成的文件位于 dist/__node-modules-inspector 目录（v2.0+ 默认路径），包含交互式 HTML 和资源文件。可以通过 Nginx 等服务器托管，或直接用浏览器打开 index.html。

实况案例：everything.antfu.dev——antfu 所有包的依赖分析报告。

四、个性化配置

在项目根目录创建 node-modules-inspector.config.ts，可以自定义工具行为：

import { defineConfig } from 'node-modules-inspector'export default defineConfig({
  // 默认过滤规则
  defaultFilters: {
    excludes: [
      'eslint',   // 排除开发工具类依赖，减少干扰
      'postcss',  // 按需隐藏特定类型包
    ],
    includes: ['@vue/ **'],  // 仅关注 Vue 相关依赖
  },  // 默认显示设置
  defaultSettings: {
    moduleTypeSimple: true,          // 简化模块类型显示
    showDependencySize: 'both',      // 同时显示单个包体积和占比
  },  // 实验性功能
  publint: true,  // 启用 publint 依赖健康检查
})

配置项详解

五、实战场景

5.1 场景一：排查依赖冲突导致的打包失败

问题描述： 项目升级 Vue 3.5 后，打包时报错 Duplicate key "runtime-core"。

排查步骤：

1. 在项目根目录运行 pnpx node-modules-inspector

2. 切换到「报告视图」，点击「多版本依赖」标签

3. 发现项目中同时存在：

   • @vue/runtime-core@3.5.13（主项目直接依赖）
   • @vue/runtime-core@3.4.12（某第三方插件间接依赖）

4. 在图谱视图中追踪到冲突源：vue-legacy-plugin → @vue/runtime-core@3.4.12

解决方案：

// package.json - 使用 pnpm override 强制统一版本
{
  "pnpm": {
    "overrides": {
      "@vue/runtime-core": "3.5.13"
    }
  }
}

或升级或替换该第三方插件，问题即可解决。

5.2 场景二：优化项目体积，减少冗余依赖

问题描述： 一个 node_modules 体积超过 100MB 的项目，需要进行瘦身。

排查步骤：

1. 运行 pnpx node-modules-inspector

2. 切换到「报告视图」，点击「安装大小」标签

3. 按体积降序排列，发现：

   • @babel/parser 占用 2.3MB
   • core-js@2 仍然存在（已被 core-js@3 替代）
   • 多个组件库重复依赖 lodash 的不同子集

4. 切换到网格视图，按「深度/层级」分类，发现 Depth null 的冗余依赖有 12 个

解决方案：

• 移除 @babel/plugin-proposal-decorators 引入的不必要的 core-js@2
• 将 lodash 替换为 lodash-es，配合 tree-shaking 按需引入
• 清理未被实际引用的冗余依赖

最终 node_modules 体积缩减约 35%。

5.3 场景三：Monorepo 跨包依赖审查

问题描述： pnpm monorepo 项目中，多个子包存在重复依赖和版本不一致问题。

排查步骤：

1. 在 monorepo 根目录运行 pnpx node-modules-inspector
2. 工具自动识别 Workspace 结构，清晰展示各子包的依赖关系
3. 在多版本依赖报告中，发现 typescript 和 eslint 在不同子包中版本不统一
4. 通过详情面板查看每个子包的具体依赖链

解决方案：

在根 package.json 中统一版本：

{
  "pnpm": {
    "overrides": {
      "typescript": "5.7.3",
      "eslint": "9.20.0"
    }
  }
}

5.4 场景四：CI/CD 自动化依赖审查

问题描述： 需要在 CI 流程中自动检测依赖问题。

解决方案：

v2.0+ 新增了 **config hook **，支持 CI/CD 自动化集成：

# 生成静态报告供 CI 归档
pnpx node-modules-inspector build# 配合脚本检查多版本依赖数量
# 如果超过阈值则构建失败

六、与传统工具对比

核心差异在于：传统工具更像是「命令行查字典」，而 Node Modules Inspector 则像是「开透视镜」。

七、进阶技巧

7.1 结合 pnpm overrides 解决版本冲突

发现多版本依赖后，最直接的解决方式是使用 pnpm 的 overrides 机制：

// package.json
{
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21",           // 强制统一版本
      "@vue/runtime-core": "^3.5.0"  // 统一 Vue 运行时
    }
  }
}

修改后重新运行 pnpx node-modules-inspector，验证冲突是否消除。

7.2 用 glob 模式精准过滤

配置文件中的 includes 和 excludes 支持 glob 模式：

export default defineConfig({
  defaultFilters: {
    excludes: [
      '** /eslint/ **',     // 排除所有 eslint 相关
      '@types/*',         // 排除所有类型声明包
    ],
    includes: [
      '@vue/** ',          // 只看 Vue 生态
      'vite*',            // 只看 Vite 相关
    ],
  },
})

这在依赖数量庞大的项目中特别有用——先过滤出关注范围，再逐项分析。

7.3 定期归档依赖快照

在每次重大版本升级前后，生成静态报告并归档：

# 升级前
pnpx node-modules-inspector build
cp -r dist/__node-modules-inspector ./reports/before-upgrade# 升级后
pnpx node-modules-inspector build
cp -r dist/__node-modules-inspector ./reports/after-upgrade

这样你可以随时对比升级前后的依赖变化，做到心中有数。

八、v2.0 重要更新

2026 年 5 月，Node Modules Inspector 发布了 v2.0，带来了一些值得关注的变更：

8.1 CLI 迁移到 devframe

v2.0 将 Inspector RPC 和 CLI 迁移到了 devframe 框架，这是 antfu 统一开发工具底层架构的一部分。对用户来说，主要影响是默认构建输出目录变更为 dist/__node-modules-inspector。

8.2 CI/CD 自动化支持

新增了 config hook，支持在 CI/CD 流程中实现自动化依赖审查。

8.3 Provenance 徽章

v2.1 新增了 provenance 来源徽章功能，可以验证包是否来自可信的 npm 发布源，帮助识别供应链风险。同时新增了依赖来源甜甜圈图（Provenance Donut），直观展示项目依赖的可信度分布。

8.4 GitHub 感知作者检测

v2.1 新增了 GitHub-aware 作者检测，能更准确地识别和展示包的维护者信息。

8.5 无障碍访问改进

v2.1 通过了 WCAG AA 色彩对比度测试，显著改善了可访问性。

九、局限性与注意事项

1. 需要 Node.js 18+ ：旧版 Node 可能无法正常启动，本地运行报错时可以尝试使用在线版 node-modules.dev
2. 大型项目首次扫描较慢：依赖上千的项目首次加载可能需要几秒到十几秒，后续交互流畅
3. 不替代打包分析：Node Modules Inspector 分析的是 node_modules 安装时的体积，并非最终打包体积。若需优化 bundle size，仍需配合 rollup-plugin-visualizer 或 webpack-bundle-analyzer
4. bun 支持仍在完善：目前对 bun 项目的支持不如 pnpm/npm 成熟

十、总结

Node Modules Inspector 的核心价值可以用一句话概括：让 node_modules 从不可见的黑盒，变成可交互的透视镜。

它并非为了替代 npm ls 或 pnpm why——而是提供了一个站在更高维度重新审视依赖关系的窗口。当你遇到以下问题时，它是最快捷的钥匙：

• 依赖冲突：多版本共存，打包时报错
• 体积膨胀：node_modules 越来越大，却不知从何处瘦身
• 合规审查：许可证分布、废弃依赖、供应链安全
• Monorepo 治理：跨包依赖不一致

一条命令即可启动，零配置即可使用，有需求时再深入配置——这种「低门槛、高上限」的设计，正是 antfu 工具的一贯风格。

项目地址：github.com/antfu/node-… | 在线体验：node-modules.dev

本文由AI辅助生成