Node Modules Inspector：Vue 团队出品的依赖分析神器

一条命令，让 node_modules 从「黑盒」变成「透视镜」

一、引言

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）

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

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

表格

分类维度	作用
深度/层级	按依赖嵌套深度分组，Depth null 表示未被实际引用的冗余依赖
模块类型	按 CJS/ESM/DUAL 分组，快速了解项目模块化现状
依赖环境	区分 dependencies 和 devDependencies
作者	按维护者分组，发现哪些作者在你的项目中占据大量空间
开源协议	按 MIT/BSD/Apache 等分组，方便做合规审查
组织	按 @vue、@babel 等组织分组
来源	区分 npm registry 来源

这种多维分类方式，让你可以用不同视角审视同一份依赖树——切换一个标签，就是一次全新的洞察。

2.1.2 树形视图（Tree）

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

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

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

2.1.3 报告视图（Report）

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

表格

报告标签	检测内容
依赖关系	依赖拓扑总览
废弃依赖	已标记 deprecated 的包
多版本依赖	同一包存在多个版本（依赖冲突）
安装大小	按体积排序，快速定位「肥胖」模块
发布时间	发现长期未更新的僵尸依赖
Node 相关	各包声明的 Node 版本要求
开源许可	许可证分布统计

其中最实用的是多版本依赖检测——它自动标记同一包的多个版本，比如 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 依赖健康检查
})

配置项详解

表格

配置项	说明	默认值
defaultFilters.excludes	默认排除的包名列表（支持 glob 模式）	[]
defaultFilters.includes	默认包含的包名列表（支持 glob 模式）	[]
defaultSettings.moduleTypeSimple	简化模块类型显示（隐藏冗余标签）	false
defaultSettings.showDependencySize	体积显示方式：'self'/'total'/'both'	'self'
publint	启用 publint 健康检查	false

五、实战场景

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

# 配合脚本检查多版本依赖数量
# 如果超过阈值则构建失败

六、与传统工具对比

表格

能力	npm ls	pnpm why	webpack-bundle-analyzer	Node Modules Inspector
依赖关系可视化	❌ 纯文本	❌ 纯文本	⚠️ 仅打包产物	✅ 全量依赖图谱
多版本冲突检测	⚠️ 需手动查找	⚠️ 需逐个排查	❌ 不涉及	✅ 自动标记
体积分析	❌	❌	✅ 打包后	✅ 安装时
模块类型检测	❌	❌	❌	✅ CJS/ESM/DUAL
许可证审查	❌	❌	❌	✅ 自动统计
Monorepo 支持	⚠️ 有限	✅	❌	✅ 完整支持
离线报告	❌	❌	✅	✅ 静态 SPA
依赖健康检查	❌	❌	❌	✅ publint 集成

核心差异：传统工具是「命令行查字典」，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辅助生成