webpack-bundle-analyzer

Webpack 插件与 CLI 工具，以交互式可缩放树形图可视化 bundle 内容，帮助开发者直观分析和优化打包体积。

技术简介说明

webpack-bundle-analyzer 是 webpack 生态中最广泛使用的包体积分析工具，自 2016 年发布至今已有近十年历史。它以交互式树形图（Treemap）的形式展示 webpack 打包产物的组成结构，让开发者能够直观地看到每个模块在最终 bundle 中所占的体积比例，从而快速定位体积瓶颈。

该工具的核心价值在于将抽象的打包数据转化为可交互的视觉图表。开发者可以通过点击、缩放等操作深入查看任意层级的模块组成，支持 stat（原始大小）、parsed（解析后大小）和 gzip/brotli/zstd（压缩后大小）三种度量方式，全面反映模块在不同阶段的体积表现。这种直观的可视化能力使其成为前端性能优化工作流中不可或缺的一环。

截至 2026 年，webpack-bundle-analyzer 已从最初的 webpack-contrib 组织迁移至 webpack 官方 webpack 组织下，成为 webpack 官方认可的核心工具之一。它每周拥有超过 1200 万次 npm 下载量，被大量企业级项目采用，包括 Next.js（通过 @next/bundle-analyzer）、Angular CLI、Vue CLI 等主流框架均内置或推荐使用该工具。

基本信息

• 官网：https://webpack.js.org/guides/code-splitting/#bundle-analysis
• GitHub：https://github.com/webpack/webpack-bundle-analyzer
• License：MIT
• 最新版本：v5.3.0（2026-03-25 发布）
• 主要维护者/公司：Yuriy Grunin（@th0r）、Vesa Laakso（@valscion）、Alexander Akait（@alexander-akait），webpack 官方组织维护
• npm 周下载量：约 1230 万次
• GitHub Stars：约 12,700
• Node.js 要求：>= 20.9.0（v5.0.0 起）

快速上手

安装

# npm
npm install --save-dev webpack-bundle-analyzer
 
# yarn
yarn add -D webpack-bundle-analyzer
 
# pnpm
pnpm add -D webpack-bundle-analyzer

基础配置

在 webpack 配置中添加插件：

// webpack.config.js
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
 
module.exports = {
  // ... 其他配置
  plugins: [
    new BundleAnalyzerPlugin({
      // 分析模式：'server'（默认，启动 HTTP 服务器展示报告）
      //          'static'（生成单个 HTML 文件）
      //          'json'（生成 stats JSON 文件供 CLI 使用）
      //          'disabled'（禁用分析器）
      analyzerMode: 'server',
      // 分析服务器主机名
      analyzerHost: '127.0.0.1',
      // 分析服务器端口
      analyzerPort: 8888,
      // 报告文件名（static 模式下）
      reportFilename: 'report.html',
      // 报告标题
      reportTitle: 'Bundle Analysis Report',
      // 默认显示的模块大小类型
      // 'stat' - 模块声明大小（原始输入大小）
      // 'parsed' - webpack 解析后大小（实际输出大小）
      // 'gzip' - gzip 压缩后大小
      // 'brotli' - brotli 压缩后大小
      defaultSizes: 'parsed',
      // 压缩算法（用于计算压缩大小）
      compressionAlgorithm: 'gzip',
      // 是否自动打开浏览器
      openAnalyzer: true,
      // 是否生成 stats 文件
      generateStatsFile: true,
      // stats 文件名
      statsFilename: 'stats.json',
      // 日志级别
      logLevel: 'info',
    }),
  ],
}

最小示例

最简使用 — 作为 webpack 插件：

const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
 
module.exports = {
  plugins: [new BundleAnalyzerPlugin()],
}

执行 webpack 构建后，浏览器会自动打开 http://127.0.0.1:8888 展示交互式分析报告。

最简使用 — 作为 CLI 工具：

# 先生成 stats.json（在 webpack 配置中添加 --profile --json > stats.json）
npx webpack --profile --json > stats.json
 
# 使用 CLI 分析已有的 stats 文件
npx webpack-bundle-analyzer stats.json

环境变量控制（生产构建按需开启）：

// webpack.config.js
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
 
const plugins = []
if (process.env.ANALYZE === 'true') {
  plugins.push(new BundleAnalyzerPlugin())
}
 
module.exports = {
  plugins,
}

# 需要分析时运行
ANALYZE=true npm run build

核心概念与架构

核心概念

Treemap（树形图）：一种使用嵌套矩形展示层级结构数据可视化方式。在 webpack-bundle-analyzer 中，每个矩形代表一个模块，面积与其在 bundle 中的体积成正比。通过颜色区分不同的 chunk，通过大小直观反映体积占比。

三种大小度量：

• Stat Size（声明大小）：模块在 webpack 处理前的原始输入大小，即 webpack 从文件系统读取时的尺寸
• Parsed Size（解析大小）：webpack 处理、编译、压缩后的实际输出大小
• Compressed Size（压缩大小）：经过 gzip/brotli/zstd 压缩后的传输大小，反映真实的网络传输开销

Chunk（块）：webpack 构建产物的基本单元。分析器以 chunk 为维度组织展示，每个 chunk 对应树形图中的一个颜色区域。

Module（模块）：构成 chunk 的个体单元。每个文件（JS、CSS、图片等）在分析器中都是一个模块，模块间通过包含关系形成层级结构。

架构设计

┌─────────────────────────────────────────────────────────┐
│                  webpack 构建流程                          │
│   源码 → Loader → Plugin → Module Graph → Chunks        │
└────────────────────────┬────────────────────────────────┘
                         │ stats.json（构建统计信息）
                         ▼
┌─────────────────────────────────────────────────────────┐
│              webpack-bundle-analyzer                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Stats 解析   │→│  体积计算     │→│  数据聚合     │  │
│  │  (acorn)     │  │ (gzip/brotli │  │  (模块树构建) │  │
│  │              │  │  /zstd)      │  │              │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                         │                               │
│                         ▼                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │           可视化渲染层                              │   │
│  │  server 模式 → HTTP Server (ws) → 浏览器 Treemap │   │
│  │  static 模式 → 生成独立 HTML 文件                  │   │
│  │  json 模式   → 输出 stats JSON 供 CLI 使用         │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

工作原理

1. 数据收集：通过 webpack 的 stats 对象获取完整的构建统计信息，包括所有模块、chunks、assets 及其依赖关系
2. 体积计算：对每个模块的源码进行 gzip/brotli/zstd 压缩计算，得到不同压缩算法下的传输大小
3. 树形结构构建：将扁平的模块列表按目录路径组织为树形层级结构
4. 可视化渲染：在浏览器中使用 D3.js 渲染交互式 treemap，支持缩放、过滤、搜索等操作
5. 实时交互：server 模式下通过 WebSocket（ws）实现实时数据推送和交互响应

核心特性

• 交互式可缩放 Treemap：以嵌套矩形直观展示模块体积占比，支持点击深入任意层级查看子模块
• 多种大小度量：同时支持 stat、parsed、gzip、brotli、zstd 五种大小显示模式，一键切换
• 三种分析模式：server（实时 HTTP 服务器）、static（独立 HTML 报告）、json（纯数据输出），满足不同场景
• CLI 独立使用：无需修改 webpack 配置，直接分析已有的 stats.json 文件
• Chunk 过滤与上下文菜单：侧边栏可按 chunk 名称过滤，右键菜单可隐藏/显示特定 chunk
• Webpack 5 完整支持：完全兼容 webpack 5，支持 ESM 模块解析（v5.0.0 起）
• Zstandard 压缩分析（v5.2.0+）：支持 Facebook 开发的 Zstandard 压缩算法的体积计算
• 深色/浅色主题切换（v5.1.0+）：UI 支持深色模式和浅色模式，适配不同使用环境
• 可编程 API：提供 start() / stop() 方法，可在代码中动态控制分析器启停
• 绝对路径支持：report 和 stats 文件支持绝对路径输出，方便 CI/CD 集成

生态图

生态系统概览

webpack-bundle-analyzer 位于 webpack 工具链的核心位置，是 webpack 官方推荐的 bundle 分析工具。它向上对接各主流框架的集成封装，向下提供可编程 API 供自定义工作流调用。

关键依赖

框架集成

社区扩展

• webpack-bundle-analyzer-brotli：独立的 Brotli 压缩分析扩展
• relative-ci/agent：基于 webpack-bundle-analyzer 数据的 CI bundle 监控服务
• bundlesize：与 CI 集成的 bundle 大小检查工具，可配合使用
• bundlewatch：bundle 大小守卫工具，防止 PR 引入体积回归

相关工具

• size-limit：基于 esbuild 的轻量级 bundle 大小限制工具
• source-map-explorer：基于 source map 的通用 bundle 分析工具（不依赖 webpack）
• rollup-plugin-visualizer：Rollup/Vite 生态的 bundle 可视化工具
• speed-measure-webpack-plugin：webpack 构建速度与体积分析工具

适用场景

1. 首屏加载性能优化

通过分析首屏 bundle 的模块组成，识别体积过大的依赖（如 moment.js、lodash 全量引入），指导 tree-shaking 和按需引入优化。

2. 代码拆分（Code Splitting）策略评估

在配置 splitChunks 后，通过对比分析前后各 chunk 的体积分布，验证拆分策略是否达到预期效果，确保各 chunk 体积均衡。

3. 依赖泄漏排查

发现不应出现在客户端 bundle 中的服务端模块（如 Node.js 内置模块、数据库驱动等），或意外引入的大型工具库。

4. 版本升级影响评估

升级 webpack、babel、或核心依赖后，对比新旧 bundle 分析结果，量化体积变化，防止升级引入隐性体积增长。

5. 按需加载验证

确认动态 import() 是否正确触发代码拆分，异步 chunk 是否按预期独立生成，懒加载组件是否包含冗余依赖。

6. CI/CD 体积守卫

生成静态 JSON 报告，配合 bundlesize 或 size-limit 在 CI 流程中设置体积阈值，自动拦截超标的 PR。

7. 多入口项目分析

对于多 entry 的 webpack 项目，分析各入口的共享模块与独立模块，优化 splitChunks.cacheGroups 配置。

开发与工程化

开发流程

本地开发：

# 克隆仓库
git clone https://github.com/webpack/webpack-bundle-analyzer.git
cd webpack-bundle-analyzer
 
# 安装依赖
npm install
 
# 运行测试
npm test
 
# 构建
npm run build

项目结构（关键目录）：

webpack-bundle-analyzer/
├── src/
│   ├── analyzer.js         # 核心分析逻辑
│   ├── viewer.js           # 可视化渲染层
│   ├── BundleAnalyzerPlugin.js  # webpack 插件入口
│   └── utils.js            # 工具函数
├── public/                 # 前端 treemap 客户端资源
├── test/                   # 测试用例
└── package.json

CI/CD 集成

GitHub Actions 集成示例：

# .github/workflows/bundle-analysis.yml
name: Bundle Analysis
 
on:
  pull_request:
    branches: [main]
 
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build with analysis
        run: npm run build:analyze
        env:
          ANALYZE: 'true'
 
      - name: Upload bundle report
        uses: actions/upload-artifact@v4
        with:
          name: bundle-report
          path: dist/report.html
 
      - name: Check bundle size
        run: npx bundlesize
        env:
          BUNDLESIZE_GITHUB_TOKEN: ${{ secrets.BUNDLESIZE_GITHUB_TOKEN }}

package.json scripts 配置：

{
  "scripts": {
    "build": "webpack --mode production",
    "build:analyze": "cross-env ANALYZE=true webpack --mode production",
    "build:report": "webpack --mode production --profile --json > stats.json && webpack-bundle-analyzer stats.json --mode static",
    "bundle:check": "bundlesize"
  }
}

工程化最佳实践

• 使用 analyzerMode: 'static' 生成可持久化的 HTML 报告，方便归档和分享
• 在 CI 中使用 analyzerMode: 'json' 输出结构化数据，配合自定义脚本做趋势对比
• 通过 excludeAssets 过滤掉 sourcemap、字体等无需分析的 assets
• 使用 statsOptions 精确控制 stats 输出内容，减少不必要的信息
• 为不同环境（development/production）配置不同的分析策略

性能与安全

性能特点

• 构建开销：插件模式会增加约 1-3 秒的构建时间，主要来自压缩大小计算
• 内存占用：大型项目（1000+ 模块）的 stats.json 可达数十 MB，分析时内存占用较高
• 前端渲染：treemap 客户端使用虚拟化渲染，即使数千个模块也能流畅交互
• WebSocket 通信：server 模式下通过 ws 实时通信，延迟极低

优化建议

• 限制分析范围：通过 excludeAssets 排除不需要分析的 assets，减少计算量
• 按需开启：仅在需要分析时启用，不要在生产构建中默认开启
• stats 优化：使用 statsOptions 减少 stats 输出的冗余信息
• 并行构建：对于大型 monorepo，可以对各子包分别生成 stats 再合并分析

安全注意事项

• Server 模式仅监听本地：默认 analyzerHost: '127.0.0.1'，切勿修改为 0.0.0.0 暴露到公网
• stats.json 敏感信息：stats 文件中可能包含项目结构、模块路径等信息，不应提交到公开仓库
• 报告文件访问控制：生成的 HTML 报告包含完整的 bundle 结构，部署到可访问地址时需注意权限控制
• 依赖安全：定期检查 acorn、ws 等依赖的安全更新

已知性能瓶颈

• 超大项目（5000+ 模块）的 Parsed Size 计算可能耗时较长
• Brotli 压缩计算比 gzip 慢，超大 bundle 可能需要更多等待时间
• stats.json 文件体积过大时，前端加载和解析可能卡顿
• output.module: true 的 ESM 构建在 v5.0.0 之前存在解析错误（已修复）

技术对比

与同类 Bundle 分析工具对比

选型建议

最佳实践

生产环境最佳实践

1. 使用环境变量按需开启

// webpack.config.js
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer')
 
module.exports = (env) => ({
  plugins: [
    env.ANALYZE && new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      reportFilename: 'bundle-report.html',
      openAnalyzer: false,
      generateStatsFile: true,
    }),
  ].filter(Boolean),
})

2. 结合 Next.js 使用 @next/bundle-analyzer

// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
 
module.exports = withBundleAnalyzer({
  // ... Next.js 配置
})

3. 多度量维度分析

new BundleAnalyzerPlugin({
  // 默认显示 gzip 大小（最接近实际传输开销）
  defaultSizes: 'gzip',
  generateStatsFile: true,
  statsOptions: {
    // 仅保留必要信息，减少 stats 文件体积
    source: false,
    moduleAssets: false,
    nestedModules: false,
  },
})

4. CI 中的趋势对比

#!/bin/bash
# 对比当前分支与 main 分支的 bundle 大小
npm run build:analyze
CURRENT_SIZE=$(cat stats.json | jq '.assets[0].size')
git checkout main
npm run build:analyze
MAIN_SIZE=$(cat stats.json | jq '.assets[0].size')
 
echo "Main: $MAIN_SIZE bytes"
echo "Current: $CURRENT_SIZE bytes"
echo "Diff: $((CURRENT_SIZE - MAIN_SIZE)) bytes"

常见陷阱

❌ 在生产构建中默认启用 始终使用环境变量控制，避免每次构建都生成报告文件和不必要的构建开销。

❌ 混淆 stat 大小和压缩大小 stat 大小是模块原始大小，gzip 才是实际传输大小。应以压缩大小作为优化决策依据。

❌ 忽略 tree-shaking 失效 分析结果中出现整个 lodash 或 moment.js，说明 tree-shaking 未生效。需要检查 sideEffects 配置和 import 方式。

❌ 忽略 vendor chunk 体积膨胀 升级依赖后 vendor chunk 突然增大，可能是新版本的依赖引入了更多代码。定期对比 vendor chunk 变化趋势。

❌ 在 monorepo 中混用多个分析器实例 多个 webpack 配置同时启动分析器会导致端口冲突。使用 analyzerPort: 'auto' 或为每个子包指定不同端口。

推荐模式

• 日常开发：使用 CLI 模式分析已有的 stats.json，避免修改 webpack 配置
• 发布前检查：使用 static 模式生成报告，团队 review 确认体积合理
• CI 守护：使用 json 模式输出数据，配合 bundlesize 做自动阈值检查
• 性能调研：使用 server 模式的交互式界面深入探索模块组成

技术局限与边界

已知限制

1. 仅支持 Webpack：不支持 Vite（Rollup）、esbuild、SWC、Turbopack 等非 webpack 构建工具。Vite 项目应使用 rollup-plugin-visualizer。

2. 不支持运行时分析：只能分析构建时的静态模块组成，无法反映动态 import() 的实际运行时加载行为。

3. 压缩计算近似值：gzip/brotli 压缩大小是对单个模块独立压缩的结果，不等于整个 bundle 一起压缩的实际大小（模块间存在共享字典，整体压缩通常更小）。

4. CSS 分析有限：对 CSS Modules、CSS-in-JS 等场景的模块归属分析不够精确，可能将 CSS 模块归属到不正确的 chunk。

5. 无法分析非 JS 资源：对图片、字体、WASM 等非 JS 资源只能展示文件大小，无法展示其内部结构。

6. 大型项目性能瓶颈：超过 5000 个模块的项目，stats 解析和 treemap 渲染可能出现明显卡顿。

7. 无增量分析能力：每次构建都需要全量重新分析，不支持只分析变更部分。

8. 不支持 Turbopack：Next.js 15+ 的 Turbopack 使用不同的构建管线，webpack-bundle-analyzer 无法直接分析 Turbopack 的产物。

不适用场景

• 非 webpack 构建工具（Vite、Rollup、esbuild、Turbopack）
• 需要精确到字节级别的 bundle 分析（应使用 source-map-explorer）
• CI 中的自动体积阈值检查（应使用 size-limit 或 bundlesize）
• 运行时 bundle 加载行为分析（需要 Performance API 或 Lighthouse）
• 需要 bundle diff 功能（当前版本不支持，社区有 feature request #403）

权衡取舍

学习资源

官方文档

• GitHub README — 完整的配置选项说明和使用示例
• Webpack 官方指南 - Bundle Analysis — webpack 官方推荐的 bundle 分析方法
• CHANGELOG.md — 完整的版本变更记录

教程

• How to Use Webpack Bundle Analyzer: Complete Guide — 从零开始的完整教程
• Improve React App Performance With Webpack Bundle Analyzer — 结合 React 项目的实战教程
• Everything You Need to Know About Webpack's Bundle-Analyzer — 全面的功能介绍
• Bundle Size Investigation: A Step-by-Step Guide — 系统化的 bundle 大小调查方法论
• Bundle Analysis Deep Dive | React Performance — Steve Kinney 的 React 性能课程中的 bundle 分析章节
• Webpack Bundle Analyzer：深入分析与优化你的包 — 掘金中文深度教程
• Bundle 分析與最佳化：現代化構建工具的效能調優技巧 — iT 邦帮忙中文技术教程

视频资源

• How to use Webpack Bundle Analyzer — YouTube 视频教程
• Webpack - Ep. 25 - SplitChunks and the Bundle Analyzer — 结合 SplitChunks 的实战视频

社区资源

• NPM Trends 对比 — 与同类工具的下载量趋势对比
• npm-compare 中文对比 — 包体积分析工具中文对比
• GitHub Discussions — 官方讨论区，包含功能请求和使用问答

2026 年现状

最新版本

截至 2026 年 7 月，最新版本为 v5.3.0（2026-03-25 发布）。

v5.x 系列版本演进时间线：

发展趋势

1. 积极维护中：2025 年末至 2026 年初，短短 5 个月内发布了 6 个版本，更新频率显著高于 4.x 时代（4.x 最后一个版本为 4.10.2，发布于 2023 年）。

2. 现代化升级：v5.0.0 丢弃了历史包袱，要求 Node.js >= 20.9.0，代码层面开始采用现代 ECMA 特性（v5.3.0），为后续演进奠定基础。

3. 压缩算法扩展：从 v5.0 仅支持 gzip/brotli，到 v5.2 新增 Zstandard 支持，反映了前端压缩技术多元化的趋势。

4. UI 改进：v5.1.0 的深色/浅色主题切换表明团队关注用户体验，这在同类工具中较为领先。

5. 组织归属强化：仓库已从 webpack-contrib 迁移至 webpack 官方组织，表明其作为 webpack 核心工具的地位得到官方认可。

社区活跃度

未来展望

• Webpack 6 适配：随着 webpack 6 的开发推进，webpack-bundle-analyzer 预计将跟进适配
• Turbopack 支持：社区对 Turbopack 分析的需求日益增长，但目前尚无官方计划，可能需要独立的分析工具
• Bundle Diff：社区长期请求的功能（Issue #403），未来版本可能纳入路线图
• 性能优化：针对超大项目的解析性能有进一步优化空间，尤其是 ESM 模块解析方面
• WebpackPlugin 插件 API 演进：可能利用 webpack 新的插件 API 获取更精确的模块粒度信息

竞品动态

• rollup-plugin-visualizer（v7.0.1）：随着 Vite 生态的崛起，在 Rollup/Vite 用户群中占据主导，但在 webpack 生态中无法替代 webpack-bundle-analyzer
• source-map-explorer（v2.5.3，2022 年后停滞）：维护活跃度下降，不适合新项目选用
• size-limit：在 CI 体积守卫领域持续领先，但与 webpack-bundle-analyzer 定位不同，更多是互补关系
• RelativeCI：商业化的 bundle 监控服务，底层部分依赖 webpack-bundle-analyzer 的数据，面向企业用户

总结：webpack-bundle-analyzer 在 2026 年依然是 webpack 生态中不可替代的 bundle 分析工具，社区活跃、维护积极、功能持续演进。对于使用 webpack 构建的项目，它仍然是首选的 bundle 可视化分析方案。