最小可运行示例：访问量计数器

适用场景很多开源项目或个人站点希望展示一个动态的访问量数字直观体现项目的受关注程度。传统做法是依赖第三方计数服务但通常需要嵌入外部图片或脚本灵活性有限。本文介绍的访问量计数器API 正是为此设计——它支持按站点隔离计数提供 SVG/JSON 两种输出格式可嵌入 GitHub README 的img标签也能在 JavaScript 中获取原始数据后自由渲染。典型场景包括GitHub 仓库首页显示每日/累计浏览次数个人博客文章页记录每篇文章的独立访问量产品落地页的“被访问次数”动态展示接口能力边界请求方法GETQPS 上限10 次/秒超出将返回 429计数模式daily每日零点清零或total累计不清零输出格式SVG默认可直接做图像标签、PNG静态、JSON返回结构化数据主题目前内置 14 套动效/渐变主题前 7 个为像素角色牌含角色帧动画后 7 个为 SVG 渐变主题隔离粒度通过sitename两个参数组合实现多站点、多位置独立计数参数与鉴权鉴权方式请求需要在 HTTP 头部携带X-API-Key字段。API Key 的获取方式以官方文档为准本文仅作技术说明不涉及准备引导。Query 参数一览参数必填类型说明默认值示例site否string站点标识推荐传域名用于区分不同站点全局共享计数器apizero.cnname否string计数器名称同站点下可挂多个demohomemode否string计数模式daily或totaldailytotaltheme否string主题枚举见下方说明gojo_boardseal_blueformat否string输出格式svg/png/jsonsvgjsonlength否number数字显示位数不足补零范围 4~1277no_increment否number设置为1时只查询不递增01主题枚举说明像素牌主题角色帧动画gojo_board/hoops_board/zero_board/jjk_infinity/rule34/moebooru/gelbooruSVG 渐变主题cursed_night/seal_blue/talisman_red/void_gold/gojo_satoru/infinity_void/sukuna_mark可复制的 curl 示例以下命令请求 JSON 格式的累计total计数结果计数器命名为readme站点设为my-blog.example.com。请将$APIZERO_API_KEY替换为实际的 API Key。curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/visits-counter?sitemy-blog.example.comnamereadmemodetotalformatjson若只需默认 SVG 图片便于嵌入 README可直接使用完整 URL无需解析返回体https://v1.apizero.cn/api/visits-counter?sitemy-blog.example.comnamehomemodedailythemegojo_boardlength7将上述 URL 放入img标签即可实时显示 GIF 动效计数器。返回值解读当formatjson时响应体是 JSON 对象包含以下关键字段字段路径类型说明codestring状态码200表示成功descstring状态描述通常为successdata.valuenumber当前计数值原始数字不补零data.display_valuestring格式化后的计数值按length补零data.incrementedboolean本次请求是否使计数器 1 no_increment1时为falsedata.modestring请求时的mode值回显data.record.dailynumber当日累计次数仅modedaily时有效data.record.totalnumber全量累计次数data.record.daystring当前统计的日期格式YYYY-MM-DDdata.record.updated_atstring最后更新时刻ISO8601data.themestring当前主题标识data.theme_namestring主题中文名称如像素牌-苍空data.stepnumber步长固定为1一个真实的响应示例{ code: 200, data: { display_value: 0000042, format: json, incremented: true, length: 7, mode: daily, name: home, record: { daily: 42, day: 2026-05-09, total: 1024, updated_at: 2026-05-09T21:48:5208:00 }, step: 1, theme: gojo_board, theme_name: 像素牌-苍空, value: 42 }, desc: success, tips: 极数本源 · https://apizero.cn }常见错误与调试问题 1请求返回 401 Unauthorized原因未传X-API-Key头部或 API Key 无效。检查请求头是否包含该字段以及 Key 是否正确。问题 2返回 429 Too Many Requests原因短时间请求超过 10 QPS 上限。建议加入本地节流或缓存逻辑。问题 3no_increment1时计数未变化这不是错误而是只读模式的设计行为。如需测试递增需去掉该参数或设为0。问题 4SVG 图片无法显示检查 URL 中site和name是否包含空格或特殊字符建议做 URL 编码。另外确保img标签正确指向该 HTTP 地址直接浏览器打开可确认 SVG 是否正常。问题 5formatpng生成图片模糊PNG 格式支持scale参数1~4可在文档中查看具体用法。本文未给出scale参数细节以官方文档为准。工程化注意事项嵌入 GitHub README在仓库的README.md中直接使用 Markdown 图片语法注意每次加载 README 页面都会触发一次 GET 请求计数器会递增。如果希望计数只反映真实访问而非页面刷新可以考虑使用no_increment1并通过其他方式递增例如仅由后端触发。前端 JavaScript 集成若需在页面中动态展示计数值而非直接显示 SVG可请求 JSON 格式const url https://v1.apizero.cn/api/visits-counter?sitemy-site.comnamehomemodedailyformatjson; const headers { X-API-Key: your-api-key-here }; fetch(url, { headers }) .then(res res.json()) .then(data { if (data.code 200) { document.getElementById(visits).textContent data.data.display_value; } }) .catch(err console.error(err));缓存与性能每个请求都会触发后端计数写入建议非活跃页面避免高频轮询。若只需要定时更新可在服务端设置缓存例如 5 分钟然后通过 cron 任务定期调用 API 更新缓存值。对于高流量站点日 PV 超 10 万可直接在业务机器内存中计数定期批量提交以减少对 API 的调用压力。多站点隔离的实践site参数建议使用完整域名如docs.example.com而name用于区分同站点下的不同计数器。例如首页计数器siteexample.comnamehome文档页计数器sitedocs.example.comnameindex产品页计数器siteexample.comnameproduct-a这样每个计数器独立维护daily和total值。参考文档接口文档页原始 Markdown 文档