把站点从 GitHub Pages 搬到 Cloudflare Pages

这个站原先放在 GitHub Pages。仓库改成私有之后，我把托管换到了 Cloudflare Pages，构建仍由 GitHub 的 push 触发，写文章的流程没有变。

迁移本身不复杂，费时间的是我一开始建错了项目类型，又误以为修改项目名就能换掉 pages.dev 子域。把这两件事记下来，免得下次再踩一遍。

为什么换托管

GitHub 免费账户使用 GitHub Pages 时，站点仓库需要公开。Cloudflare Pages 可以直接构建私有仓库，这正合适：公开的是构建后的网页，不必连草稿和提交历史一起公开。

两边对静态站的使用方式很接近。Cloudflare Pages 连接 GitHub 仓库后，每次 push 自动构建；Astro 的构建命令是 npm run build，输出目录填 dist。Node 版本固定为 22，避免构建环境日后升级带来意外。

我一开始建成了 Worker

Cloudflare 控制台里，Worker 和 Pages 的入口很容易混淆。我第一次实际创建的是 Worker + 静态资源，所以拿到的是 workers.dev 地址，而不是预期的 pages.dev。

构建日志也能看出来：

Configuring project for Astro with "astro add cloudflare"
[build] directory: /opt/buildhome/repo/dist/
[build] adapter: @astrojs/cloudflare
Using redirected Wrangler configuration.

它给项目加入了 Cloudflare 适配器，输出也变成了 dist/client。我的站点没有服务端渲染，不需要 Worker 运行时，这些配置都用不上。

简单说，Pages 负责构建和托管静态站；Worker 用来在边缘运行代码，需要 API、KV、D1、R2 或登录态时才有意义。这次删掉 Worker 项目，只保留 Pages。

私有仓库要检查构建授权

仓库公开时，Worker 和 Pages 都能克隆代码。仓库转为私有后，Worker 的构建开始在 clone 阶段失败，Pages 则仍然正常。

原因是两边的 GitHub 授权并不通用。Pages 已通过 GitHub App 获得仓库权限，Worker 没有可用凭据。以后遇到类似问题，先看失败发生在哪一步：如果代码还没克隆下来，就没有必要先排查 Astro。

改项目名不会改 pages.dev 子域

我原以为控制台里的 Project name 同时决定访问地址。实际改名后，控制台路径变了，部署地址却没有变。

官方文档对此写得很直接：

*.pages.dev subdomains currently cannot be changed. If you need to change your *.pages.dev subdomain, delete your project and create a new one.

也就是说，想换子域只能新建项目。旧地址不会自动重定向，原项目的部署历史和回滚点也不会带过去。源码还在 Git 仓库里，所以这次重建没有造成内容损失。

域名配置集中在一处

迁移期间换过几次地址，我把 Astro 的 site 改为读取环境变量：

const site = process.env.SITE_URL ?? "https://mopango.pages.dev";

export default defineConfig({
  site,
  output: "static",
  integrations: [sitemap()],
});

canonical、og:url 和 sitemap 都使用这个值。以后绑定自定义域名，只需要改这里的默认值，或者在托管平台设置 SITE_URL。

有一点值得注意：新地址真正能访问之后，再把它写进 canonical。否则搜索引擎拿到的正式地址可能还是一个 404 页面。

最后保留的配置

_headers 只加了两类规则。带内容哈希的 _astro 静态资源使用长缓存，其余页面补上基本安全头：

/_astro/*
  Cache-Control: public, max-age=31536000, immutable

/*
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin

部署完成后，我检查了首页、文章页、RSS、sitemap 和 404 页面，再关闭旧托管。目前仓库保持私有，公开站点是 mopango.pages.dev。

pages.dev 在国内的可达性不算稳定。如果以后这个站需要长期给别人访问，我会绑定自己的域名；暂时先不为一个个人笔记站增加备案和国内 CDN 的维护成本。