跳转至

Cloudflare Pages 部署指引

项目文档站（MkDocs build 的 site/）部署到 Cloudflare Pages。 用 CF Pages 直连 GitHub 方式，push 后自动 build + 上线。不需要 GH Actions、不需要 wrangler、不需要 API token。

一次性配置（5 分钟）

Step 1: 登录 Cloudflare 创建 Pages 项目

  1. 打开 https://dash.cloudflare.com/
  2. 左侧菜单 → Workers & Pages → Create application → Pages tab → Connect to Git
  3. 授权 Cloudflare 访问 GitHub（首次需要 OAuth）
  4. 选择 repo：suxuemi/laifaxin-chajian-ditu
  5. 点 Begin setup

Step 2: 配置 build

在 Project setup 页面填：

字段 值
Project name laifaxin-google-map-docs（或自取）
Production branch main
Framework preset None
Build command pip install -r requirements-docs.txt && cp -f CHANGELOG.md docs/ 2>/dev/null; mkdocs build
Build output directory site
Root directory (留空)

Step 3: 环境变量

在 Environment variables (advanced) 展开：

Variable name Value Type
PYTHON_VERSION 3.11 Production + Preview

CF Pages 默认 Node 22 环境，加 PYTHON_VERSION 让 Python 可用。

Step 4: 保存并部署

点 Save and Deploy。Cloudflare 会立即跑首次 build。

完成后访问：https://<project-name>.pages.dev/

可在 Custom domains 绑定自己域名（如 docs.laifaxin.com）。

后续维护

无需任何手动操作 — 每次 push 到 main 分支，CF Pages 自动重新 build + 发布。

预览部署：push 到非 main 分支 → CF 自动生成 preview URL（PR 的 build 状态会显示）。

配置文件位置

文件 作用
mkdocs.yml (repo 根) MkDocs 配置：theme / plugins / nav
requirements-docs.txt (repo 根) CF Pages build 装的 Python 依赖（v0.10.111 起固化，关键：含 mkdocs-roamlinks-plugin）
docs/index.md 站点首页
docs/**/*.md 内容（五层漏斗）
CHANGELOG.md / development-log*.md repo 根 / docs/changelog 的，build 时 cp 复制

故障排查

build 失败 "ModuleNotFoundError: No module named 'mkdocs'"

  • 检查 build command 第一段 pip install ... 是否完整
  • 检查 PYTHON_VERSION env var 是否设置
  • 检查 requirements-docs.txt 是否在仓库根

站点上所有 〚english|中文〛 显示为字面文本（不渲染为链接）

  • 症状：页面上看到 〚development-log|开发日志〛 这种方括号字面文本
  • 原因：mkdocs-roamlinks-plugin 没装（v0.10.110 起项目用了 137 个这种 wikilink）
  • 修复：确认 build command 用 pip install -r requirements-docs.txt（不是手写 plugin 列表）
  • 历史教训：v0.10.110 之前是把 plugin 名写在 build command 里，依赖藏在 CF dashboard 外，容易丢

中文文件名 URL 404

  • 检查文件名是否含特殊字符（v0.10.105 已清理 + / （ / ） → -）
  • mkdocs build 输出会自动 URL encode 中文 — 正常的
  • 检查 pip install 命令是否含 mkdocs-roamlinks-plugin
  • 检查 mkdocs.yml 的 plugins: 是否含 roamlinks

push 后 CF 没自动 build

  • 检查 CF Pages Project → Settings → Builds & deployments → Production branch 是否设为 main
  • 检查 GitHub repo Settings → Webhooks 有没有 cloudflare 的 webhook（应该有，CF OAuth 时自动加）

切换到其他部署目标

如果未来要切回 GH Pages 或换 Vercel/Netlify： - 删除 CF Pages 项目（dashboard 操作） - 在 GitHub repo 添加对应 workflow - 不影响 mkdocs.yml（同一份配置适合所有目标）

相关