适用场景当你在 GitHub 仓库 README、个人博客或 SaaS 产品页面上需要展示“本页浏览次数”时传统做法是自建数据库后端接口维护复杂度高且部署复杂。访问量计数器 API 提供了一种即插即用的方案通过一个 GET 请求即可输出 SVG 图片或 JSON 数据支持按站点、按页面隔离计数并且提供多套动效主题像素角色举牌、渐变文字等可直接用img标签嵌入 Markdown。常见使用场景GitHub 项目 README 中展示项目总访问量。静态博客每条文章页脚显示当日/累计阅读量。管理后台统计落地页曝光配合 JSON 格式自行渲染图表。接口能力边界该接口按站点site和名称name两个维度隔离计数。同一站点下可挂多个计数器如首页、产品页、文章页不同站点之间的计数互不干扰。计数模式支持每日清零daily和累计不清零total满足短期活动统计与长期总览需求。输出格式丰富SVG返回可直接嵌入网页的矢量图包含动画效果像素角色帧动画或渐变 SVG。PNG静态位图适合邮件或 PDF 等不支持 SVG 的场景。JSON原始结构化数据便于前端自行渲染或存入数据库。接口 QPS 限制为 10/s日常集成足够。注意每次计数模式下的访问都会增加计数除非指定no_increment1做只读查询。参数与鉴权鉴权方式使用 HTTP HeaderX-API-Key传递密钥。你需要在 apizero.cn 准备后获取 API Key并在请求中携带。Query 参数一览参数必填类型说明示例site否string站点标识建议传你的域名。不传时全局共享计数器。apizero.cnname否string计数器名称同一站点下可不同。默认demo。homemode否string计数模式daily/total。默认daily。totaltheme否string主题详见文档。默认gojo_board像素牌。sukuna_markformat否string输出格式svg/png/json。默认svg。jsonlength否number显示位数4~12默认 7前导补零。7no_increment否number只读模式1不递增计数0递增。默认0。1所有参数均以文档 apizero.cn/aidocs/visits-counter 为准。curl 接入示例以下命令可获取apizero.cn站点、home计数器的 JSON 格式数据并递增计数默认daily模式curl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY \ https://v1.apizero.cn/api/visits-counter?siteapizero.cnnamehomeformatjson若要获取 SVG 图像并保存为文件curl -sS -o counter.svg \ -H X-API-Key: YOUR_API_KEY \ https://v1.apizero.cn/api/visits-counter?sitemyblog.comnamearticle-001modetotalthemeseal_blue只查询不递增预览curl -sS \ -H X-API-Key: YOUR_API_KEY \ https://v1.apizero.cn/api/visits-counter?sitepreviewnametestno_increment1formatjson请将YOUR_API_KEY替换为你实际的密钥。返回值解读当请求formatjson时响应体是一个数组首个元素包含完整数据。以下为示例 JSON 的字段说明{ 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 }主要字段含义字段类型说明codestring业务状态码200表示成功。data.valuenumber当前计数根据 mode 为日值或累计值。data.display_valuestring补齐前导零后的显示字符串可直接拼接 SVG 显示。data.incrementedboolean本次请求是否执行了递增操作。若no_increment1则为 false。data.modestring请求时的计数模式。data.recordobject明细记录包含 daily当日值、total累计值、day当前日期、updated_at最后更新时间。data.stepnumber每次递增步长固定 1。data.theme_namestring当前主题的中文名称。当输出格式为svg或png时响应体直接为二进制内容需设置相应的 Content-Type例如image/svgxml或image/png可在浏览器或img标签中直接引用 URL但需注意 API Key 不宜暴露在前端。常见错误排查错误现象可能原因解决方案返回 HTTP 401API Key 未传或无效在请求头中添加X-API-Key并确认密钥正确。返回 HTTP 400必填参数缺失或参数值不合法如长度超出范围、theme 名称拼写错误对照文档检查参数。返回code非200业务逻辑错误例如no_increment传了非 0/1 的值检查参数类型和取值范围。SVG 显示异常乱码未正确设置 Content-Type 或未按图片格式处理若用img标签可直接引用 API URL带上认证参数但注意安全性。计数未预期递增可能误将no_increment设为了1或每次请求使用了不同参数导致创建了多个计数器排查参数一致性确认在相同 site 和 name 下调用。QPS 超限短时间内请求频率超过 10/s加入本地缓存或节流不要在前端直接并发请求。工程化注意事项1. 环境变量管理 API Key不要在代码中硬编码 API Key。建议通过环境变量读取export APIZERO_API_KEY你的密钥在 Node.js 中const apiKey process.env.APIZERO_API_KEY;Pythonimport os api_key os.environ.get(APIZERO_API_KEY)2. 服务端封装避免暴露密钥由于 API Key 要求放在请求头中若直接在前端img标签或fetch中携带密钥会泄漏到浏览器的开发者工具或网络日志中。推荐在服务端进行代理封装客户端 - 你的后端持有 API Key - 访问量计数器 API。例如使用 Express 封装一个接口app.get(/api/counter, async (req, res) { const { site, name, mode, theme } req.query; const apiRes await fetch(https://v1.apizero.cn/api/visits-counter? new URLSearchParams({ site: site || default, name: name || default, mode: mode || daily, theme: theme || gojo_board, format: svg }), { headers: { X-API-Key: process.env.APIZERO_API_KEY } }); const svg await apiRes.text(); res.set(Content-Type, image/svgxml); res.send(svg); });这样前端只需引用/api/counter?sitexxx即可密钥存在于后端。3. 缓存策略对于不需要实时更新的场景如 README 展示可以启用缓存减少 API 调用。例如在 Nginx 层配置缓存或在应用层使用 Redis 缓存响应 5~10 分钟注意缓存将不再触发递增但展示效果无影响。4. 计数器命名规范建议为每个页面生成固定且唯一的name例如使用 URL 路径的 MD5 哈希或 slug。避免将用户输入直接作为name防止碰撞或注入API 本身会校验但命名混乱影响管理。5. 处理超时与重试网络不可靠建议在调用时设置超时如 3 秒并添加重试逻辑指数退避最多 3 次。不要在无重试的情况下让用户看到加载失败。参考文档访问量计数器 API 文档https://apizero.cn/aidocs/visits-counter原始 Markdown 文档https://apizero.cn/aidocs/visits-counter/raw.md