Package-Phobia

在添加 npm 依赖之前，了解它将为你的 node_modules 带来多大的磁盘开销。

技术简介说明

Package Phobia 是一个专注于 npm 包安装体积（Install Size） 的在线分析工具。与 Bundlephobia 等关注浏览器打包体积的工具不同，Package Phobia 回答的是一个更基础的问题：运行 npm install <package> 后，磁盘上会增加多少数据？ 它同时报告 发布体积（Publish Size） ——即包在 npm Registry 上的 tarball 大小——和 安装体积（Install Size） ——即包及其全部传递依赖解压后在磁盘上占据的总空间。

这个工具的诞生源于一个实际痛点：在 Node.js 项目中，node_modules 的膨胀直接影响 CI/CD 流水线的构建时间、Docker 镜像体积、冷启动速度和磁盘资源成本。一个包的发布体积可能很小（例如几百 KB），但安装体积却可能很大（数十 MB），因为其传递依赖可能包含大量原生二进制文件、类型定义、测试文件和文档。Package Phobia 正是为了揭示这种"隐藏的重量"而设计的。

Package Phobia 的独特价值在于它追踪每个包版本的历史体积变化，通过折线图直观展示包随时间的膨胀趋势。这使得开发者可以在选择依赖时做出更明智的决策，也可以在发现包体积突然飙升时及时预警。它特别适合 Node.js 后端项目、CLI 工具、构建插件和开发依赖的评估——这些场景下包不会被打包到浏览器中，因此 bundle size 不是主要关注点，磁盘占用才是。

与 Bundlephobia 的核心区别

简单来说：Package Phobia 关注的是开发者侧的成本（安装时间、磁盘空间、CI 速度），而 Bundlephobia 关注的是用户侧的成本（页面加载速度、下载流量、运行时性能）。

基本信息

• 官网：https://packagephobia.com
• GitHub：https://github.com/styfle/packagephobia
• License：MIT
• 最新版本：持续部署（基于 main 分支自动部署至 Vercel）
• GitHub Stars：约 2.3k
• 总提交数：1,587+
• 技术栈：TypeScript 100%、Next.js、Vercel（托管）、Upstash（数据库）
• 主要维护者：styfle（Steven L. Scott）
• 创建时间：2018 年
• 最近更新：2025 年 3 月（commit 08fcb14）

快速上手

安装

Package Phobia 是一个纯 Web 服务，无需本地安装。直接在浏览器中访问官网即可使用：

# 直接在浏览器中打开
open https://packagephobia.com
 
# 或在 URL 中直接指定包名和版本
# https://packagephobia.com/result?p=express
# https://packagephobia.com/[email protected]

如果你需要在 CI/CD 或脚本中使用，可以通过其 JSON API 调用：

# cURL 调用 API v2
curl "https://packagephobia.com/v2/api.json?p=express"
 
# 指定版本
curl "https://packagephobia.com/v2/[email protected]"
 
# API v1（简洁格式）
curl "https://packagephobia.com/api.json?p=express"

基础配置

Package Phobia 的 Web 界面不需要任何配置。如果你要通过 API 使用，需要注意以下事项：

# API 使用须知
# 1. 需要注册你的域名（domain）和 User-Agent
#    未注册的请求可能会被拒绝
# 2. 缓存策略：
#    - 指定版本的查询：缓存 7 天（Cache-Control: max-age=604800）
#    - 查询最新版本：缓存 30 秒（Cache-Control: max-age=30）
# 3. 请求频率限制存在但未公开具体数值，请合理调用

最小示例

Web 界面使用：

1. 打开 https://packagephobia.com
2. 在搜索框中输入 npm 包名（如 express）
3. 点击搜索，查看发布体积和安装体积的详细信息和历史图表

API 调用示例（v2）：

curl "https://packagephobia.com/v2/[email protected]"

返回结果：

{
  "name": "react",
  "version": "18.2.0",
  "publish": {
    "size": 3686131,
    "pretty": "3.52 MB",
    "files": 18,
    "color": "#df3603"
  },
  "install": {
    "size": 8724612,
    "pretty": "8.32 MB",
    "files": 67,
    "color": "#df3603"
  }
}

API 调用示例（v1）：

curl "https://packagephobia.com/[email protected]"

返回结果：

{
  "publishSize": 3686131,
  "installSize": 8724612
}

核心概念与架构

三种"体积"概念

Package Phobia 的世界观围绕以下三个核心度量展开：

1. 发布体积（Publish Size）

• 定义：npm 包的 tarball（.tgz 文件）在 npm Registry 上的压缩大小
• 影响：包的下载时间、Registry 存储成本
• 特点：不包含未发布的文件（如 .gitignore 中的内容、测试源码等）

2. 安装体积（Install Size）

• 定义：执行 npm install 后，包及其全部传递依赖在磁盘上占据的总字节数
• 影响：node_modules 目录大小、CI/CD 构建时间、Docker 镜像体积
• 特点：包含所有传递依赖、类型定义文件、README、原生二进制等
• 这是 Package Phobia 最核心的度量

3. 打包体积（Bundle Size）——Package Phobia 不测量

• 定义：包代码经过 tree-shaking、minification、gzip/brotli 压缩后，最终进入浏览器 bundle 的大小
• 影响：用户的页面加载速度、网络流量
• 由 Bundlephobia 等工具负责测量

工作原理

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  npm Registry │ ──▶ │ Package Phobia    │ ──▶ │  用户查询界面    │
│  (tarball)    │     │  服务端          │     │  / JSON API     │
└──────────────┘     │                  │     └─────────────────┘
                     │ 1. 下载 tarball   │
                     │ 2. 解压测量       │
                     │ 3. npm install    │
                     │ 4. 测量磁盘占用   │
                     │ 5. 记录历史数据   │
                     └──────────────────┘

1. 下载阶段：从 npm Registry 下载指定版本的 tarball
2. 发布体积测量：直接获取 tarball 的压缩文件大小
3. 安装模拟：在隔离环境中执行 npm install，解析完整依赖树
4. 安装体积测量：统计 node_modules 目录的总大小和文件数量
5. 历史追踪：将数据持久化存储（Upstash），支持按版本时间线展示体积变化
6. 缓存与加速：已查询的包版本结果被缓存，避免重复计算

核心特性

• 📦 双维度测量：同时报告发布体积（Publish Size）和安装体积（Install Size），帮助开发者全面了解包的磁盘成本
• 📈 历史体积图表：追踪每个版本发布以来的体积变化趋势，以折线图形式呈现，可清晰看到何时出现体积突增
• 📁 文件数量统计：显示包包含的文件数量，帮助识别"小文件过多"等潜在问题
• 🎨 体积颜色编码：根据体积大小自动分配颜色（绿色=小、橙色=中等、红色=大），直观判断包体积等级
• 🌐 JSON API（v1/v2）：提供结构化 API 接口，便于集成到 CI/CD 流水线、自定义工具链和监控系统中
• 🛡️ Shields 徽章：支持生成用于 README 文档的体积徽章（类似 shields.io），展示包的体积信息
• 🔄 多版本对比：可查询同一包的不同版本，便于对比升级前后的体积变化
• ⚡ 零安装、零配置：纯 Web 服务，无需本地安装任何工具，打开浏览器即可使用
• 📋 package.json 上传：支持直接上传 package.json 文件，批量分析所有依赖的体积

生态图

生态系统

                    ┌─────────────────────────────────┐
                    │       npm 包体积分析生态          │
                    └─────────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
     ┌────────▼────────┐  ┌────────▼────────┐  ┌────────▼────────┐
     │  安装体积测量    │  │  打包体积测量    │  │  性能预算管理    │
     │                 │  │                 │  │                 │
     │ • Package Phobia│  │ • Bundlephobia  │  │ • size-limit    │
     │ • pkg-size.dev  │  │ • bundlejs      │  │ • bundlesize    │
     │                 │  │                 │  │                 │
     └─────────────────┘  └─────────────────┘  └─────────────────┘

API 体系

v1 API（简洁模式）

GET /api.json?p={package}[@{version}]

返回最小的 JSON 结构，仅包含 publishSize 和 installSize 两个字段（字节数）。

v2 API（详细模式）

GET /v2/api.json?p={package}[@{version}]

返回丰富的 JSON 结构，包含包名、版本、发布/安装的体积、文件数、可读格式（pretty）和颜色编码。

相关工具

适用场景

• 🖥️ Node.js 后端依赖评估 后端包的代码不会进入浏览器 bundle，因此 Bundlephobia 的数据意义有限。Package Phobia 的安装体积直接反映了服务器部署时的磁盘占用和 Docker 镜像大小。

• ⚙️ CI/CD 流水线优化 npm install 是 CI 流水线中最耗时的步骤之一。通过 Package Phobia 评估每个依赖的安装体积，可以识别导致 CI 构建缓慢的"重量级"依赖。

• 🐳 Docker 镜像瘦身 Docker 镜像中的 node_modules 往往是最大的层。使用 Package Phobia 可以在编码阶段就预见依赖对镜像体积的影响，指导选择更轻量的替代方案。

• 🛠️ 开发依赖（devDependencies）审查 对于 ESLint 插件、TypeScript 工具、Babel 预设等开发依赖，它们的安装体积不影响生产 bundle，但会显著影响本地开发环境的 node_modules 大小和首次安装时间。

• 📊 依赖选型对比 在多个功能相似的 npm 包之间做选择时，Package Phobia 可以直观对比它们的安装体积。例如在 moment（大）和 dayjs（小）之间做选择。

• 🔍 包体积膨胀监控 通过历史图表功能，可以持续监控关键依赖的体积变化趋势。当某次版本更新导致体积突增时，可以及时评估是否需要升级或寻找替代方案。

• 📝 技术文档与 RFC 决策支持 在撰写技术 RFC 或架构决策记录时，引用 Package Phobia 的数据可以作为依赖选择的客观依据，增强决策的可追溯性。

开发与工程化

API 集成

在项目中集成 Package Phobia 数据到自动化流程：

#!/bin/bash
# scripts/check-package-size.sh
# 检查指定包的安装体积是否超过阈值
 
PACKAGE=$1
THRESHOLD_BYTES=${2:-10485760}  # 默认 10MB
 
RESPONSE=$(curl -s "https://packagephobia.com/v2/api.json?p=${PACKAGE}")
INSTALL_SIZE=$(echo "$RESPONSE" | jq '.install.size')
 
if [ "$INSTALL_SIZE" -gt "$THRESHOLD_BYTES" ]; then
  echo "❌ $PACKAGE 安装体积 ($(echo "$RESPONSE" | jq -r '.install.pretty')) 超过阈值"
  exit 1
else
  echo "✅ $PACKAGE 安装体积 ($(echo "$RESPONSE" | jq -r '.install.pretty')) 在阈值内"
  exit 0
fi

CI/CD 集成

# GitHub Actions 示例：PR 中检查新增依赖的体积
name: Check Dependency Size
on: [pull_request]
 
jobs:
  check-size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get diff of package.json
        id: diff
        run: |
          # 提取新增的依赖
          NEW_DEPS=$(git diff origin/main -- package.json | grep '^+' | grep -oP '"[^"]+":\s*"[^"]+"' || true)
          echo "new_deps=$NEW_DEPS" >> $GITHUB_OUTPUT
 
      - name: Check sizes of new dependencies
        run: |
          # 对每个新增依赖调用 Package Phobia API
          # 注意：需合理控制请求频率

本地开发集成

// scripts/analyze-deps.mjs
// 读取 package.json 并批量查询所有依赖的安装体积
import { readFileSync } from 'node:fs';
 
const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'));
const deps = Object.keys(pkg.dependencies || {});
 
for (const dep of deps) {
  const res = await fetch(`https://packagephobia.com/v2/api.json?p=${dep}`);
  const data = await res.json();
  console.log(`${data.name}@${data.version}: install=${data.install.pretty}, publish=${data.publish.pretty}`);
}

性能与安全

性能特点

• 查询延迟：首次查询一个包需要下载 tarball 并模拟安装，可能需要 5-30 秒（取决于包大小和依赖复杂度）
• 缓存命中：已查询过的包版本结果会被缓存（指定版本缓存 7 天，最新版本缓存 30 秒），后续查询几乎即时返回
• 并发限制：API 存在隐含的并发/频率限制，大量批量查询时应注意控制请求速率
• 数据库性能：使用 Upstash（Redis 兼容）存储历史数据，读取性能优秀

安全注意事项

• API 认证：API 要求注册域名和 User-Agent，未注册请求可能被拒绝。这是一种基本的访问控制机制
• 数据准确性：安装体积是在隔离服务器环境中通过实际 npm install 测量的，理论上与本地安装结果一致，但可能因平台差异（原生依赖）而略有不同
• 无恶意代码风险：Package Phobia 只是下载和测量包的大小，不执行包中的代码。但测量过程中的 npm install 会触发 postinstall 脚本——官方在隔离环境中运行以降低风险
• 隐私注意：通过 API 查询的包名和版本信息会被记录（用于缓存和统计），敏感项目需注意不要暴露内部包名

技术对比

详细对比表

选型建议

• 评估后端/CLI 依赖 → 优先用 Package Phobia（或 pkg-size.dev）
• 评估前端库的 bundle 影响 → 优先用 Bundlephobia 或 bundlejs
• 需要 CI 性能预算门禁 → 用 size-limit
• 需要最全面的数据（安装+打包） → 用 pkg-size.dev
• 需要分析特定 import 的打包成本 → 用 bundlejs
• 需要历史趋势监控 → Package Phobia 有最完整的历史数据

最佳实践

使用建议

1. 在依赖选型阶段就用 不要等到 node_modules 膨胀到几个 GB 才想起检查。在 RFC 或技术评审阶段，就用 Package Phobia 对比候选依赖的体积。

2. 同时看发布体积和安装体积 一个包发布体积很小但安装体积很大，说明它依赖了很多重量级的传递依赖。反过来则说明包本身可能包含了很多不必要的文件。

3. 关注体积变化趋势，而非单点数据 利用历史图表功能，查看包在过去几个版本中的体积变化。持续膨胀的包可能存在维护质量问题。

4. 为不同类别的依赖设定不同的体积阈值

   • 核心运行时依赖：严格控制（< 1MB 安装体积为佳）
   • 工具类依赖：适度放宽（< 50MB 可接受）
   • devDependencies：宽松管理（不影响生产部署）

5. 结合 Bundlephobia 一起使用 Package Phobia 和 Bundlephobia 测量的维度不同，对于同时服务前端和后端的 Monorepo 项目，两个工具都应该使用。

6. 在 CI 中设置体积预警 通过 API 集成，在 PR 中自动检查新增依赖的体积，超过阈值时给出警告（不一定是阻断）。

常见陷阱

• ⚠️ 不要把安装体积等同于 bundle 体积 一个 50MB 安装体积的包，经过 tree-shaking 后可能只有几 KB 进入最终 bundle。反之亦然。

• ⚠️ API 缓存可能返回过时数据 如果包刚发布了新版本，Package Phobia 可能还在用旧缓存。指定版本的查询缓存 7 天，最新版本缓存 30 秒。

• ⚠️ 注意原生依赖的平台差异 Package Phobia 的测量环境是 Linux 服务器。如果包包含原生二进制（如 esbuild、sharp），macOS/Windows 上的实际安装体积可能不同。

• ⚠️ 不要只看体积做决策 体积只是依赖评估的一个维度。安全性、维护活跃度、API 设计、TypeScript 支持、社区生态同样重要。

• ⚠️ API 调用频率需克制 Package Phobia 是免费服务，没有公开的 rate limit 文档。批量查询时应添加延时，避免对服务造成压力。

技术局限与边界

已知限制

1. 不支持私有 npm Registry Package Phobia 只能查询 npm 公开 Registry 上的包。对于企业内部私有包、GitHub Packages、Artifactory 等私有 Registry 中的包无法使用。

2. 不支持 monorepo workspace 依赖 无法分析通过 workspace 协议（workspace:*）引用的本地包。

3. 测量环境固定为 Linux 安装体积的测量在 Linux 服务器上完成。包含平台特定原生依赖的包（如 fsevents）在其他平台上的实际体积可能不同。

4. 不支持 Yarn PnP 模式 Package Phobia 使用 npm install 模拟安装，不考虑 Yarn PnP（Plug'n'Play）模式下的不同磁盘占用模型。

5. 历史数据可能不完整 非常老的版本或冷门包可能缺少历史数据。Package Phobia 是在按需查询时测量并记录的，并非预计算所有包的所有版本。

6. 不反映实际运行时行为 安装体积是静态度量，不反映包的实际运行时内存占用、CPU 消耗或启动时间。

7. API 需要注册 API 调用要求注册域名和 User-Agent，对于临时性或探索性使用增加了一定门槛。

不适用场景

• 前端 bundle 优化：应使用 Bundlephobia、size-limit 或 bundlejs
• 私有包分析：需要本地工具如 npm pack --dry-run 或 du -sh node_modules/<pkg>
• 实时 CI 性能门禁：应使用 size-limit，它专为 CI 集成设计，支持 pass/fail 判断
• Bundle 可视化分析：应使用 Webpack Bundle Analyzer 或 Source Map Explorer
• 运行时性能分析：应使用 Lighthouse、WebPageTest 或 Node.js 性能分析工具

学习资源

官方资源

• 官网：https://packagephobia.com — 直接使用 Web 界面查询
• GitHub 仓库：https://github.com/styfle/packagephobia — 源码、Issues、API 文档
• API 文档：https://github.com/styfle/packagephobia/blob/main/API.md — API 端点、参数、响应格式详细说明

教程与文章

• Better know your NPM package bundles — Steve Fuller 的详细文章，对比 PackagePhobia 与其他包体积工具
• How to Worry About npm Package Weight — CSS-Tricks 上的实用指南，涵盖多种包体积分析工具
• Measure package sizes effectively — 综合对比 Bundlephobia、Packagephobia、pkg-size、bundlejs 的最新文章
• How do I view the size of npm packages? — Stack Overflow 高赞问答，涵盖多种方法

社区资源

• Hacker News 讨论 — Package Phobia 在 HN 上的讨论帖
• Reddit: r/javascript — JavaScript 社区中关于包体积优化的讨论
• npm Package Size Checker — 另一个 npm 包大小检查工具，提供类似功能

2026 年现状

项目状态

截至 2026 年 7 月，Package Phobia 的状态可以描述为低活跃维护、服务基本可用：

• 官网（packagephobia.com） 仍然在线运行，部署在 Vercel 上
• GitHub 仓库 未归档、未标记为 deprecated，代码仍然开放
• 最后一次代码提交 记录为 2025 年 3 月 11 日（commit 08fcb14）
• Issues 中存在问题：2025 年 3 月有用户报告 504 GATEWAY_TIMEOUT 错误（issue #1067），表明后端服务可能存在间歇性稳定性问题
• GitHub Stars 约 2.3k，相比同类工具 Bundlephobia（~9k）和 size-limit（~6.9k）差距明显

维护者状况

主要维护者 styfle 在 2025 年的提交频率较低，项目可能已进入维护模式而非积极开发模式。核心功能已经稳定，不需要频繁更新，但新特性开发（如 issue #720 请求显示依赖数量）进展缓慢。

替代方案趋势

2025-2026 年期间，pkg-size.dev 作为一个新兴替代方案正在获得关注。它通过浏览器内的 WebContainers 技术，同时提供安装体积和打包体积的测量，且每次查询执行全新的 npm install，避免了 Package Phobia 的缓存数据陈旧问题。对于新项目或需要更全面分析的场景，pkg-size.dev 可能是一个更好的选择。

是否仍推荐使用？

仍然可用，但建议结合替代方案一起使用：

• ✅ Package Phobia 的历史版本体积追踪功能仍然是独一无二的，对于长期监控包的体积趋势非常有价值
• ✅ 对于快速查看一个公开 npm 包的安装体积，它仍然是最简单的入口
• ⚠️ 如果遇到 504 超时或数据加载失败，可以尝试 pkg-size.dev 作为备用
• ⚠️ 如果需要同时分析安装体积和打包体积，pkg-size.dev 或 bundlejs 可能是更全面的选择
• ⚠️ 如果需要 CI 性能门禁，建议使用 size-limit 而非通过 API 间接集成