Bundlephobia

🏋️ 在添加 npm 依赖之前，了解它对前端打包体积的影响——一站式 npm 包体积分析工具。

技术简介说明

Bundlephobia 是前端生态中最知名的 npm 包体积分析工具之一。它允许开发者在将一个新的 npm 包添加到项目之前，快速查询该包经过 minified 和 gzipped 压缩后对最终打包产物的体积贡献。与传统的本地打包分析工具不同，Bundlephobia 作为一个在线服务，通过服务端真实打包（使用 Rollup/esbuild）来模拟浏览器环境下的代码体积，给出了最接近真实生产环境的测量结果。

Bundlephobia 的核心价值在于其「选型前置」能力——开发者不需要先安装依赖、配置打包工具、运行完整构建后才能获得体积数据。只需在网页上搜索包名，或通过 API/CLI 查询，即可获得 minified 体积、gzipped 体积、tree-shaking 支持情况、依赖树分析和导出组成分析（Export Analysis）等关键指标。这对于控制前端包体积、防止「依赖膨胀」具有重要意义。

该工具自 2017 年上线以来，迅速成为前端社区的标配工具，被 Shields.io 集成为官方 badge 数据源，被 Import Cost（VS Code 扩展）等工具作为底层数据参考，也是各类「如何选择 npm 包」指南中的推荐工具。截至 2025 年，Bundlephobia 仍在运行，但维护节奏明显放缓，社区出现了多个替代方案。

基本信息

快速上手

安装

方式一：Web 界面（无需安装）

直接访问 https://bundlephobia.com，在搜索框中输入 npm 包名即可查询。

方式二：CLI 工具 bundle-phobia-cli

# 全局安装
npm install -g bundle-phobia-cli
 
# 或使用 npx 免安装运行
npx bundle-phobia-cli react lodash

注意：CLI 工具 bundle-phobia-cli 由社区开发者 AdrieanKhisbe 维护，非 Bundlephobia 官方出品，但调用 Bundlephobia 的 API 数据。

方式三：API 调用

# 查询单个包的体积
curl "https://bundlephobia.com/api/[email protected]"
 
# 查询最新版本的体积
curl "https://bundlephobia.com/api/size?package=lodash"

基础配置

CLI 工具配置

bundle-phobia-cli 支持以下主要参数：

# 查询指定包的体积
bundle-phobia stats react lodash vue
 
# 从 package.json 文件扫描所有依赖
bundle-phobia stats --from package.json
 
# 指定版本或版本范围
bundle-phobia stats [email protected]
 
# 设置单包体积上限（字节）
bundle-phobia install --max-size 50000 react
 
# 设置所有新增依赖的总大小上限
bundle-phobia install --max-total-size 200000 react lodash
 
# 输出 JSON 格式
bundle-phobia stats --json react
 
# 提取特定指标
bundle-phobia stats --grep "gzip" react

API 参数

GET https://bundlephobia.com/api/size?package=<name[@version]>

最小示例

Web 界面

1. 打开 bundlephobia.com
2. 输入 react 并按回车
3. 查看结果：minified 体积、gzipped 体积、依赖树、导出分析

CLI 最小使用

# 一步查询
npx bundle-phobia-cli react
# 输出: [email protected] — Minified: 42.3 kB, Gzipped: 14.8 kB

API 最小使用

const res = await fetch('https://bundlephobia.com/api/size?package=react');
const data = await res.json();
console.log({
  name: data.name,
  version: data.version,
  size: data.size,       // minified 体积（字节）
  gzip: data.gzip,       // gzipped 体积（字节）
  dependencyCount: data.dependencyCount,
});

API 响应结构

{
  "name": "react",
  "version": "18.2.0",
  "description": "React is a JavaScript library for building user interfaces.",
  "repository": "https://github.com/facebook/react",
  "size": 44312,
  "gzip": 15234,
  "dependencyCount": 2,
  "assets": [
    {
      "type": "script",
      "name": "index.js",
      "size": 44312,
      "gzip": 15234
    }
  ]
}

核心概念与架构

工作原理

Bundlephobia 的核心流程如下：

1. 接收查询：通过 Web UI / API / CLI 接收目标 npm 包名和版本号
2. 下载包：从 npm registry 下载目标包及其所有依赖
3. 服务端打包：使用 Rollup / esbuild 在服务端对包进行真实打包（bundle），模拟浏览器环境
4. 计算体积：
   • Minified 体积：经过 JS 压缩（去除空白、缩短变量名等）后的代码大小
   • Gzipped 体积：在 minified 基础上再进行 gzip 压缩后的大小
5. 分析导出：通过静态分析 ESM 导出，提供每个导出的体积贡献
6. 返回结果：将分析结果返回给前端展示或 API 响应

核心概念

打包策略

Bundlephobia 使用服务端打包来模拟真实浏览器场景，而非简单的文件大小累加。这意味着：

• 共享依赖会被正确去重
• 死代码会被消除（tree-shaking）
• 测量的是「用户实际下载的代码量」而非「磁盘上的文件大小」

核心特性

1. npm 包体积实时查询

输入任意 npm 包名即可获取 minified 和 gzipped 体积数据，支持指定版本查询和历史版本对比。

2. Tree-Shaking 支持分析

自动检测包是否支持 tree-shaking，标注 ESM/CommonJS 模块类型。支持 tree-shaking 的包可以显著减少最终打包体积。

3. 导出组成分析（Export Analysis）

对包的每个导出（export）进行体积拆解，以可视化图表展示各导出的体积占比，帮助开发者判断是否可以只导入需要的部分。

4. package.json 扫描

支持上传或扫描 package.json 文件（Beta 功能），一次性列出所有依赖的体积贡献，快速定位体积瓶颈。

5. 依赖树分析

展示包的完整依赖关系图，帮助评估依赖链的复杂度和潜在风险。

6. 相似包推荐（Similar Packages）

推荐功能相似但体积更小的替代包，帮助开发者进行依赖选型优化。

7. 多版本对比

支持查询同一包不同版本的体积变化，追踪版本升级带来的体积影响。

8. Shields.io Badge 集成

通过 Shields.io 提供 README 可用的体积 badge，支持 min（minified）和 minzip（gzipped）两种格式：

![bundle size](https://img.shields.io/bundlephobia/min/react)
![bundle size gzip](https://img.shields.io/bundlephobia/minzip/react)

9. 非官方 CLI 工具

社区维护的 bundle-phobia-cli 支持命令行查询、package.json 扫描、体积阈值限制等功能。

10. MCP Server 集成（2025+）

2025 年出现了 Bundlephobia MCP Server（如 pipeworx-io/mcp-bundlephobia），使 AI 助手（Claude、Cursor 等）可以直接查询包体积数据。

生态图

生态系统概览

Bundlephobia 生态系统
│
├── Web 界面 ─────────── bundlephobia.com（核心产品）
│   ├── 包搜索与查询
│   ├── package.json 扫描（Beta）
│   ├── 导出分析
│   └── 相似包推荐
│
├── API ──────────────── /api/size?package=<name>
│   ├── 无官方文档（非公开 API）
│   ├── 社区 TypeScript 客户端：ElJijuna/bundlephobia-api-client
│   └── 被 Shields.io、Import Cost 等工具作为数据源
│
├── CLI ──────────────── bundle-phobia-cli（社区维护）
│   ├── stats 命令：查询包体积
│   └── install 命令：带体积阈值的安装
│
├── VS Code 扩展 ─────── Import Cost（by Wix）
│   └── 编辑器内联显示 import 体积（使用 Bundlephobia 类似逻辑）
│
├── GitHub Actions ───── check-my-bundlephobia
│   └── PR 评论依赖体积变化
│
├── MCP Server ───────── mcp-bundlephobia（pipeworx-io）
│   ├── size / similar / history / recent_searches 工具
│   └── 支持 Claude Desktop、Cursor、Windsurf 等
│
├── Badge ────────────── Shields.io
│   ├── /bundlephobia/min/:package
│   └── /bundlephobia/minzip/:package
│
└── 替代工具 ──────────── bundlejs.com / pkg-size.dev / packagephobia.com

API 客户端库

VS Code 扩展

GitHub Actions

适用场景

1. 依赖选型评估

在引入新的 npm 包之前，通过 Bundlephobia 快速对比候选包的体积影响，选择体积更合理的方案。例如在 moment (233 kB gzipped) 和 dayjs (2 kB gzipped) 之间做选择。

2. 包体积预算控制

团队设定依赖体积预算，使用 CLI 工具或 GitHub Action 在 CI 中自动检查新依赖是否超标，防止「依赖膨胀」。

3. Tree-Shaking 兼容性调研

评估候选包的 tree-shaking 支持情况——是否提供 ESM 格式、是否标记 sideEffects: false、导出粒度是否合理。

4. 依赖升级影响评估

对比包的多个版本体积变化，评估升级是否会带来显著的体积增长，辅助版本决策。

5. 性能优化定位

通过导出组成分析（Export Analysis）定位包内的体积大户，决定是否可以用更轻量的子路径导入替代全量引入。

6. README Badge 展示

开源项目通过 Shields.io 在 README 中展示包体积 badge，让使用者直观了解包的轻量程度。

7. 技术分享与团队培训

使用 Bundlephobia 的可视化结果（依赖树、导出分析图表）帮助团队成员理解依赖管理的重要性。

开发与工程化

API 集成

由于 Bundlephobia 没有官方公开 API 文档，集成时需注意：

// 基本 API 调用示例
async function getPackageSize(packageName, version) {
  const packageStr = version ? `${packageName}@${version}` : packageName;
  const url = `https://bundlephobia.com/api/size?package=${encodeURIComponent(packageStr)}`;
  
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Bundlephobia API error: ${response.status}`);
  }
  
  return response.json();
  // 返回: { name, version, size, gzip, dependencyCount, assets, ... }
}

CI/CD 集成

GitHub Action: check-my-bundlephobia

# .github/workflows/bundle-size.yml
name: Bundle Size Check
 
on:
  pull_request:
    branches: [main]
 
jobs:
  check-bundle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check Bundle Size
        uses: carlesnunez/check-my-bundlephobia@v1
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          strict: true          # 超标时阻止合并
          threshold: 50000      # 50KB 阈值
          ignore-dev-dependencies: true

CLI 在 CI 中使用

# 安装 CLI
npm install -g bundle-phobia-cli
 
# 检查新增依赖体积
bundle-phobia stats --from package.json
 
# 带体积阈值的安装（CI 中推荐）
bundle-phobia install --max-size 100000 some-new-package

MCP 集成（AI 助手）

{
  "mcpServers": {
    "bundlephobia": {
      "url": "https://gateway.pipeworx.io/bundlephobia/mcp"
    }
  }
}

配置后可在 Claude Desktop、Cursor 等 AI 工具中直接询问：

• "react 的 gzipped 体积是多少？"
• "推荐比 lodash 更轻量的替代包"
• "对比 axios 和 ky 的近 5 个版本体积变化"

性能与安全

性能特点

安全注意事项

1. 非官方 API：Bundlephobia 的 /api/size 端点并非官方公开 API，可能随时变更或被限制，不建议在生产环境中作为关键依赖
2. 速率限制：频繁调用 API 可能触发速率限制或 IP 封锁
3. 数据准确性：测量基于服务端打包，与项目实际打包结果可能存在差异（不同 bundler、配置、target 设置等）
4. 供应链风险：依赖外部服务获取包信息，服务不可用时功能失效
5. CLI 工具来源：bundle-phobia-cli 是社区工具，非官方出品，使用前需评估可信度
6. 私密包支持：Bundlephobia 无法分析私有 npm 包（需要认证才能从 registry 下载）

技术对比

Bundlephobia vs Package Phobia vs 其他工具

Bundlephobia vs Package Phobia 核心区别

Bundlephobia 回答的问题是：「这个包加到我的前端 bundle 里，用户需要多下载多少字节？」

Package Phobia 回答的问题是：「运行 npm install 时，这个包（含依赖）会占用多少磁盘空间？」

Bundlephobia = 最终用户视角（运行时体积）
Package Phobia = 开发者视角（安装时体积）

选择建议：

• 关注前端性能、用户体验 → Bundlephobia
• 关注 CI 安装速度、node_modules 体积、devDependencies → Package Phobia
• 两者互补使用效果最佳

Bundlephobia vs bundlejs

bundlejs 是 2025 年最活跃的开源替代方案，优势在于：

• 完全开源，可自行部署
• 支持 Brotli 压缩（比 gzip 更现代）
• 支持 CDN 选择（unpkg、esm.sh、skypack）
• 支持代码片段直接打包分析
• 提供 treemap/sunburst 可视化

Bundlephobia 的优势在于：

• 更成熟的分析能力（导出分析、相似包推荐）
• 更完善的生态系统（Shields.io、GitHub Actions、MCP Server）
• 社区知名度更高，历史数据更丰富

最佳实践

使用建议

1. 优先关注 Gzipped 体积：这是用户实际通过网络传输下载的体积，比 minified 体积更有参考价值

2. 利用导出分析做精准优化：不要只看总包体积，通过 Export Analysis 找到实际导入的部分，评估是否可以通过子路径导入减少体积

3. 对比同类替代包：使用相似包推荐功能或手动在 Bundlephobia 上对比，选择体积合理的替代方案

4. 建立体积预算机制：在 CI 中集成 check-my-bundlephobia Action，设定体积阈值，超标时阻止合并

5. 关注 tree-shaking 支持：优先选择支持 tree-shaking 的包（ESM 格式 + sideEffects: false），确保只打包实际使用的代码

6. 版本升级前查体积变化：使用多版本对比功能，评估升级是否会带来显著的体积增长

7. 结合本地打包分析：Bundlephobia 测量的是「包本身」的体积，实际项目中的体积还受 bundler 配置、target、polyfill 等影响，需结合 Webpack Bundle Analyzer 等本地工具综合判断

常见陷阱

技术局限与边界

已知限制

1. 非官方 API：/api/size 端点没有官方文档，不承诺稳定性，可能随时变更或添加限制
2. 测量偏差：服务端使用 Rollup/esbuild 打包，与项目实际的 Webpack/Vite/esbuild 配置可能存在差异
3. 不支持私有包：无法分析需要认证的私有 npm 包
4. 不支持 monorepo 工作区：无法分析 workspace 内部依赖的体积
5. CSS/Sass 支持有限：主要针对 JS/TS 包，CSS 库的测量精度不如专业工具
6. 服务端打包时间：冷门包的首次查询可能较慢（需要服务端下载和打包）
7. 不支持自定义配置：无法模拟项目的 babel 配置、target 设置、polyfill 策略等
8. 速率限制：频繁 API 调用可能触发限流，不适合大规模自动化扫描
9. 维护节奏放缓：项目最后一次代码发布在 2019 年，虽然 Web 服务仍在运行，但新特性开发停滞
10. 导出分析不覆盖所有包：部分使用 CommonJS 或动态导出的包无法进行导出级别分析

不适用场景

• 分析私有/内部 npm 包
• 需要精确匹配项目实际打包结果的场景
• 需要离线使用或自部署的场景（考虑 bundlejs 作为替代）
• 大规模依赖审计（应考虑本地工具如 source-map-explorer）
• 需要分析运行时性能而非静态体积的场景

学习资源

官方资源

• Bundlephobia 官网 — 在线包体积查询
• GitHub 仓库 — 源码、Issue 和 Discussion
• GitHub Discussions — 社区讨论

教程与文章

• How to Speed Up Your App with Bundlephobia Package Analysis — YouTube 视频教程（2024）
• How to Worry About npm Package Weight — CSS-Tricks — 使用 Bundlephobia 进行依赖体重管理
• Keep Your Javascript Bundle Size in Check — Simon Wicki — 全面的包体积检查工具对比
• Bundle Size Investigation — The Developer Way — 深度包体积调查指南（2025）
• Better Know Your NPM Package Bundles — Medium — NPM 包体积分析进阶
• Evaluate and Find the Cost of Adding an npm Package — Dev.to — Bundlephobia 使用入门
• Measure Package Sizes Effectively — sordyl.dev — 包体积测量深度分析

社区资源

• Hacker News 讨论 — Bundlephobia 社区讨论
• Reddit r/javascript 讨论 — Reddit 社区讨论
• bundlephobia-api-client — TypeScript API 客户端
• mcp-bundlephobia — MCP Server（AI 助手集成）

相关工具文档

• Import Cost VS Code 扩展 — 编辑器内联体积显示
• check-my-bundlephobia — GitHub Action
• bundle-phobia-cli — 命令行工具
• Shields.io Bundlephobia Badge — 体积 Badge

2026 年现状

服务状态

截至 2026 年 7 月，Bundlephobia Web 服务仍在正常运行。访问 bundlephobia.com 可以正常查询包体积数据，网站新增了 package.json 扫描功能（仍处于 Beta 状态）。

维护状态

• 代码仓库：最后一次正式发布（release）在 2019 年 10 月，核心代码库更新节奏极慢
• Web 服务：持续运行，但曾出现间歇性不可用事件（如社区报告的服务中断）
• 维护者：Shubham Kanodia（pastelsky）仍在管理项目，但已公开表示 正在寻找贡献者和共同维护者
• Issue 处理：GitHub Issues 和 Discussions 中仍有社区互动，但官方响应频率较低

生态发展

虽然核心项目维护放缓，但 Bundlephobia 的生态系统仍在扩展：

• MCP Server（2025）：pipeworx-io/mcp-bundlephobia 出现，使 AI 助手可直接查询包体积
• mcp-server-npm-plus（2026）：更综合的 npm 分析 MCP Server 集成了 Bundlephobia 数据
• GitHub 社区讨论（2025）：有建议在 GitHub 包页面集成 Bundlephobia 体积数据的讨论
• 替代工具活跃：bundlejs.com、pkg-size.dev 等开源替代品在持续迭代

未来展望

• Bundlephobia 作为「npm 包体积查询」的代名词，其在社区中的地位短期内难以被完全替代
• 如果维护者未能找到新的共同维护者，项目可能逐步进入「维护模式」，仅保持服务运行而不再开发新特性
• 对于新项目，建议将 Bundlephobia 作为参考工具之一，同时关注 bundlejs、pkg-size.dev 等更活跃的替代方案
• MCP Server 的出现为 Bundlephobia 的数据提供了新的消费方式，是其在 AI 时代的新增长点