Webpack 5 把模块依赖关系建模成一幅有向图，每个模块从入口开始都有一个深度值 depth。这个值不是只给开发者看的调试信息，而是真正参与了 tree shaking、splitChunks 甚至缓存键的生成。在 webpack 4 中，模块信息分散在多个内部对象里，插件很难拿到统一的深度数据；Webpack 5 通过 compilation.moduleGraph 暴露了完整的模块图 API，其中 getDepth(module) 可以直接返回模块深度。我们可以利用这个深度做依赖层级分析、优化公共模块提取，还能定位构建中的深层依赖瓶颈。
一、模块图深度从哪里来
Webpack 5 用 ModuleGraph 来统一管理模块、依赖和连接关系。每个模块在图中都有一个深度值，入口模块深度为 0，它直接引入的模块深度为 1，再下一层为 2，依次类推。如果存在循环依赖，深度取最短可达路径，不会因为环而无限累加。这与树结构不同，因为模块图是有向图，同一个模块可能被多个父模块引用，深度只反映从最近入口出发的层级。
深度值的计算方法并不复杂，但要注意它没有包含异步边界。例如入口通过 import() 懒加载的模块，深度是按依赖边计算，不会因为异步 chunk 的拆分离而重置为 0。这意味着一个动态导入的页面组件，深度可能比某些静态公共模块更深。深度能够反映模块距离执行入口的远近，但在异步场景下，深层不代表一定慢，也不能直接对应 chunk 的加载顺序。
下面这段插件代码可以在构建结束后输出所有深度大于 5 的模块，方便快速定位依赖层级过深的位置：
class DepthReporterPlugin {
apply(compiler) {
compiler.hooks.compilation.tap('DepthReporterPlugin', (compilation) => {
compilation.hooks.finishModules.tap('DepthReporterPlugin', () => {
const moduleGraph = compilation.moduleGraph;
const deepModules = [];
for (const module of compilation.modules) {
const depth = moduleGraph.getDepth(module);
if (depth !== null && depth > 5) {
deepModules.push({ identifier: module.identifier(), depth });
}
}
console.log('深度大于5的模块数量:', deepModules.length);
});
});
}
}
module.exports = DepthReporterPlugin;
Webpack 4 中插件如果要获取类似信息，需要遍历 dependencies 并手动回溯，不同模块类型处理方式不一致；Webpack 5 把 moduleGraph 作为一等公民，getDepth 只是其中一个方法，这大幅降低了插件开发复杂度。对于大型项目来说，模块图深度还是观察依赖结构是否健康的有效指标。
二、深度对 tree shaking 和副作用分析的影响
tree shaking 并不是简单地删除未使用导出，它需要先判断每个模块是否包含副作用。Webpack 5 会沿着模块图从入口开始分析，越深的模块经过的导入链越长，受到中间模块 sideEffects 配置的影响越明显。如果某个组件库没有在 package.json 中声明 sideEffects: false，那么深层引入的组件即使只用到其中一个函数，也可能被整体保留。深度越大，这种误保留的累积越严重。
以一个典型后台项目为例，入口通过路由懒加载十几个页面组件，每个页面又引入日期库、图表库和工具函数。未配置 sideEffects 时，打包产物体积可能达到 3.2 MB；为第三方库统一加上 sideEffects 标记后，同样的模块深度结构下，体积下降到 2.1 MB。模块深度没有变化，但 tree shaking 能够安全剪掉更多分支，说明深度本身不是问题，副作用分析精度才是关键。
| 配置项 | 最大模块深度 | 入口 chunk 体积 | 异步 chunk 总体积 |
|---|---|---|---|
| 未声明 sideEffects | 13 | 1.45 MB | 1.75 MB |
| 仅第三方库标记 sideEffects: false | 13 | 1.12 MB | 0.98 MB |
| 业务模块按需导出 | 8 | 0.87 MB | 0.76 MB |
除了 sideEffects，Webpack 5 的 optimization.usedExports 也会结合深度信息判断导出是否被使用。当一个模块深度较深且只被单一入口间接引用时，分析器可以更激进地标记未使用导出。但这并不是因为深度大而被删除，而是深度路径上的引用关系简单，分析器信心更高。真正决定删除与否的仍然是导入和导出的实际使用情况。
三、基于深度做构建优化的两种实践
第一种实践是用深度报告定位依赖层级过深问题。很多项目开发一段时间后，会出现入口文件间接依赖十几层工具函数的情况。深度过大本身不直接导致性能问题，但会拉长模块解析和副作用分析的路径。通过前面示例的插件，可以定期检查深度大于 8 的模块是否合理。如果发现某个公共工具函数位于第 12 层，往往说明依赖没有被提升到合适位置，可以通过路径别名、统一导出入口或调整目录结构来降低深度。
第二种实践是结合 splitChunks.cacheGroups 做更精细的公共模块提取。Webpack 5 支持在 cacheGroups 中使用函数形式的 test，函数能拿到 module 参数，通过 moduleGraph.getDepth(module) 判断该模块的深度。比如把深度小于 3 的公共模块提取到 vendors，把深度大于等于 3 的异步公共模块提取到 async-common。配置如下：
module.exports = {
optimization: {
splitChunks: {
cacheGroups: {
vendors: {
test(module, { moduleGraph }) {
const depth = moduleGraph.getDepth(module);
return depth !== null && depth < 3 && /node_modules/.test(module.identifier());
},
name: 'vendors',
chunks: 'all'
},
asyncCommon: {
test(module, { moduleGraph }) {
const depth = moduleGraph.getDepth(module);
return depth !== null && depth >= 3 && /node_modules/.test(module.identifier());
},
name: 'async-common',
chunks: 'async'
}
}
}
}
};
这套配置的核心不是盲目相信深度，而是把深度作为一个稳定、可计算的分类维度。浅层 node_modules 代码通常被多个入口直接共享，适合放在初始缓存中；深层 node_modules 代码往往只出现在异步路由里，单独拆包可以减少首屏加载。要注意 depth 可能为 null，例如某些特殊模块还未完全建立连接，因此处理时必须做空值判断。
四、容易误解的几个点
第一个误解是深度越深越应该单独打包。实际上深度只描述依赖层级，不描述模块被复用的次数。一个深层模块如果只被一个 chunk 使用，单独拆出来反而增加网络请求；一个浅层模块如果被几十个入口共享，即使深度为 1 也应该提取。打包策略需要同时考虑深度、体积、复用次数和 chunk 类型，不能只盯住 depth。
第二个误解是模块深度在构建过程中一成不变。由于 loader 和插件会修改模块图，例如移除未用模块、合并模块或调整依赖关系，同一个模块在不同 hook 阶段读到的深度可能不同。因此不要在 compilation 开始时把深度缓存下来，而要在模块图基本稳定后的 hook 中读取，比如 finishModules 或 afterOptimizeModuleGraph。
第三个误解是把深度当作运行时加载顺序。Webpack 的运行时按 chunk 和模块 ID 加载，不按深度排序。深度是编译期的分析指标，用于优化构建结果和诊断依赖结构，不会作为浏览器执行代码的优先级依据。理解这一点有助于避免在插件中把深度写入运行时逻辑而引发错误。