这篇写给做静态站、内容站、自动化发布流水线的人:文章已经能正常打开,但「发出去」这一步时好时坏,而且坏的时候自己这边全是绿的。
约 9 分钟读完;需要你会用命令行和一点 JavaScript;不懂搜索引擎收录协议也能跟,第一次出现时会解释。
环境准备:Node.js 18 以上和系统自带的 curl,不需要 npm install 任何包。
下面这张表列出四类读者各自能拿走什么,按你的目的直接跳到对应小节。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 接了第三方翻译或摘要接口的开发者 | 一张按实测延迟切块、留余量的配置表 | 照第 2 节量一遍自己的接口延迟,再定块大小和超时 | 2 |
| 给搜索引擎推送新链接的人 | 「同一份数据换三个服务对照」的判别法 | 用第 3 节的命令判断 403 是 key 还是服务端问题 | 3 |
| 做了分享按钮 / 复制链接的前端 | 一段编码前后对比 | 照第 4 节把自己的分享链接改一行 | 4 |
| 想让 AI 智能体做发布后巡检的人 | 一张「外部信号 vs 本地日志」对照表 | 把第 5 节的表当成验收标准 | 5 |
不适合完全手动发布、也不接外部服务的读者:这三处故障都发生在跨系统边界上。
三件事看起来无关,但它们的排查方式是同一个:不要看自己这边的返回值,去要一个只有外部才能给出的信号。全貌如下。
三处故障放在一起对照如下。
| 你看到的现象 | 自己这边显示 | 外部真正的状态 | 本文给的判据 |
|---|---|---|---|
| 英文版整篇被判失败,中文版正常 | 翻译任务返回了结果 | 某一块超时,整篇被记为不完整 | 块耗时必须留出超时余量,而不是刚好卡线 |
| 新文章推给搜索引擎一直被拒 | 请求发出去了 | 服务端 403,可能只是这个 key 被拉黑 | 同一份数据换服务对照,三个结果不一致就指向 key |
| 分享到聊天软件,对方点不开 | 复制成功、链接看起来完整 | 客户端只识别了前半段英文字符 | 链接里不允许出现未编码的非 ASCII 字符 |
下面逐条展开,每条都按「为什么会坏 → 怎么修 → 差别在哪」写。
流水线最容易给人的错觉是「命令退出了 0,所以事情成了」。但这三处的成功判定都在别人的服务器上:
所以排查顺序永远是:先把「外部返回了什么」抓下来,再回头改自己的代码。下面三节各自给出这个「外部信号」怎么拿。
因为超时设置常常是「凭感觉写一个 4 秒」,而这个值恰好落在真实延迟的区间里——大部分时候能过,长文章必挂。
把中文按 1800 字切块,逐块调用一个模型网关做翻译,单次请求硬超时 4000 毫秒。任何一块失败,整篇记为「部分完成」,不发布。
实测这一档的耗时:1800 字的块需要 3.7~4.1 秒,已经压线甚至超过 4000 毫秒。于是长文章几乎必挂,短文章侥幸通过——这就是「时好时坏」的来源。
先量清楚每一档的真实耗时,再选块大小。同一批内容按不同块长测出来是这样:
各档块长的实测耗时如下。
| 每块字数 | 实测耗时 | 相对 4 秒超时的余量 |
|---|---|---|
| 600 | 1.7~3.0 秒 | 充足 |
| 1000 | 2.5~2.7 秒 | 约 1.3 秒 |
| 1200 | 3.1~3.2 秒 | 约 0.8 秒 |
| 1400 | 3.0~3.2 秒 | 约 0.8 秒 |
| 1800 | 3.7~4.1 秒 | 不够,会撞线 |
最终定下来的参数如下,每一行都有实测依据。
// 翻译客户端的关键参数(示例)
const CHUNK_MAX = 1000; // 每块字数:实测最慢 2.7 秒
const TIMEOUT_MS = 8000; // 单块超时:留出约 3 倍余量
const MAX_CHUNKS = 25; // 块数上限:25 × 1000 ≥ 最长文章
MAX_CHUNKS 也是踩出来的:原来的上限 14 是按普通文章估的,遇到一万多字的长文,块数会超过上限,整篇被直接判成不完整。上限必须按「最长文章的块数」反推,不能按普通文章估。
两种参数组合的差别如下。
| 对比项 | 1800 字 / 4 秒 | 1000 字 / 8 秒 |
|---|---|---|
| 单块最慢耗时 | 4.1 秒(超时) | 2.7 秒(余量 1.3 秒) |
| 长文章(1.2 万字) | 块数超上限 14 → 判失败 | 12 块,上限 25 → 通过 |
| 失败的可解释性 | 「有时成功有时失败」 | 每块都有明确耗时,可回归 |
翻译前要把正文里的链接「保护」起来,翻译后再放回。链接识别用的正则如果只把空格和引号当结束符,遇到被多个反引号包起来的链接,就会把后面的整行都吞进 URL 里。翻译回来一比对,校验发现原文的链接不见了,于是判失败——真正的原因是识别错了,不是翻译错了。
修法三件:结束字符补上反引号、括号和中文标点;保护和还原改用唯一序号做占位,并在还原时跳过空片段;完整性校验从「逐字比对」改成两条更稳的规则——译文里不能凭空多出原文没有的链接,代码围栏数量必须不变。
因为「推送失败」最常见的第一反应是「key 过期了,换一个」,但换 key 可能白忙;反过来,如果真是 key 被拉黑,改代码也永远修不好。
先解释这一步在做什么:搜索引擎的即时收录协议允许你主动 POST 一条新链接,请求它尽快来抓。你的站点没有变,只是「通知」这一步失败,所以搜索引擎那边看起来一切正常,只是不收录新文章。
看到接口返回 403,先怀疑自己的密钥文件路径错了、内容被改了,于是反复改配置——但 key 文件明明能正常下载,内容也逐字节正确。
同一份数据,分别发给三个支持同一协议的服务,看结果是否一致:
# 同一份 JSON,换三个服务对照(key 从环境变量读,不写死在命令里)
for host in api.indexnow.org search.seznam.cz yandex.com; do
echo "== $host"
curl -s -o /dev/null -w "%{http_code}\n" \
-X POST "https://$host/indexnow" \
-H "Content-Type: application/json; charset=utf-8" \
-d "{\"host\":\"example.com\",\"key\":\"$INDEXNOW_KEY\",\"keyLocation\":\"https://example.com/$INDEXNOW_KEY.txt\",\"urlList\":[\"https://example.com/post/1\"]}"
done
跑完会看到三个数字。实测是 200 / 202 / 403:两个服务接受,只有原来那个拒绝。同一份数据、同一个 key、同一天,这个组合只可能指向一个结论——key 值被某一家单方面标记了,而不是文件或格式的问题。
于是处理方式从「改代码」变成「换 key」:生成新 key、上传新的 key 文件、删掉旧的 key 文件并确认访问它返回 404、再用新 key 重发。同时记住这条判别法,下次遇到 403 先用它分流。
两种排查方式的差别如下。
| 对比项 | 只怀疑自己 | 换服务对照 |
|---|---|---|
| 排查方向 | 反复检查本地配置 | 一次比较定位到「哪一家、哪一层」 |
| 能否推翻旧结论 | 不能,旧结论会一直挂着 | 能,此前「文件或格式有问题」的判断当场被推翻 |
| 修复动作 | 改配置(可能无效) | 轮换 key(一次到位) |
因为这类问题在自己电脑上永远复现不了:浏览器地址栏会自动把中文显示回来,看起来完全正常;只有粘贴到聊天软件、对方点的时候才断。这里的门槛是 ASCII(英文、数字和常用符号使用的那套字符编码,中文不在其中):链接里一旦出现中文,部分客户端只认到中文之前的那一段。
先看原来的写法:中文原样拼进 URL。
// 原来的做法:中文原样拼进链接
const title = "炮塔为什么一直抖";
const shareUrl = `https://example.com/blog/${title}`;
链接在浏览器里能打开,是因为浏览器在发送前会自己编码。但把这段文本复制到聊天软件时,客户端只把第一个非 ASCII 字符之前的部分识别成链接,后半段变成普通文字——对方点到的其实是一个不存在的短地址。
对路径和查询参数分别编码,拼出来的字符串里不出现任何非 ASCII 字符:
编码后的拼接方式如下,拼出来的字符串里不会出现中文。
// 现在的做法:每一段都编码
const shareUrl =
`https://example.com/blog/${encodeURIComponent(slug)}` +
`?from=share&title=${encodeURIComponent(title)}`;
两种拼接方式的差别如下。
| 对比项 | 原来拼接 | 编码后拼接 |
|---|---|---|
| 链接里有没有中文字符 | 有 | 没有,全是 %E4%BD%A0 这种形式 |
| 粘到聊天软件 | 只识别前半段,点开 404 | 整段识别为链接 |
| 在浏览器里看 | 显示中文,看着正常 | 也显示中文(浏览器会解码显示) |
注意 encodeURI 和 encodeURIComponent 的区别:前者保留 :/?& 这些分隔符,适合编码一整条 URL;后者把分隔符也编码,适合编码单个参数值。分享链接是把「已经确定的模板 + 一段值」拼起来,所以值用后者。
因为这三处都可以「本地全绿但外部全错」。下面这张表就是巡检时该看的东西。
| 检查项 | 通过 | 不通过 | 命令 / 依据 |
|---|---|---|---|
| 翻译完整性 | 英文版每一节都有内容,链接数量与中文版一致 | 某段变空、链接消失 | 比对两版的链接数与代码围栏数 |
| 翻译延迟 | 每块耗时 < 超时的 1/2 | 最慢块 4.1 秒、超时 4 秒 | 在日志里记录每块耗时 |
| 推送接受度 | 目标服务返回 2xx | 返回 403 | 上面那段换三个服务的命令 |
| 分享链接可识别 | 整段不含非 ASCII 字符 | 含中文 | 对拼出的字符串跑一次 /[^\x00-\x7F]/.test(url) |
配套的三道验收:翻译改动后跑原有的端到端场景(本次新增 3 个场景,30 条全绿);推送改成「每天巡检时用真实 key 发一条测试链接」,403 立刻告警;分享链接在拼装函数里直接断言不含非 ASCII,命中就抛错。
这套判据的好处是:不依赖作者在场。定时任务跑完,看的是外部返回码而不是自己的「已完成」日志。
内容离开本站之后,成功由别人定义。三处故障对应三个外部信号:翻译看每块的耗时与完整性校验;推送看服务端状态码,并且用「同一份数据换服务对照」区分「key 被拉黑」和「自己配置错」;分享看拼出来的字符串里有没有未编码的非 ASCII 字符。共同判据只有一句:本地返回成功不算成功,必须拿到外部给出的、可对照的信号。
边界也很清楚:
一是翻译仍然按字符数切块。中文和英文的 token 密度不同,同样 1000 字,含大量英文术语的段落会更慢。下一步可以按「上一次同类块的实际耗时」动态调整块长。
二是换服务对照是手动的。现在只有出问题时才跑那段循环。下一步可以让巡检每天自动跑三个服务,把「只有某一家拒绝」当成独立告警项。
三是分享链接只覆盖了复制粘贴。聊天软件内置的分享接口有各自的参数格式,未逐一验证;目前能保证的是「复制的纯文本链接在对方客户端里可被整体识别」。
在发布流水线的最后加一步:把当天生成的分享链接打印出来,跑一次「不含非 ASCII 字符」的断言;再把推送那一步改成记录服务端返回码。两个小改动就能把「以为发出去了」变成「确认对方收到了」。
这些内容来自一个真实内容站连续多天的发布故障排查:一次是长文章翻译稳定失败,一次是搜索推送持续被拒、在推翻此前的结论后才定位到密钥,一次是分享链接在聊天软件里断掉。文中所有耗时、状态码和块数都是当时实测记录,修复后都补了对应的自动化场景或巡检项。