Skip to content

fix(sitemap): write real per-page lastmod from git history - #1341

Open
nic75408 wants to merge 1 commit into
longbridge:mainfrom
nic75408:fix/sitemap-lastmod
Open

nic75408 wants to merge 1 commit into
longbridge:mainfrom
nic75408:fix/sitemap-lastmod

Conversation

@nic75408

Copy link
Copy Markdown
Contributor

背景

开发者平台三份网站地图(/en、/zh-CN、/zh-HK/sitemap.xml,共 1,404 个网址)都没有 <lastmod>,Google 不知道哪页改过:抽查的 6 个文档页源文件都在 Google 最近一次抓取之后改过,仍停在「已抓取未编入」。仓库里已有按提交记录取日期的代码(src/lib/last-updated.ts,页面底部 Last Updated 用),线上没生效:构建流水线 fetch-depth: 1 没有历史;代码只认迁移前的 .md 文件名。

改动

文件 改了什么
src/lib/last-updated.ts 读 HEAD 历史(原来是 origin/main),认 .mdx,保留 .md 兜底、两者取较新;浅克隆时返回空,避免把构建那次提交的日期盖到每一页;加 --no-renames,部分克隆下不触发拉 blob
src/lib/sitemap-lastmod.ts(新) 读 docs 集合同一批 .mdx 的 frontmatter,用页面路由同一个 resolveUrl 建「网址 → 源文件」对照,slug 改过网址的页面也能对上(how-to-parse-push.mdx → /docs/socket/protocol/push)。只给 <locale>/docs/ 下 docs 布局的页面写日期;首页、sdk/pricing/skill 营销页、API Reference(/docs/api、/docs/api/*,由 openapi.yaml 生成)不写;取不到日期就不写,不用构建当天兜底
astro.config.ts sitemap serialize 有日期时输出 lastmod
.github/workflows/release.yml(3 个 job)、canary.yml、canary-cloudflare.yml、canary-aliyun.yml checkout 改 fetch-depth: 0
src/lib/*.test.ts 单测:.mdx 映射、.md 兜底取较新、slug 指定网址、取不到日期不写、浅克隆一条都不写、真实 docs 目录三语 slug 对照

build.yml(PR 构建检查)和 autocorrect.yml 保持 fetch-depth: 1:不发布,网站地图日期无关紧要,也正好覆盖「没有历史时不写日期」这条路径。

取舍: 全量历史而不是固定深度。固定深度(如 50)时,最老那次提交在 git 里像根提交,会把所有文件都记成那天,日期就错了;所以代码对浅克隆一律不写。仓库约 11 MB、1,107 次提交,全量拉取预计只多几秒,对构建时长影响可忽略(未在 Actions 上实测)。

顺带:页面底部「Last Updated」在线上会恢复显示(DocMeta.astro 已有逻辑,没改)。

验证

按仓库 CLAUDE.md 没有在 AI 会话里跑 build:*,用下面的方式替代验证:

  • 用新代码对线上三份网站地图的全部网址逐条算 lastmod(共 1,404 个):
网站地图 网址数 有 lastmod API Reference(无) 不写的非 API 页 等于今天
en 472 305 162 5(/、/pricing、/sdk、/skill、/skill/install) 0
zh-CN 466 299 162 5(同上,中文前缀) 0
zh-HK 466 299 162 5(同上,中文前缀) 0
  • 抽查:/docs/cli/orders/exchange-rate → 2026-11-09T19:04:49+08:00;/docs/screener/screener-search → 2026-10-15T18:33:39+08:00;/docs/socket/protocol/push(源文件 how-to-parse-push.mdx)→ 2026-10-22T16:33:35+08:00。
  • bun run test(vitest 88/88)、tsc --noEmit(仅剩一条已有的 McpToolsIsland 生成文件缺失,与本 PR 无关)、oxlint、astro sync 通过。

麻烦构建时看一眼 dist/en/sitemap.xml、dist/zh-CN/sitemap.xml、dist/zh-HK/sitemap.xml:文档页带 <lastmod>,/docs/api/* 没有,以及文档页底部出现 Last Updated。

上线后验证

首屏自查

只改网站地图生成和构建流水线(构建时多读一次 git 历史),页面不加请求、不加脚本;HTML 只多一行已有的 Last Updated 文字,首屏接口和加载耗时不变。

🤖 Generated with Claude Code

- last-updated: read HEAD history for .mdx (keep .md fallback, newer wins);
  return nothing on shallow clones instead of stamping the build commit date
- sitemap-lastmod: map sitemap URLs back to source files via resolveUrl, so
  frontmatter slugs (how-to-parse-push.mdx -> /docs/socket/protocol/push)
  resolve; only docs-layout pages under /docs get lastmod, API reference,
  homepage and marketing pages are left without one
- astro.config: sitemap serialize emits lastmod when known
- release / canary workflows: fetch-depth 0 so the build has git history

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nic75408

Copy link
Copy Markdown
Contributor Author

补充一点输出格式:sitemap 库会把 lastmod 统一转成 UTC 的 ISO 时间(new Date(x).toISOString()),所以网站地图里写的是 2026-11-09T11:04:49.000Z 这种形式,日期部分和 PR 描述里的抽查结果一致(exchange-rate 2026-11-09、screener-search 2026-10-15、socket/protocol/push 2026-10-22)。生成的条目里 <lastmod> 紧跟在 <loc> 后面。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants