博客迁移 Cloudflare Pages 踩坑复盘

发布于 2026年02月15日 11:09

#DevOps

复盘日期：2026-02-15 域名：wangruofeng007.com 目标：新博客迁移到 Cloudflare Pages，旧博客 blog 子域继续保留 GitHub Pages

背景

博客之前托管在 GitHub Pages，新年伊始决定将主站迁移到 Cloudflare Pages。本以为是个简单的迁移，结果踩了个遍。遂整理此文，希望对有类似需求的同学有所帮助。

目标架构

迁移完成后期望的域名映射：

  • https://wangruofeng007.com → 新博客（Cloudflare Pages）
  • https://blog.wangruofeng007.com → 旧博客（GitHub Pages）
  • 邮件（MX/SPF/DMARC）继续可用

踩坑总览

在开始之前，先列出这次遇到的所有坑：

  1. 把「改 NS」和「改解析记录」混在一起，导致状态一直看不懂
  2. Cloudflare 处于 pending 时，误以为 Cloudflare 记录已生效
  3. 直接 CNAME 到 tech-blog.pages.dev，但账号下没有对应 Pages 项目，触发 Error 1014
  4. SSL 模式选成 Flexible，误以为是证书问题主因
  5. 在 Pages 项目里用了 Workers 的部署命令：wrangler deploy
  6. 改成 wrangler pages deploy 后又报 wrangler: not found（环境没全局 wrangler）
  7. 用 npx wrangler pages deploy 后再报 Authentication error 10000（Token 权限/模式冲突）
  8. Node 版本与本地不一致（云端默认 Node 22），增加不确定性
  9. Non-production deploy command 填错（wrangler versions upload 不适用于 Pages）
  10. 邮件记录只保留 1 条 MX，可用但冗余不足
  11. giscus app 配置在博客主仓库，导致博客文章源码需要变成公开，正确做法是单独创建一个 public 仓库进行配置 giscus 评论系统，例如我的是这个仓库是 tech-blog-comment

逐条复盘

1. Cloudflare 一直 pending

现象：Cloudflare Overview 显示 Waiting for your registrar to propagate your new nameservers。

根因：权威 NS 还没完全切到 Cloudflare，或还在传播。

处理：

  • 在阿里云域名控制台（不是云解析记录页）确认 NS 为：
    • ivan.ns.cloudflare.com
    • mckenzie.ns.cloudflare.com
  • 等待传播完成，状态变 Active

2. 阿里云出现「当前解析记录不生效」警告

现象：阿里云云解析页提示当前记录不生效。

根因：NS 已改到 Cloudflare，阿里云记录自然不再是公网权威数据。

处理：无需修复，这是正常状态；后续只在 Cloudflare 改 DNS。

3. Error 1014: CNAME Cross-User Banned

现象：@/www 打不开，报 1014；blog 正常。

根因：手工将域名 CNAME 到 tech-blog.pages.dev，但当前账号下无对应 Pages 项目或未正确绑定自定义域，触发跨账户限制。

处理：

  • 先创建并成功部署本账号下的 Pages 项目
  • 在项目中添加自定义域：wangruofeng007.com
  • 再校准 DNS 指向

4. 构建成功但部署失败

现象：astro build 全绿，最后 deploy 失败。

根因：部署命令配置不正确（Pages 与 Workers 命令混用）。

处理演进：

  • npx wrangler deploy → 错（Workers 命令）
  • wrangler pages deploy → 错（wrangler 未安装）
  • npx wrangler pages deploy ... → 可执行，但又遇到 API Token 鉴权问题

5. Authentication error [code: 10000]

现象：npx wrangler pages deploy ... 调 API 失败，提示 CLOUDFLARE_API_TOKEN 权限问题。

根因：该流程依赖 API Token，当前 token 权限或作用域不满足。

建议处理（推荐）：

  • 使用 Pages 的 Git 托管构建/部署模式（只配置 Build command + Output dir），不要再额外执行 wrangler deploy 命令
  • 若必须 wrangler 部署，再单独配置具备 Pages 编辑权限的 Token

6. Node 版本漂移

现象：日志初期使用 Node 22，本地以 Node 20 为主。

根因：Cloudflare 默认运行时版本未固定。

处理：

  • 项目内增加：
    • package.json → "engines": { "node": "20.x" }
    • .nvmrc → 20
  • Cloudflare 项目环境变量设置：NODE_VERSION=20

最终推荐配置

DNS（Cloudflare）

类型名称内容代理状态
CNAMEblogwangruofeng.github.ioDNS only
CNAME@tech-blog.pages.devProxied
CNAMEwwwtech-blog.pages.devProxied

邮件相关（MX/TXT）全部 DNS only

Pages

  • 项目已存在并能成功构建
  • Custom domains 已添加：wangruofeng007.com
  • Build command：npm run build
  • Build output directory：dist
  • Node：20

常用部署命令

手动部署本地构建产物到 Cloudflare Pages：

npx wrangler pages deploy dist --project-name tech-blog

前置条件：

  • 安装 wrangler：npm install -g wrangler
  • 身份验证：wrangler login

推荐方式：使用 Git 托管构建模式（配置 Build command + Output dir），避免手动部署的 Token 权限问题。

SSL/TLS

  • 建议使用 Full（Pages 场景）
  • Always Use HTTPS 开启

一套可复用的迁移 SOP

  1. 明确目标域名映射（@/www/blog 各指向哪里）
  2. 先创建 Pages 项目并完成首次成功部署
  3. 在 Pages 项目中先绑定自定义域
  4. 再修改 DNS 记录
  5. 最后切 NS 到 Cloudflare
  6. 等待 Active 后进行全链路验收
  7. 验证邮件记录是否仍可用

验收清单（上线前 10 分钟）

  • Cloudflare Zone 状态为 Active
  • www 访问新站正常
  • @ 访问行为符合预期（直达或跳转）
  • blog 访问旧站正常
  • 没有 1014/525/526 等错误页
  • Sitemap/RSS 域名为正式域（非 pages.dev）
  • 邮件收发正常（MX/SPF/DMARC/DKIM）

关键经验总结

  1. 先有 Pages 项目，再做域名指向，否则极易触发 1014
  2. NS 是总开关，没切到 Cloudflare 前，Cloudflare 记录不会真正生效
  3. 构建成功不代表部署成功，要分开看 build 与 deploy 阶段日志
  4. Pages 与 Workers 是两套发布路径，命令不能混用

如果你也在考虑迁移博客到 Cloudflare Pages，希望这篇复盘能帮你少走弯路。有问题欢迎评论区交流。

评论互动

© 2026 王若风的技术博客 · Powered by Astro