JavaScript 渲染
把文档从纯客户端单页应用改为构建时静态预渲染,并在每次发版时增量重新生成。现在每个页面在第一个 HTML 响应里就带着完整的正文、标题和代码示例;JavaScript 只负责增加交互。
在 CI 中运行原始 HTML 一致性检查:渲染后文本与原始文本相差超过 2%,构建即失败。
Ferrovane · 可观测性与日志平台 · 柏林
输入信号 · 挑战
Ferrovane 的文档是一个客户端渲染的单页应用,Google 只收录了其中不到五分之一,开发者搜索时找到的反而是竞争对手的指南。
从纸面上看,文档是 Ferrovane 最好的获客渠道:6,040 篇指南、采集器配置示例和 API 参考,全部出自打造这款产品的工程师之手。可整个文档站是一个客户端渲染的单页应用。Googlebot 抓到的只是一个空壳,先排进渲染队列,往往等不到内容加载就放弃了。开发者搜索确切的报错信息和配置片段时,看到的是竞争对手的教程,其中不少讲的恰恰是如何接入 Ferrovane。
<html>
<body>
<div id="root"></div>
<script src="/app.9f3c.js">
<!-- 1.9 MB -->
</body>
</html># Configure the OTel collector
exporters:
ferrovane:
endpoint: ingest.eu.ferrovane.example
compression: zstd诊断 · 故障日志
我们读了 30 天的服务器日志,逐个 URL 对比原始 HTML 与渲染后的 HTML,并在关闭 JavaScript 的情况下抓取了整个网站。故障分为四类:渲染、架构、抓取预算和国际化。
文档上线时只是一个空的 <div id="root"> 加一个 1.9 MB 的脚本包。Googlebot 的渲染队列要晚好几天才轮到大多数页面;那些在 hydration 之后才拉取内容的 API 参考页面则直接超时。
> 原始 HTML 字数:6,040 个 URL 中有 5,880 个为 0
导航靠 <span> 元素上的 onClick 处理函数实现,爬虫在各版块之间找不到任何 <a href> 链接。大部分指南都成了孤立页面。
> 原始 HTML 中的内部链接:平均每页 3 个
六个发布版本(v3.0 至 v3.5)分别放在不同路径下,没有任何 canonical。Google 一再把旧的 v3.1 页面选为代表性 URL。
> 重复内容簇:6 个版本共 2,310 个 URL
哈希片段路由(/docs#/collectors/otel)让成千上万个页面在搜索引擎眼里合并成了同一个 URL。
> 可抓取的唯一 URL:6,040 个中仅 412 个
API 浏览器的分面参数和会话令牌制造出几乎无限的 URL 空间,Googlebot 71% 的请求都耗在了这里。
> 花在非规范 URL 上的抓取:71%
改名后的页面出现软 404:返回 200 状态码,却显示一个“未找到”组件。站点地图里列着 1,400 个会被重定向的 URL。
> 每周记录的抓取错误:3,840 个
德语和日语文档在客户端注入,与英文共用同一个 URL,因此根本没有可供标注的语言版本 URL,德语页面也从未被收录。
> 已收录的德语/日语文档页面:0
校准 · 策略
这项工作基于我们面向技术 SEO 的 Signal 方案。每项策略消除一个噪声来源,并且都配有一项检查,确保修复不会在下一次发版时悄悄倒退。
把文档从纯客户端单页应用改为构建时静态预渲染,并在每次发版时增量重新生成。现在每个页面在第一个 HTML 响应里就带着完整的正文、标题和代码示例;JavaScript 只负责增加交互。
在 CI 中运行原始 HTML 一致性检查:渲染后文本与原始文本相差超过 2%,构建即失败。
用真实路径(/docs/collectors/otel)取代哈希路由,把 span 导航改为锚链接,并设立一个“latest” canonical,让各版本页面都指向它。加上面包屑导航,任何指南最多点击 3 次即可到达。
孤立页面:4,100 → 0。点击深度中位数:7 → 3。
在 robots.txt 中屏蔽浏览器分面和会话参数,去掉链接里的令牌,返回真实的 404/410 状态码,并按版块拆分站点地图,lastmod 日期直接取自文档仓库,准确无误。
规范文档 URL 在抓取中的占比:29% → 94%。
为每种语言单独设立子目录(/de/、/ja/)并做服务端渲染,再在 HTML head 和站点地图里同时加上互相指向的 hreflang 与 x-default,全部由翻译清单自动生成,不会彼此脱节。
Hreflang 回链标记错误:1,960 → 0。
时基 · 1 格 = 1 个月
M01 · 探测
分析 30 天的 Googlebot 访问日志,逐个 URL 比对原始与渲染后的 HTML,并确立 1,120 个已收录文档页面的基线。
M02 · 探测
采集器指南(420 页)通过功能开关先行预渲染。五周内,该版块的收录数从 61 升至 388。
M03 · 校准
全部 6,040 个页面改为静态渲染,加入 CI 一致性检查,span 导航重建为真正的链接。
M04 · 校准
哈希路由换成路径,设置 6,000 多条一对一 301 重定向,各版本的 canonical 指向“latest”。
M05 · 滤波
屏蔽分面与令牌参数,修复软 404,站点地图按版块拆分并使用真实的 lastmod。
M06 · 滤波
德语和日语文档迁至 /de/ 和 /ja/,改为服务端渲染,并配上互相指向的 hreflang。
M07 · 锁定
针对 140 个开发者查询撰写对比页和操作指南:这些查询下排名的都是竞争对手的教程,而 Ferrovane 连一个页面都没有。
M08 · 锁定
把渲染、收录和 hreflang 检查接入发布流水线,一旦出现问题就向文档团队告警。
读数 · 结果
虚构企业的模拟情景,并非客户结果。排名和流量从无保证,详见我们的条款。
已锁定通道:0/4
已收录文档页面
1,120 → 4,940
自然注册
+88%
抓取错误
-93%
开发者查询前 10 名
+620
转动旋钮(拖动,或选中后用方向键),把每项指标从噪声中拉出来。
Google 排名,模拟数据。“—”表示未进入前 100 名。
| 查询词 | 语言 | 月搜索量 | M0 | M8 |
|---|---|---|---|---|
| opentelemetry collector config | EN | 6600 | 48 | #3 |
| structured logging kubernetes | EN | 2900 | — | #6 |
| fluent bit json parser | EN | 3400 | 22 | #4 |
| trace sampling strategies | EN | 1600 | — | #8 |
| promql vs logql | EN | 1300 | 67 | #5 |
| log retention policy gdpr | EN | 880 | 31 | #2 |
| log management dsgvo | DE | 1100 | — | #1 |
| opentelemetry exporter einrichten | DE | 590 | — | #3 |
| ログ 監視 ツール 比較 | JA | 1900 | — | #7 |
“opentelemetry collector config”,模拟数据。
M0 · #48
…… Ferrovane 排在第 5 页
M8 · #3
曲线结束
如果搜索引擎看不到您的用户所看到的内容,Signal 会先做一次渲染与抓取审计,再把发现的问题变成您的工程师可以直接上线的修复。