3、可视化依赖图谱：让模块间的“蜘蛛网”无所遁形

说实话，我第一次接手一个老项目时，光是理清模块之间的关系就花了两天。打开代码目录，几十个文件互相引用，谁依赖谁完全是一笔糊涂账。后来我学乖了——直接用工具生成依赖图，一眼就能看出问题在哪。

这一节，我们就聊聊怎么用 dependency-cruiser 和 madge 这两个工具，把模块间的依赖关系变成一张清晰的 SVG 图。说白了，就是让那些隐形的“蜘蛛网”现出原形。

为什么需要可视化依赖图谱？

你想想看，一个项目里模块互相引用很正常。但一旦出现循环依赖、深层嵌套、或者某个模块被几十个地方引用，问题就来了：

循环依赖：A 引用 B，B 引用 C，C 又引用 A。这种结构在运行时可能引发死循环或诡异的 bug。
过度耦合：一个工具模块被上百个文件引用，改一行代码就得全局回归测试。
隐式依赖：有些依赖藏在深层路径里，你根本不知道它引用了什么。

我在项目中遇到过最夸张的一次，一个看似简单的 utils.js 文件，竟然间接依赖了 47 个模块。嗯，当时我就决定，必须用工具把这些关系画出来。

工具一：dependency-cruiser

dependency-cruiser 是我个人比较推荐的工具。它不仅能生成依赖图，还能做规则校验——比如禁止循环依赖、限制模块的引用深度。

安装与基本使用

npm install --save-dev dependency-cruiser

安装完后，先初始化一个配置文件：

npx depcruise --init

这个命令会生成 .dependency-cruiser.js 文件。里面可以配置哪些目录要扫描、哪些文件要忽略、以及自定义规则。

生成 SVG 依赖图也很简单：

npx depcruise src --output-type dot | dot -T svg > dependency-graph.svg

这里用到了 graphviz 的 dot 命令。如果你没装 graphviz，可以用 brew install graphviz 或者去官网下载。

配置规则示例

我个人习惯在配置里加上几条硬性规则：

// .dependency-cruiser.js 片段
{
  forbidden: [
    {
      name: 'no-circular',
      severity: 'error',
      from: {},
      to: {
        circular: true
      }
    },
    {
      name: 'no-deep-import',
      severity: 'warn',
      from: {},
      to: {
        pathDepth: 3
      }
    }
  ]
}

第一条规则禁止循环依赖，一旦发现直接报错。第二条规则警告深层导入——比如 import x from '../../../../utils' 这种，路径深度超过 3 层就该考虑重构了。

小技巧： 我建议把 dependency-cruiser 集成到 CI 流程里。每次提交代码时自动检查依赖关系，避免新代码引入循环依赖。我曾经因为没做这一步，上线后才发现一个循环引用导致内存泄漏，排查了整整一个下午。

工具二：madge

madge 是另一个好用的工具，它更轻量，生成图的速度更快。如果你只是想快速看一眼依赖关系，madge 是个不错的选择。

安装与使用

npm install --save-dev madge

生成 SVG 图：

npx madge --image dependency-graph.svg src/

就这么一行命令，搞定。madge 会自动分析 src/ 目录下的所有模块，生成一张完整的依赖图。

如果你想只看循环依赖，可以加个参数：

npx madge --circular src/

这个命令会列出所有循环依赖的模块路径。我一般先用这个命令快速扫描，如果有循环依赖，再针对性地去修。

如何解读依赖图？

生成 SVG 图之后，你可能会看到一张密密麻麻的“蜘蛛网”。别慌，重点看这几个地方：

节点大小：被引用次数多的模块，节点会比较大。这些模块往往是核心工具库，改动时要格外小心。
箭头方向：箭头指向被依赖的模块。如果发现箭头形成了一个环，那就是循环依赖。
颜色标记：有些工具会用不同颜色区分模块类型（比如蓝色是业务代码，红色是第三方库）。

我记得有一次，我看到一张图里有个节点特别大，点进去一看，是一个 helpers.js 文件，被 80 多个模块引用。我当时就意识到，这个文件已经成了“上帝对象”，任何改动都会引发连锁反应。后来我把它拆成了 5 个小模块，每个只负责单一功能，依赖关系瞬间清爽了很多。

实战：用 SVG 图展示依赖关系

下面这张 SVG 图是我用 dependency-cruiser 生成的一个示例。它展示了一个典型的前端项目中，模块之间的依赖关系：

从这张图里，你能很直观地看到：

App.js 是入口，依赖了路由、组件和工具模块。
Components 和 Utils 又分别依赖了 API 和第三方库。
最下面那个红色的 循环依赖 节点，用虚线箭头表示它和 API 模块之间形成了循环引用——这就是需要优先处理的问题。

注意： 生成 SVG 图时，如果项目很大，图可能会非常复杂。我建议先按模块分组，比如只分析某个子目录，或者只关注核心业务代码。否则一张图里几百个节点，谁也看不清。

避坑指南

我曾经在一个项目里，用 madge 生成了一张依赖图，发现有个模块被 200 多个文件引用。我当时想当然地以为这个模块是核心，结果一查，它只是一个简单的日期格式化函数。为什么会被引用这么多次？因为团队里每个人都在自己文件里写了一遍 import { formatDate } from './utils'，但没人想到把它抽成公共库。

所以，看到依赖图里的大节点时，先别急着重构。问自己三个问题：

这个模块真的需要被这么多人引用吗？
能不能通过接口抽象来减少直接依赖？
有没有重复的代码可以合并？

嗯，想清楚再动手，比盲目拆分要有效得多。

总结

可视化依赖图谱，说白了就是给项目做一次“CT 扫描”。用 dependency-cruiser 或 madge 生成 SVG 图，你就能一眼看出哪些模块是“交通枢纽”，哪些地方有“死循环”。

我个人习惯是：每两周跑一次依赖图，看看有没有新增的循环依赖或者过度耦合。如果发现异常，就趁早修掉。别等到项目膨胀到几万行代码时再回头，那时候改起来就痛苦了。

记住，依赖图不是用来炫耀的，它是帮你做决策的工具。图越清晰，你的代码就越健康。

  核心要点：
  dependency-cruiser 适合做规则校验和深度分析
madge 适合快速生成依赖图
重点关注大节点和循环依赖
定期检查，防患于未然

可可精品资料库

📚 课程目录

3、可视化依赖图谱：让模块间的“蜘蛛网”无所遁形

为什么需要可视化依赖图谱？

工具一：dependency-cruiser

安装与基本使用

配置规则示例

工具二：madge

安装与使用

如何解读依赖图？

实战：用 SVG 图展示依赖关系

避坑指南

总结