npm Registry 数据源

调用 npm 官方 Registry API 获取 npm 包的元数据、版本信息、依赖关系、README 以及用户/组织信息。支持访问私有包（需配置 Token）。

鉴权

npm Registry 的公开 API 无需鉴权即可查询公开包。如果需要访问私有包，请配置 NPM Token：

公开包（默认值）：直接发送请求，不传任何 token。

私有包：在请求头携带：

Authorization: Bearer {{secrets.NPM_TOKEN}}

注意：npm token 不提升公开 API 的请求速率限制，其主要用途是访问私有包和发布包。

通用约定

• Base URL：https://registry.npmjs.org（必须使用 HTTPS，HTTP 会被系统拒绝）
• 请求方法：GET
• 响应格式：JSON（CouchDB 风格文档）
• 字符编码：UTF-8
• 分页：搜索接口支持分页，其他接口不分页
• 速率限制：无明确限制，但建议不要高频并发请求；如收到 429 请等待后重试
• 包名转义：scope 包需要 URL 编码，@scope/name → @scope%2Fname

⚠️ 速率限制策略（必须遵守）

1. 串行请求：同一时间只发 1 个 curl 请求，等返回后再发下一个。严禁并行发送多个请求
2. 请求间隔：每两个请求之间至少间隔 1 秒
3. 批量查询：需要查多个包时，一次最多查 5 条，如需更多则分批
4. 429 重试：收到 429 错误后等待 60 秒再重试，严禁立即重试
5. 数据复用：已获取的列表/枚举类结果应缓存使用，不要重复请求

常用接口

1. 获取包元数据

获取指定 npm 包的所有元数据，包括所有版本、作者、关键词等。

GET https://registry.npmjs.org/{package}

参数：

关键返回字段：

2. 获取包特定版本详情

获取指定版本的详细信息，包括依赖、dist 文件等。

GET https://registry.npmjs.org/{package}/{version}

参数：

关键返回字段：

3. 搜索包

搜索 npm registry 中的包，支持关键词、作者、scope 等过滤。

GET https://registry.npmjs.org/-/v1/search?text={query}&size={size}&from={from}

参数：

关键返回字段：

4. 获取用户包列表

获取指定 npm 用户的所有公开包。

GET https://registry.npmjs.org/-/user/{username}/packages

参数：

关键返回字段：

5. 获取组织用户列表

获取组织（org）下的用户列表（需组织公开或权限）。

GET https://registry.npmjs.org/-/org/{org}/user

参数：

关键返回字段：

调用示例

场景 1：查询包的最新版本和依赖

用户问题："react 包最新版本是多少，依赖什么？"

1. 调用接口获取版本详情：

curl(url = "https://registry.npmjs.org/react/latest", X = "GET")

2. 从返回中提取：
   • 版本：jq(".version") → "18.2.0"
   • 依赖：jq(".dependencies") → { "loose-envify": "^1.1.0" }

场景 2：搜索某个作者的所有包

用户问题："sindresorhus 有哪些 npm 包？"

1. 搜索该作者的包：

curl(url = "https://registry.npmjs.org/-/v1/search?text=author:sindresorhus&size=20", X = "GET")

2. 从 objects[].package.name 中提取包名列表。

场景 3：获取用户包列表

用户问题："查查 sindresorhus 有多少 npm 包"

1. 调用用户包列表接口：

curl(url = "https://registry.npmjs.org/-/user/sindresorhus/packages", X = "GET")

2. 统计返回数组长度，或使用搜索接口配合分页获取完整列表。

场景 4：比较两个包的版本

用户问题："vue 和 react 哪个版本更新？"

1. 分两次调用获取最新版本：

curl(url = "https://registry.npmjs.org/vue/latest", X = "GET")# 提取 .versioncurl(url = "https://registry.npmjs.org/react/latest", X = "GET")# 提取 .version

2. 比较返回的版本号。

场景 5：访问私有包（需 Token）

用户问题："查询 @mycompany/private-package 的信息"

1. 使用 Authorization header 调用：

curl(url = "https://registry.npmjs.org/@mycompany%2Fprivate-package", X = "GET", H = ["Authorization: Bearer {{secrets.NPM_TOKEN}}"])

2. 提取所需字段。

错误处理

数据边界说明

1. 弃用包：deprecated 字段不为 null 时表示该版本已弃用，应提示用户谨慎使用
2. 私有包：无权限访问时会返回 404 或 401，不代表包不存在
3. Scope 包编码：@types/react 需编码为 @types%2Freact
4. 下载量数据：Registry 本身不提供下载量，需使用 npm API（https://api.npmjs.org/downloads/point/{period}/{package}）或 npms.io 的搜索接口获取近似值
5. README 缓存：readme 字段可能为空或已缓存的旧版本，最新 README 建议从 GitHub 仓库获取