PackagePhobia API 使用指南：获取npm包体积数据的专业方案

PackagePhobia API 使用指南：获取npm包体积数据的专业方案

packagephobia ⚖️ Find the cost of adding a new dependency to your project 项目地址: https://gitcode.com/gh_mirrors/pa/packagephobia

什么是PackagePhobia API

PackagePhobia API 是一个专门用于查询npm软件包体积数据的接口服务。它能够返回软件包的发布体积(publishSize)和安装体积(installSize)等关键指标，帮助开发者评估依赖包对项目构建大小的影响。

API使用前提

在使用PackagePhobia API前，开发者必须注意以下重要事项：

1. 必须设置User-Agent请求头：这是API的强制要求，未设置User-Agent的请求会被直接拦截
2. 建议登记使用网站：虽然非强制，但建议将使用此API的网站或应用信息提供给维护方

API版本与端点

PackagePhobia API目前提供两个版本：

1. v1版本：基础API，返回简化的体积数据

   • 端点：/api.json
   • 返回字段：仅包含publishSize和installSize

2. v2版本：增强API，返回更丰富的元数据

   • 端点：/v2/api.json
   • 返回字段：包含包名、版本、文件数、格式化大小和颜色标识等

请求参数说明

API支持两种查询方式：

1. 精确版本查询：指定包名和确切版本号

   • 示例：/api.json?p=satori@0.4.3
   • 缓存策略：最长缓存一周

2. 最新版本查询：仅指定包名，自动使用最新版本

   • 示例：/api.json?p=satori
   • 缓存策略：仅缓存30秒

响应数据结构解析

v1版本响应示例

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

• publishSize：发布体积，单位字节
• installSize：安装体积，单位字节

v2版本响应示例

{
  "name": "satori",
  "version": "0.4.3",
  "publish": {
    "bytes": 3686131,
    "files": 19,
    "pretty": "3.52 MB",
    "color": "#007EC6"
  },
  "install": {
    "bytes": 8724612,
    "files": 297,
    "pretty": "8.32 MB",
    "color": "#DFB317"
  }
}

v2版本提供了更丰富的信息：

• 基础信息：包名(name)和版本号(version)
• 发布信息(publish)：
  • bytes：原始字节数
  • files：包含文件数量
  • pretty：格式化后的大小字符串
  • color：建议的显示颜色
• 安装信息(install)：结构与publish相同

最佳实践建议

1. 版本选择：生产环境建议使用精确版本查询，避免自动获取最新版本可能带来的不确定性

2. 缓存利用：根据API的缓存策略设计客户端缓存机制，v1版本数据可缓存更长时间

3. 错误处理：实现适当的错误处理逻辑，特别是对于未找到的包或无效版本号等情况

4. 性能考虑：对于需要频繁查询的场景，考虑在服务端实现中间缓存层

5. 数据展示：v2版本提供的颜色标识可用于可视化展示，帮助用户直观理解包体积大小

技术实现原理

PackagePhobia API底层通过分析npm包的元数据和实际内容来计算体积指标：

• 发布体积：计算打包后的.tgz文件大小
• 安装体积：模拟实际安装过程，计算所有依赖项的总大小

API使用Cache-Control头部实现缓存控制，确保在提供最新数据的同时优化服务器性能。

适用场景

PackagePhobia API特别适用于以下场景：

1. 包管理平台：展示包体积信息，帮助用户选择轻量级替代方案
2. CI/CD流程：在构建过程中监控依赖体积变化
3. 开发工具：集成到IDE或CLI工具中，实时反馈依赖影响
4. 性能分析：评估第三方依赖对应用性能的潜在影响

通过合理利用PackagePhobia API提供的数据，开发团队可以更好地优化应用体积，提升用户体验。

packagephobia ⚖️ Find the cost of adding a new dependency to your project 项目地址: https://gitcode.com/gh_mirrors/pa/packagephobia