Build Docs 因远程徽章拉取(shields.io)零星失败——让 apps/site 构建对图片拉取故障健壮

[os-zhuang]

现象

Build Docs(@object-ui/site#build)在构建时用 fumadocs 的 remark-image 插件拉取远程图片(shields.io 徽章)以取得图片尺寸(getImageSize)。shields.io 一抖(Cloudflare 520 / 1200 "Too many requests")就会抛错并让整个 docs 构建失败。

实例:PR #2684 期间该 job 因 shields.io 抖动连续两次红(Cloudflare 520/1200),与 PR 内容无关,重跑到 shields.io 恢复后才绿。

影响

• 与代码改动无关的外部抖动会零星卡住任意 PR(和 main);
• 若 Build Docs 是必需检查,会误阻塞合并。

根因

docs 站构建在构建期出网拉远程徽章图片,把一个外部服务的可用性变成了构建的硬依赖。

方案(任选/组合)

1. 给 remark-image 配置失败跳过 / 超时容忍,远程图片拉取失败时告警而非 fail 构建;
2. 把徽章本地化(下载进仓库)或在 markdown 里内联尺寸,避免构建期出网;
3. 或在受影响文档里移除对远程 shields.io 徽章的构建期尺寸解析依赖。

验收

• shields.io(或任意远程图片源)不可用时,Build Docs 不再整体失败;
• 定位并处理触发拉取的具体徽章引用。

备注

属 apps/site 基础设施,与 batchTransaction 重构(#2679 / #2684)无关,单独跟踪。