Cloudflare Pages 部署
使用 Cloudflare Pages 托管 Docusaurus 的静态构建产物。
构建设置
在 Cloudflare Pages 中使用下面的配置：
| 配置项 | 值 |
|---|---|
| 框架预设 | None |
| 构建命令 | npm run build |
| 构建输出目录 | build |
| 根目录 | / |
| Node.js 版本 | 22 |
构建过程
npm run build 依次生成内容图谱与精简导航数据、构建 Docusaurus、生成订阅源和 Pagefind 索引、生成离线 IndexNow 清单，最后运行 SEO 检查：
npm run build
生成的 build/pagefind/ 目录会和其他静态文件一起部署。
GitHub 部署流程
- 将代码推送到
main分支。 - Cloudflare Pages 根据
package-lock.json安装依赖。 - Cloudflare Pages 执行
npm run build。 - Cloudflare Pages 发布生成的
build/目录。
functions/_middleware.js 配合 static/_routes.json，仅为 /404、/404/、/404.html 和 /404.html/ 返回真实 404 与 X-Robots-Tag: noindex,follow。普通页面和随机不存在的 URL 继续使用 Pages 原生静态路由，不将全站流量转入 Functions。发布时应保留仓库根目录的 functions/，不要仅上传静态目录而省略 Functions。
部署后 IndexNow 增量提交
构建过程只生成 build/indexnow-manifest.json，不调用 IndexNow。清单指纹来自正文、标题、描述、结构化数据、正文链接和图片，不受运行时 JS 文件名或页脚年份变化影响。
仓库的 .github/workflows/indexnow.yml 在部署成功事件后运行；对于只上报检查状态、不发送部署事件的 Pages 集成，每小时进行一次生产清单检查，也支持 Actions 页面手动触发。流程不依赖私密 API Token，仅检查固定的生产域名。
- 读取线上生产清单，与最后一次成功提交的清单比较。
- 对新增/变更页面验证 HTTP 200、Canonical、索引指令和正文指纹；删除的页面需返回 404 或 410。
- 再次确认发布清单未变化，再提交新增、变更、删除的 URL。
- 仅在 IndexNow 返回 200/202 后保存状态。校验或提交失败时保留原状态，后续任务重试。
初次执行会为全部公开 URL 建立基线；此后未变化的构建不会重复提交。GitHub Actions 缓存保存已确认状态；缓存被清理后会重新建立基线。仓库需开启 Actions，定时任务从默认分支执行。首次发布前若线上尚无清单，任务跳过提交。
手动执行时也应先完成生产部署：
# 仅验证生产页面；不提交，也不更新状态
npm run submit:indexnow -- --dry-run
# 验证通过后提交，状态保存在 .cache/indexnow-state.json
npm run postdeploy:seo
如需限定某次发布，可设置 INDEXNOW_EXPECTED_REVISION 为该次提交的完整 SHA；脚本将在对应版本尚未上线时退出，不提前提交。成功接收通知不代表页面已被索引。
回归验证
npm run test:seo
npm run build
# 另一个终端启动 wrangler pages dev build --port 4173 后：
npm run test:seo:browser
单元测试覆盖增量、删除、重复提交、失败状态保留、生产一致性与网络预取策略。浏览器测试覆盖实际 404 状态、错误页 noindex、移动端预取和 SPA 导航。仅验证本地构建时，不执行 postdeploy:seo。
SEO 发布检查
生产构建应生成 sitemap.xml、robots.txt、llms.txt 和 llms-full.txt。Markdown 源文件不应被复制进 build/，公开入口以渲染后的 HTML 页面为准。
站点所有文章（Markdown Frontmatter）及静态页面（如 src/data/about.json）均采用显式 published_at 与 updated_at 元数据。此机制解耦了构建环境与 Git 浅克隆（--depth=1）的历史限制，确保线上 Sitemap 与结构化数据的时间戳完全幂等且不受部署提交时间影响。若未来新增依赖完整 Git 历史的构建插件，可在构建命令前加入 git fetch --unshallow || true。