npm 下载榜数据接口
2026-11-11 起由 CDN 直出。本端点的规范地址是 https://cdn.dsh.so//data/npm-downloads.json,字节由 Cloudflare R2 直出。https://www.dsh.so/DATA_PATH 仍可访问,但只是一条指向同一对象的 307——新代码请直接用 CDN 地址。(浏览器提示:CDN 按桶的 CORS 规则走,只放行 www.dsh.so / dsh.so 两个来源;curl 与服务端客户端不受影响。)
一次请求返回 DSH 插件的 npm 周下载前 100 名——与首页「本周 npm 下载」榜单同一口径,按 npm 官方 last-week(滚动 7 天)窗口下载量降序排列。week 与 total 是合计:npm 官方 + npmmirror 国内镜像两路各自独立计数的下载量之和,每条另有 official / mirror 明细。
| URL | 说明 | 更新 |
|---|---|---|
https://cdn.dsh.so/data/npm-downloads.json | 前 100 名排名——当前 last-week 窗口内下载量最高的 100 个插件,每个插件一条。week / total 为 npm 官方 + npmmirror 镜像的合计。 | 随部署重建;官方数值取自最近一次每日 npm 快照,镜像数值取自最近一次镜像采集 |
https://cdn.dsh.so/data/npm-downloads.schema.json | 本接口数据格式对应的 JSON Schema。 | 稳定 |
JSON 接口支持跨域读取:Access-Control-Allow-Origin: *,无需 API Key 或注册。
| 字段 | 类型 | 语义 |
|---|---|---|
generatedAt | string (ISO) | 构建时间戳——缓存副本请一并保留 |
snapshotDate | string (YYYY-MM-DD) | null | week 数值来自哪一份 npm 快照;无快照时为 null(此时 items 为空) |
window | object | days: 7(npm 官方 last-week 滚动窗口)、start / end(YYYY-MM-DD)——end 即 snapshotDate。该窗口只描述 week 的官方一路;同一字段的镜像一路来自比官方新约 5 天的窗口(见 sources.mirror) |
sources | object | official / mirror,各含 provider、api、semantics——合计数字背后的两路计数来源 |
scope | object | 收录口径:listableOnly(仅站内列表口径)、ecosystemAppsExcluded(排除生态应用)、newlyIndexedExcludedDays: 7(窗口内新入库不上榜) |
count | number | 榜单条目数(≤ limit) |
limit | number | 100——本接口只提供前 100 名 |
items[] | array | 榜单条目,按 week 降序(字段见下) |
items[].rank | number | 名次(1–100) |
items[].id | string | 插件 id(与 plugins.json 的 id、详情页 slug 一致) |
items[].name | string | 展示名 |
items[].packageName | string | 下载量统计所用的 npm 包名 |
items[].week | number | 合计周下载 = npm 官方 last-week 滚动 7 天窗口 + npmmirror 镜像窗口(比官方新约 5 天)。滚动窗口跨快照日期互相重叠——不要把不同快照的 week 相加。分解见 official.week / mirror.week |
items[].total | number | null | 合计累计下载 = 官方累计 + 镜像累计,两路各自由「初值 + 逐日累加」得到(官方窗口约 18 个月、镜像 2 年,合计是两路各自口径的累计之和);两路都没有初值时为 null——绝不报 0 冒充。分解见 official.total / mirror.total |
items[].official | object | { week, total }——本条目的 npm 官方(registry.npmjs.org)一路;缺数据记 null(绝不记 0) |
items[].mirror | object | { week, total }——本条目的 npmmirror(registry.npmmirror.com)镜像一路。镜像是自己的一路独立计数(不是官方数据代理,两路相加不是对同一批事件的重复计数),窗口比官方新约 5 天;镜像方没有公开计数口径声明,镜像计数口径由镜像方定义。null = 镜像 404 / 尚未采集,绝不记 0 |
items[].stars | number | GitHub 星数 |
items[].url | string | 插件详情页绝对地址 |
license | object | 出处与引用条款——聚合自公开 npm registry,引用需注明来源 |
诚实原则:本接口与首页榜单共用同一派生层(src/data/trending.ts),两处永远一致。窗口内新入库的插件不上榜——新条目的下载量是「刚被发现」而非本周真实热度;生态应用(不能作为插件安装)同样排除。镜像一路同守「诚实缺席」:拿不到就是 null 而不是 0,合计值只有在两路都拿不到时才是 null。
获取前 100 名排名(或在浏览器直接打开 https://cdn.dsh.so/data/npm-downloads.json):
接口固定只输出前 100 名。单插件详情(验证等级、安全、安装方式)用 id 关联 /plugins-index.json 或 /plugin/@作者/插件名.json。
榜单随部署重建,数据来自 dsh.so 流水线每日采集的 npm 官方 Downloads API 快照与 npmmirror 镜像快照。字段只增不删:既有字段不会移除或改名。可免费引用,需注明来源 dsh.so;新增字段见 更新日志。