pub.dev 下载量30天窗口问题与解决方案

一个令人困惑的数字

当你发布一个 Dart 包到 pub.dev 后，最初几天下载量飙升——200 次！然后数字开始下跌：120、55……你的代码没改，功能没变，用户还在用，但数字却在"崩塌"。

这不是你的包出了问题，而是 pub.dev 展示的是 30 天滚动窗口，不是累计总量。当发布初期的流量高峰滑出这个窗口，数字就会断崖式下跌，让人误以为包正在被抛弃。

下载量到底怎么算的？

很多人误以为 pub.dev 的下载量代表"有多少人在用你的包"。实际上：

• pub 工具会先检查本地 PUB_CACHE，缓存命中则不产生下载计数
• 只有开发者从服务器首次拉取包时才会计数
• 官方文档明确说明："下载量不是用户数的直接度量"

这意味着，即使 1000 个项目在用你的包，只要他们都已经缓存了，那段时间的下载量就是零。而你看到的，还是这"低估值"中最近 30 天的部分。

背后的 API：揭开完整数据

pub.dev 提供了官方 API 文档，其中 Metrics 端点可以获取更细粒度的下载数据。通过调用这些接口，你可以：

1. 获取历史下载趋势——不再局限于 30 天
2. 按版本查看下载分布——了解哪个版本最受欢迎
3. 计算真实累计下载量——还原完整的使用全貌

实战：构建 PubTrace 分析工具

作者基于上述 API 构建了 PubTrace，核心思路是：

• 定期轮询 Metrics API，将每次返回的数据持久化存储
• 通过历史数据累加，计算真实累计下载量
• 生成可视化图表，展示长期增长趋势

对开发者有什么价值？

• 判断包的真实健康度：避免被 30 天窗口误导，做出错误决策
• 评估版本影响力：了解哪个版本被下载最多
• 数据驱动迭代：基于真实使用数据规划开发路线

注意事项

文中提到的部分 API 端点属于非官方接口，可能随时变更。生产环境中使用时需注意稳定性，建议做好降级方案。