rollup-plugin-visualizer

可视化分析 Rollup/Vite 打包产物，快速定位大模块并优化 Bundle 体积的必备工具

Bundle分析性能优化RollupVite

Rollup 生态最受欢迎的打包分析插件，在构建完成后生成交互式可视化报告，直观展示每个模块在最终产物中的体积占比，是 Vite 项目进行 Bundle 分析的事实标准。

rollup-plugin-visualizer

可视化分析 Rollup/Vite 打包产物，快速定位大模块并优化 Bundle 体积的必备工具。

技术简介说明

rollup-plugin-visualizer 是 Rollup 生态中最受欢迎的打包分析插件之一，由 Denis Bardadym 创建于 2016 年。它的核心功能是在构建完成后生成一份交互式可视化报告（HTML/SVG/JSON），直观展示每个模块在最终产物中的体积占比，帮助开发者快速识别"体积大户"并进行针对性优化。

在 Vite 成为主流构建工具后，该插件的重要性进一步提升——因为 Vite 的生产构建底层依赖 Rollup，所以 rollup-plugin-visualizer 自然成为了 Vite 项目进行 Bundle 分析的事实标准。相比 Webpack 生态的 webpack-bundle-analyzer，它在 Rollup/Vite 领域几乎没有真正的竞争对手。

截至 2026 年初，该插件已迭代到 v7.x 版本，完成了 ESM-only 迁移，支持 Node.js 22+，并新增了对 Rolldown（Rust 版 Rollup 继任者）的兼容支持。GitHub 上拥有 2.4k Stars，npm 周下载量超过 650 万次，是前端性能优化领域的核心基础设施之一。

基本信息

项目	信息
官网	https://www.npmjs.com/package/rollup-plugin-visualizer
GitHub	https://github.com/btd/rollup-plugin-visualizer
License	MIT
最新版本	v7.0.1（2026 年 Q1 发布）
主要维护者	Denis Bardadym（btd）
GitHub Stars	~2,400
npm 周下载量	~6,500,000+
Open Issues	~12
Node.js 要求	v22+（v7.x），v20+（v6.x）
模块类型	ESM-only（v7.x 起）

快速上手

安装

# npm
npm install rollup-plugin-visualizer --save-dev
 
# pnpm（推荐）
pnpm add rollup-plugin-visualizer -D
 
# yarn
yarn add rollup-plugin-visualizer --dev

注意：v7.x 起要求 Node.js 22+，并且仅支持 ESM。若使用 CommonJS 或 Node.js < 22，请使用 v6.x（pnpm add rollup-plugin-visualizer@6 -D）。

基础配置

Vite 项目集成（最常见用法）

// vite.config.ts
import { defineConfig } from 'vite'
import { visualizer } from 'rollup-plugin-visualizer'
 
export default defineConfig({
  plugins: [
    // ...其他插件
    visualizer({
      open: true,          // 构建完成后自动在浏览器打开报告
      gzipSize: true,      // 显示 gzip 压缩后大小
      brotliSize: true,    // 显示 brotli 压缩后大小
      filename: 'stats.html', // 输出文件名
      template: 'treemap',  // 可视化模板（默认 treemap）
    }),
  ],
})

Rollup 原生项目集成

// rollup.config.js
import { visualizer } from 'rollup-plugin-visualizer'
 
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
  },
  plugins: [
    visualizer({
      filename: 'stats.html',
      gzipSize: true,
      brotliSize: true,
    }),
  ],
}

条件启用（仅分析时开启）

// vite.config.ts
import { defineConfig } from 'vite'
import { visualizer } from 'rollup-plugin-visualizer'
 
const enableVisualizer = process.env.ANALYZE === 'true'
 
export default defineConfig({
  plugins: [
    enableVisualizer && visualizer({
      open: true,
      gzipSize: true,
      brotliSize: true,
      filename: 'dist/stats.html',
    }),
  ].filter(Boolean),
})

然后通过 ANALYZE=true pnpm build 触发分析构建。

最小示例

# 1. 安装
pnpm add rollup-plugin-visualizer -D

// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer'
 
export default {
  plugins: [
    visualizer({ open: true }),
  ],
}

# 2. 构建
pnpm build
# 浏览器会自动打开 stats.html 报告

核心概念与架构

工作原理

rollup-plugin-visualizer 利用 Rollup 的 generateBundle 钩子拦截构建产物，收集每个模块的元数据（模块 ID、源码大小、压缩后大小等），然后将这些数据注入到预定义的 HTML 模板中，生成一份完全自包含的交互式报告。

报告本身是一个单文件 HTML，内嵌了所有数据和前端渲染逻辑（基于 D3.js 等可视化库），无需服务器即可在浏览器中直接打开和交互。

可视化模式

模板名称	说明	适用场景
`treemap`	矩形树图（默认），嵌套矩形展示模块层级与体积占比	快速发现大模块、重复依赖
`treemap-3d`	3D 树图，以立体方块呈现层次结构	需要更直观的 3D 视角展示
`sunburst`	旭日图，同心环展示层级关系	理解模块嵌套结构和依赖层次
`flamegraph`	火焰图，类似 CPU 火焰图的从上到下视图	审查调用栈和模块链
`network`	网络图，力导向图展示模块间依赖关系	可视化模块间的互相引用关系
`raw-data`	原始数据，输出 JSON 格式	自定义分析、配合 CLI 或第三方工具
`list`	列表视图，YML 格式模块清单	简单查看各模块大小

体积计算维度

原始大小（Raw Size）：模块源码的原始字节数
gzip 大小（gzipSize: true）：模拟 gzip 压缩后的体积
brotli 大小（brotliSize: true）：模拟 brotli 压缩后的体积
SourceMap 大小（sourcemap: true）：基于 sourcemap 进行更精确的模块大小计算

核心特性

多种可视化模板：支持 treemap、sunburst、flamegraph、network、treemap-3d、raw-data、list 共 7 种可视化模式，满足不同分析视角需求
压缩体积计算：内置 gzip 和 brotli 压缩体积计算，贴近真实传输大小
交互式报告：生成的 HTML 报告支持点击缩放、悬停查看详情、模块搜索过滤等功能
Vite 原生兼容：通过 Rollup 插件机制无缝集成 Vite，是 Vite 生态的标配分析工具
Rolldown 支持：v7.x 新增 Rolldown RC 版本的 peer dependency 支持，面向 Rust 化构建工具的未来
灵活的过滤能力：支持 include / exclude 选项，使用 picomatch 语法过滤需要分析的模块
多输出格式：支持 HTML、SVG、JSON（raw-data）、YML（list）、Markdown 等输出格式
emitFile 集成：可通过 Rollup 的 emitFile API 输出报告，自动放入构建输出目录
LLM 友好报告：v7.0.0 新增 Markdown 报告模板，方便 AI 工具直接读取分析结果
SourceMap 精确分析：支持基于 sourcemap 的模块大小计算，提供更准确的体积分布

生态图

与构建工具生态的关系

┌─────────────────────────────────────────────────────┐
│                    Vite 生态                          │
│  ┌──────────┐   ┌──────────┐   ┌──────────────────┐ │
│  │   Vite   │──▶│  Rollup  │──▶│rollup-plugin-    │ │
│  │ (dev:    │   │ (prod    │   │  visualizer      │ │
│  │  esbuild)│   │  build)  │   │  (分析产物)       │ │
│  └──────────┘   └──────────┘   └──────────────────┘ │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│                  Rolldown 生态（新兴）                 │
│  ┌──────────┐   ┌──────────────────┐                │
│  │Rolldown  │──▶│rollup-plugin-    │                │
│  │(Rust 构建)│   │  visualizer      │                │
│  └──────────┘   │  (v7.x 兼容)     │                │
│                  └──────────────────┘                │
└─────────────────────────────────────────────────────┘

关键依赖

D3.js — 报告内部的可视化渲染引擎
picomatch — 模块过滤的 glob 匹配
open — 构建完成后自动打开浏览器
source-map — 基于 sourcemap 的精确体积计算

社区生态

vite-bundle-visualizer — 基于 rollup-plugin-visualizer 的 Vite 封装包装器，提供更便捷的 CLI 体验（周下载量 ~18 万）
@aklinker1/rollup-plugin-visualizer — 知名 fork 版本，被 WXT 浏览器扩展框架采用（周下载量 ~35 万）
@vinxi/rollup-plugin-visualizer — Vinxi 全栈框架的 fork 版本
VS Code 扩展 — "Bundle visualizer" 扩展支持读取 Rollup/Webpack 的 JSON stats 在 VS Code 内可视化
Astro 官方推荐 — Astro 文档中将其作为 Bundle 分析的推荐方案

与 Vite/Rollup 生态的关系

rollup-plugin-visualizer 是 Vite 项目进行生产构建分析的唯一官方推荐方案。Astro、SvelteKit、Nuxt 等基于 Vite 的框架文档中均推荐该工具。在 Rollup 4.x 和即将到来的 Rolldown 中，该插件持续保持兼容性更新。

适用场景

1. Vite 项目 Bundle 体积分析

最常见的场景。在 Vite 项目接入时，只需一行代码即可获得交互式打包分析报告，快速定位哪些依赖占据最多空间。

2. 依赖重复检测与优化

通过 treemap 视图可以清晰看到是否存在同一依赖的多个版本被打包，从而针对性地配置 resolve.alias 或 optimizeDeps 去重。

3. 按需加载与 Code Splitting 评估

分析各 chunk 的体积分布，评估动态 import 策略是否合理，识别需要进一步拆分的过大 chunk。

4. Tree Shaking 效果验证

对比引入某个库前后的产物体积变化，验证 tree shaking 是否正确移除了未使用的代码。

5. CI/CD 构建产物监控

通过 raw-data 或 list 模板输出 JSON/YML 数据，配合 CI 流水线监控 Bundle 体积趋势，设置体积阈值告警。

6. 新旧技术栈迁移对比

从 Webpack 迁移到 Vite 时，对比两个构建工具的产物差异，量化优化效果。

7. 第三方库选型评估

在引入大型第三方库之前，先分析其实际打包体积（含 tree shaking 后），为技术选型提供数据支撑。

开发与工程化

开发流程

# 克隆仓库
git clone https://github.com/btd/rollup-plugin-visualizer.git
cd rollup-plugin-visualizer
 
# 安装依赖
npm install
 
# 开发模式（监听文件变化）
npm run dev
 
# 构建
npm run build
 
# 运行测试
npm test
 
# 代码检查
npm run lint

工程化最佳实践

条件启用，避免影响日常构建

// vite.config.ts
const isAnalyze = process.env.npm_lifecycle_event === 'build:analyze'
 
export default defineConfig({
  plugins: [
    isAnalyze && visualizer({
      open: true,
      gzipSize: true,
      brotliSize: true,
      filename: 'dist/report.html',
      template: 'treemap',
    }),
  ].filter(Boolean),
  // ...
})

// package.json
{
  "scripts": {
    "build": "vite build",
    "build:analyze": "vite build"
  }
}

CI/CD 集成 — 体积监控与告警

# .github/workflows/bundle-monitor.yml
name: Bundle Size Monitor
on: [pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install
      - run: pnpm build:analyze
      - name: Check bundle size
        run: |
          # 解析 raw-data JSON，检查体积阈值
          node scripts/check-bundle-size.js

使用 `emitFile` 输出到构建目录

visualizer({
  emitFile: true,
  filename: 'stats.html',  // 输出到 outDir 下
  template: 'treemap',
})

报告部署

生成的 stats.html 是完全自包含的单文件，可直接部署到静态服务器或 CDN，方便团队共享查看。

性能与安全

性能特点

构建性能影响：gzip/brotli 体积计算会增加构建时间，大型项目可能增加数秒。建议仅在分析构建时启用。
报告性能：对于超大型项目（数千模块），treemap 渲染可能卡顿。可使用 raw-data 模板导出数据，配合外部工具分析。
内存占用：生成报告时需要持有所有模块元数据，内存占用随模块数量增长。

优化建议

日常开发不启用 visualizer，仅在需要分析时通过环境变量开启
大型项目优先使用 sourcemap: true 获取更准确的分析，但要确保 sourcemap 生成不会显著拖慢构建
gzipSize 和 brotliSize 同时开启会增加计算量，按需选择
对超大项目使用 include / exclude 过滤，只关注关键模块

安全注意事项

生成的报告文件包含模块路径和依赖结构信息，不要公开部署到互联网
报告是纯前端 HTML，无服务端交互，本身不存在 XSS 等注入风险
如果使用 open: true，报告会在本地浏览器打开，仅本地可见
raw-data JSON 输出可能包含内部文件路径信息，注意不要泄露到公开仓库

技术对比

与同类 Bundle 分析工具对比

特性	rollup-plugin-visualizer	webpack-bundle-analyzer	esbuild-visualizer	source-map-explorer	vite-bundle-visualizer
适用构建工具	Rollup / Vite	Webpack	esbuild	任何（基于 sourcemap）	Vite（封装）
GitHub Stars	~2.4k	~6.1k	~300+	~5.7k	~300+
npm 周下载量	~650 万	~480 万	~1 万	~120 万	~18 万
可视化模板	7 种	3 种（treemap/stat/list）	1 种（treemap）	1 种（treemap）	继承 visualizer
gzip 大小	✅	✅	有限	✅	✅
brotli 大小	✅	✅	❌	❌	✅
交互式缩放	✅ 点击放大	✅ 鼠标缩放	✅ 基础	✅ 基础	✅
模块搜索/过滤	✅ picomatch	❌	❌	❌	❌
JSON 数据导出	✅ raw-data	✅ stat	❌	✅	✅
Markdown 输出	✅ v7.x	❌	❌	❌	❌
网络图	✅	❌	❌	❌	✅
3D 可视化	✅ treemap-3d	❌	❌	❌	✅
Vite 原生兼容	✅ 直接使用	❌ 需适配	❌	❌	✅
ESM-only	✅ v7.x	❌	✅	❌	✅
维护状态	活跃（2026 持续更新）	活跃	一般	维护模式	维护中

选型建议

Vite / Rollup 项目：毫无疑问选 rollup-plugin-visualizer，这是生态标准
Webpack 项目：选 webpack-bundle-analyzer，功能最成熟
esbuild 项目：选 esbuild-visualizer 或使用 esbuild 官方在线分析器（https://esbuild.github.io/analyze/）
通用 sourcemap 分析：选 source-map-explorer，不依赖特定构建工具
需要更友好的 Vite 报告体验：可考虑 vite-bundle-visualizer 封装