静态博客怎么显示每篇文章的浏览量：从 D1 读数接口到前端排序的完整链路

先看这套东西现在的样子#

文章页的标题下面那行 meta：发布时间、浏览量图标加一个「0 次」。这个数字不是构建时写死的——看组件模板就知道（下面贴的是 PostMeta.astro 的源码，不是渲染后的 HTML），它渲染出来就是个空壳，slug 是文章 id：

<div class="flex items-center" id={`page-views-wrapper-${slug}`} style="display: none;">
    <div class="meta-icon">
        <Icon name="material-symbols:visibility-outline-rounded" class="text-xl"></Icon>
    </div>
    <span class="text-50 text-sm font-medium" id={`page-views-${slug}`}></span>
</div>

首页同样，每张卡片下挂着一个「0 次」，右上角多了排序控件。顺便注意侧栏：首页有「访问量 0」，文章页没有——这不是设计，是实现细节，放在「踩坑」里说（后来修掉了，见文末补记）。

真正值得在意的不是那一刻的 0，而是为什么会是 0：读数接口一路通着（下面有实测），却没有任何页面在往计数表里写。本文写作时（2026-10-05 晚）这套系统处于「只读不写」的状态，这个坑当天深夜补上了，改动集中在文末补记里；正文保留的代码与截图是当时的样子，我会在对应位置标出哪些已经变了。

为什么不用第三方统计的 API#

最省事的做法是前端直接去第三方统计的分享页拉数字。我没选，理由都跟「展示」这个场景的特殊性有关：

1. 分享页是给人看的页面，不是给浏览器 fetch 的接口。 它属于统计后台的一部分，渲染方式随时可能变，而文章卡片要长期依赖它的响应结构——绑得越紧越难拆。
2. 跨域和配额都不在我手里。 读数请求要从 blog.juluo.work 打到别人的域上，失败时我连「为什么失败」都看不到——是 CORS、是限流，还是接口改了。
3. 展示只需要一个整数。 来源、设备、停留时长这些留在统计后台看就好，为了一个数字去拉一个通用分析接口，是拿大炮打蚊子。

自建的代价也很实在：多一个 Worker、多一张表、多一处要维护的东西。但它的失效模式是干净的：接口挂了，博客照常打开，只是数字不显示（我实测过，见后面的失败兜底）。

提示

这段写于当晚 22 点，两个多小时后我自己把它推翻了：展示的数字改成优先读 Umami 的分享接口，自建那份退成兜底。三条理由本身没被推翻——变的是多了兜底，所以可以冒「接口随时会变」这个险。具体见文末「再补一刀」。

数据表：只有两列，是刻意的#

D1 里的建表语句就一行（来自 cf-umami 仓库的 src/index.ts，我用 curl 核对过部署版本返回的错误字符串，行为与它一致）：

CREATE TABLE IF NOT EXISTS pageviews (pathname TEXT PRIMARY KEY, views INTEGER NOT NULL);

写入也只有一句 UPSERT：

INSERT INTO pageviews(pathname, views) VALUES(?, 1) ON CONFLICT(pathname) DO UPDATE SET views = views + 1;

pathname 直接当主键，views 就是个整数计数。没有 IP、没有 UA、没有 session、没有时间戳。 这不是偷懒，是取舍：

• 好处：表小，查询就是一次主键查，不存任何可识别信息，连「匿名化」这一步都省了。
• 代价：UV、来源、停留时长、趋势曲线一概没有，这些交给 Umami。

另一个直接后果是路径必须规范化。同一个页面只要能通过两个 URL 打开，计数就会裂成两条。我的文章页只有 /posts/<slug>/ 一种形态，工具页统一用组件里写死的 pathname（比如 /tools/cover/ 这个页面，实际读写的路径是 /cover/——实测抓到的请求就是 GET /share?pathname=%2Fcover%2F），所以这件事暂时没炸。

接口契约：两个读接口，一个写接口#

三个端点用 curl 跑一遍，下面是线上真实响应：

• GET /share?pathname=/posts/xxx/ → {"pathname":"/posts/xxx/","views":0}，单个页面读数；参数缺失返回 {"ok":false,"error":"invalid_pathname"}。
• POST /batch，请求体是裸 JSON 数组 ["/","/posts/xxx/"]，返回同序数组 [0,0]；传对象进去会被拒：{"ok":false,"error":"expected_array"}（HTTP 400）。
• POST /send，单个写入，请求体是 {"pathname":"/"}，只接受来自本站 Origin/Referer 的请求，其他来源直接 HTTP 204 静默丢弃。

警告

Windows PowerShell 会把命令行里内联 JSON 的双引号吃掉。--data-raw '["/"]' 实际只发出了 3 个字节，接口回 {"ok":false,"error":"invalid_json"}；把请求体写进文件、用 --data-binary "@file" 才能正常测通。我第一次测 /batch 就被它坑了，差点以为接口不认数组。

为什么读数用 POST 而不是 GET。 语义洁癖会说「读操作该用 GET」，但这套接口要一次读 N 个路径：GET 只能靠 ?pathname=a&pathname=b 或者逗号分隔，URL 长度、编码、去重规则全得自己定；POST + JSON 数组能把「顺序」表达得最清楚——顺序就是契约，讲排序时你会看到它有多关键。副作用是 POST 天然不可缓存，每次浏览都真的打一次查询，好处是数字永远新鲜。

前端：一次批量读，先藏后显#

上图是单页读数组件 src/components/ViewsCounter.astro，用在工具页、课程表这类没有文章卡的页面上：/share 读一个路径、写进 span、把 wrapper 从 display: none 改成 flex。

关键在「藏」这个动作上。 组件渲染出来的 wrapper 带 style="display: none;"，服务端渲染阶段它就是个不占位的空壳，数字是客户端拿到之后才亮的。如果先渲染一个「0 次」占位、等接口回来再换成「1234 次」，用户会看到数字跳变，数字宽度变化还会把整行 meta 往前推一下——比晚半秒出现难看得多。代价是这一行从无到有时，下面的内容会有一次小位移，但至少不会有错误的数字被看到。

实测：工具页整页只发出 1 个请求 GET /share?pathname=%2Fcover%2F，然后 span 里出现「0 次」。

文章页和列表页走的是另一条路——批量读。一页最多 8 张卡片（src/constants/constants.ts 里的 PAGE_SIZE = 8），每张各发一个 /share 就是 8 个请求，既慢又费额度。所以这里的机制是「先登记、再一次性取数」——不是并发发起 N 个请求，而是把 N 个路径压进同一个请求：

登记这一步做在卡片组件里（src/components/PostMeta.astro 的内联脚本，页面上有几张卡片就有几份）：

window.__VIEWS_QUEUE__ = window.__VIEWS_QUEUE__ || [];
if (!window.__VIEWS_QUEUE__.includes(slug)) {
    window.__VIEWS_QUEUE__.push(slug);
}

真正发请求的是独立的读取端 src/scripts/view-counter-runtime.ts（挂在 Layout.astro 上，所以每个页面都有，而且每页只跑一次）：

const slugs = collectSlugs(); // 列表页读 __PAGE_POSTS_DATA__，其它页面读 __VIEWS_QUEUE__
const pathnames = ["/", ...slugs.map((slug) => `/posts/${slug}/`)];
const res = await fetch(`${endpoint}/batch`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(pathnames),
});

请求体永远以 / 打头，所以不管在哪一页，侧栏那个全站访问量都能顺带取回来。抓包实测：线上首页是 9 条路径（/ 加 8 篇文章），发往 t.juluo.work 的请求只有 1 条——POST /batch。代价也在这句话里：只要其中任意一个 pathname 不合法，整个 /batch 就返回 400（实测：数组里混进一个不以 / 开头的路径，整批请求直接失败），那一页的数字会全部不显示——「全对才给」的严格口径，换来的是前端永远不用处理”部分成功”。

提示

「9 条路径」只是那一刻的快照，别当成固定值：请求体长度永远等于线上文章数 + 1（多出来的 / 是侧栏那个全站访问量）。文章数一变，这个数字就跟着变。

列表页按热度排序：索引对齐才是真难点#

列表页的排序完全在客户端做（src/scripts/post-list-sort.ts）。文章数据在构建时就被塞进页面：

window.__PAGE_POSTS_DATA__ = pagePostsData;

这段在 src/pages/[...page].astro 里，pagePostsData 是 id / title / published / pinned 四个字段的精简对象。排序脚本拿到它之后一次读完，再靠下标把数字分回去：

• views[0] 是全站访问量，写进侧栏的 #site-views——这一步由读取端直接做，排序脚本不掺和；
• views[index + 1] 才是第 index 篇文章的量，填进卡片上那个 span，同时通过 post-views-loaded 事件广播出去，排序脚本收到后存进 viewsData 这个 Map。

排序在 getSortedIndices() 里：日期模式按 published 排（置顶优先），访问量模式按 Map 里的数字排；render() 不做 diff，直接把 article 元素按新顺序 appendChild 回容器——元素复用，只是顺序变了。

这套实现的脆弱点恰恰是它的简洁：请求数组、响应数组、__PAGE_POSTS_DATA__ 三个顺序必须完全一致。任何一边多一个、少一个、乱一个，数字就会串到别的文章上，而且不会报错，你只会觉得数字”有点怪”。换成对象数组（[{pathname, views}]）当然更稳，但接口契约已经定了，眼下改它的收益不值这个工。

这里有个尴尬的现实：写作当时线上所有计数都是 0，点「按访问量排序」看不出任何变化——每个比较都返回 0，而 V8 的 sort 是稳定的，顺序原样保留（只有按钮的 active 样式变了）。为了验证逻辑本身，我把 /batch 的响应体在浏览器里换成了模拟数据（页面代码一行没改，也没有往 D1 写任何东西）：

• 6 张卡片（就是当时首页那几张）按模拟计数从大到小重排：500 / 300 / 200 / 100 / 50 / 10，侧栏全站数变成 1234；
• 再点一次顺序按钮（「倒序」→「正序」），顺序整个反过来：10 / 50 / 100 / 200 / 300 / 500。

也就是说批量取数、下标映射、排序三件事都是通的。唯一没验证的是真实非零数据——那需要有人往表里写，而这正是当时缺的那一环；接入上报之后我用真实数据又跑了一遍，见文末补记。

防刷与缓存口径#

防刷。 先说清楚：这套守卫不是防刷，是防误写。

• 读接口（/share、/batch）完全公开，任何人 curl 都能拿到数字。它只做了 CORS 白名单：带外域 Origin 请求时响应里根本没有 Access-Control-Allow-Origin（实测），浏览器会拦掉读取——但这拦不住 curl。
• 写接口 /send 会检查 Origin/Referer 的 host 是否等于配置的目标站点，不等就 204 静默丢弃。我拿一个没人访问的路径试过：带外域 Origin 时返回 204，随后用 /share 查该路径仍然是 views: 0，说明它确实没写进去。它拦的是「别的站把上报误打过来」，同样拦不住伪造 Origin 的脚本。
• 真要防刷得靠边缘的 WAF / 限速规则。而我这里是读接口被刷，代价只是 D1 的行读，真正要担心的是有人拿它刷用量，不是数据被篡改。

缓存。 实测两个读接口的响应头里都没有 Cache-Control（我用 Select-String 过滤响应头，一条都过滤不出来），而 POST 本身也不可缓存。所以每次浏览都会实打实打一次查询：数字永远新鲜，也意味着没有「缓存穿透」这类问题需要额外机制去补。

顺带一个反面样本：上报脚本 /tracker.js 是有缓存的（Cache-Control: public, max-age=3600），而它当时在页面上一次都没被引用——我 curl 了首页、文章页、归档、友链、赞助、隐私、工具几个页面，tracker.js 出现次数都是 0。所以那会儿的状态是：读接口跑得很勤，写接口准备好了但没人调用。写接口接上去之后，缓存反而是好事：脚本每页只下载一次的量级，被浏览器缓存住就不会反复消耗请求额度。

踩坑与注意事项#

1. 文章页看不到侧栏的「全站访问量」，首页能看到。 因为全站数字是排序脚本顺带取回来的（views[0]），而排序脚本只在列表页加载；文章页只有 PostMeta，它只取自己那一条。实测：首页 #site-views-wrapper 的 display 是 grid，文章页是 none。同一个侧栏组件，两个页面表现不一致。（已修：读取端统一后，任何页面都会把 / 带上，见补记。）
2. 0 数据下的排序”看起来失效”。 点按钮时 active 样式会变（说明事件绑上了），但顺序纹丝不动，因为比较器对所有组合都返回 0。测排序逻辑不能只看线上表现，得先把数据换成非零的。
3. 接口挂了要能安静地不显示。 我把 /batch 分别换成 500 和「200 + 空响应体」测了一遍：列表页、文章页都不显示任何数字，页面其他部分完全正常，控制台的 pageerror 里也没有浏览量相关的报错。空响应体当时靠一句 throw new Error('Empty response') 拦下，统一读取端之后换成了 Array.isArray(views) 检查。这个「宁可不显示，也不显示错的」兜底是免费的——因为渲染前就检查了 res.ok。
4. /batch 是 N 次串行查询。 Worker 源码里就是一个 for 循环，每个 pathname 单独 SELECT 一次，没有用 IN 一次查回来；而且每次请求进来还会先跑一遍 CREATE TABLE IF NOT EXISTS。写作时首页那 7 个路径就是 7 次串行查询。现在文章少看不出差别，等文章上百篇，这就是最该先改的一处（一次 IN 查询 + 把建表检查挪出热路径）。
5. 与本文无关但顺手发现的一个报错：线上页面控制台里一直有 cookieConsentConfig is not defined（Cookie 同意横幅那个脚本）。它不影响浏览量，但它说明客户端脚本的错误最容易长期潜伏——因为很少有人天天开着控制台看自己的博客。

收尾：给想抄这套的人一份清单#

判断先放在前面：静态博客要显示浏览量，下限方案是「一个只读接口 + 一次批量读 + 服务端渲染留空位」，而不是去引第三方统计的公开接口。 展示和统计是两件事，混在一起做，哪天统计服务改个接口，你就得跟着改文章卡片。

但更值得记住的是这条：显示链路和写入链路是两件独立的事。 我这套当时读得又快又稳，数字却全是 0——因为没有页面上报。它不是读数接口的毛病，是「先把读的那半截跑通、写的那半截还没接」的状态；接上 tracker.js 会让每次 PV 多 1 个请求额度（这笔账在上一篇里算过），所以我先留着了——留到当天深夜，看着满屏 0 实在难受，还是接了，过程见下面的补记。所以：如果你在自己站点上看到每篇都是 0 次，先别怀疑接口，去抓一次包看有没有 /send。

要抄的话，按这个顺序做：

1. 定一张两列的表（pathname 主键 + views 计数），别急着存 UA/IP——那些需求九成不会实现，真要实现也该换一套表。
2. 接口分三个：单读（/share）、批量读（/batch，请求体就用裸数组，顺序即契约）、写（/send，带 Origin 守卫并按需静默丢弃）。
3. 前端先渲染空壳（display: none），拿到数据再亮——不要先渲染 0 再跳数。
4. 一页上多个组件要读数时，用「队列登记 + 一个统一读取端」，别让每个组件各自发请求，也别让「只有某个页面才取得到某个数字」。
5. 依赖下标的排序逻辑，一定要用非零的模拟数据测一遍，别拿线上的全 0 当”测过了”。
6. 失败路径要测全：500、空响应体、CORS 被拦，三种情况下页面都应该安静地不显示数字。
7. 读和写都要验：读接口返回 0 不等于”接口坏了”，先 curl 一次写接口，确认是「写不进去」还是「没人写」。

补记（2026-10-05 深夜）：把写入端接上，顺手统一了读取端#

上面这篇发出不到两小时，我就把「只读不写」这半截补上了——满屏的 0 摆在首页上，比多花一个请求额度难受得多。动手之后才发现问题不止一个。

# 读：接口活着，只是表里没数据
curl -s "https://t.juluo.work/share?pathname=/posts/hello-world/"
# {"pathname":"/posts/hello-world/","views":0}

# 写：拿本站 Origin 手动打一次，立刻就进去了
curl -s -X POST "https://t.juluo.work/send" \
  -H "content-type: application/json" -H "Origin: https://blog.juluo.work" \
  -d '{"pathname":"/__selftest"}'
# {"ok":true}
curl -s "https://t.juluo.work/share?pathname=/__selftest"
# {"pathname":"/__selftest","views":1}

{viewCounterConfig.enable && viewCounterConfig.endpoint.trim() !== "" && (
	<script is:inline defer src={`${viewCounterConfig.endpoint.replace(/\/+$/, "")}/tracker.js`}></script>
)}

再补一刀（同一夜更晚）：数据源改成「优先 Umami，自建退成兜底」#

上面那套修完，数字确实是真的了，但全是从零开始的真：D1 里第一行数据诞生于今晚，而 Umami 从 2025 年 8 月就在记这个站。读者点开一篇文章看到「1 次」，不会觉得「这站刚上线」，只会觉得坏了。

所以数据源换了个顺序：先读 Umami，读不到再用自建的 D1 补。

GET  {gateway}/api/share/{shareId}                      -> {"websiteId":"842d…","token":"<JWT>"}
GET  {gateway}/api/websites/{websiteId}/stats?startAt=0&endAt=<毫秒>          -> 全站全时段 PV
GET  {gateway}/api/websites/{websiteId}/stats?…&path=eq.%2Fposts%2Fxxx%2F     -> 该路径全时段 PV
     header: x-umami-share-token: <token>      # 10 分钟有效
     header: x-umami-share-context: <shareId>  # 少这个一律 401