把 Astro 博客迁到 Cloudflare Pages:一次踩坑完整的部署复盘

Web
3088 字·11 分钟
阅读量: ... 次

这个博客最终跑在 https://blog.cospaye.com,托管在 Cloudflare Pages 上,推送即部署。

迁移本身并不难,难的是那些文档里不会写、但一定会让你卡住的地方:建项目时点错一个入口,你会得到一个访问就报 522 的空壳站;不加 404 页,你所有的错误链接都会静默地返回 200 和一份首页副本。这篇复盘按真实操作顺序记录全过程,包括踩过的坑和最终的验证方法。

一、先回答一个问题:你的 Astro 站到底需不需要 SSR

Cloudflare 上部署 Astro 有两条完全不同的路:

  • 纯静态:构建出 HTML 扔到边缘,不需要 adapter;
  • 按需渲染(SSR):需要 @astrojs/cloudflare adapter,生成一个 Worker 来处理请求。

判断方法很简单,看三处:

# 1. 有没有接入 adapter
grep -n "cloudflare" astro.config.mjs

# 2. 有没有页面显式声明不必预渲染
grep -rn "prerender" src/pages

# 3. 有没有用到请求上下文
grep -rn "Astro.request\|APIRoute\|middleware" src/pages src

本站三项结果是:没接 adapter;唯一的动态路由 search-index.json.ts 自己写了 export const prerender = true;只有 Header.astro 读了 Astro.request.url(构建期可用,不算 SSR 需求)。

结论:整站都是预渲染产物,不需要 adapter。

顺便说一个容易忽略的收益:不接 adapter 就绕开了 @astrojs/cloudflare 的 peer 依赖约束(它要求 astro ^7.4.0,而本站当时是 7.3.4),省掉一次非必要的升级。

二、三条部署路线怎么选

路线 做法 优点 代价
Pages + Git 集成(本站选择) 连 GitHub 仓库,push 自动构建 零维护、有预览环境、能一键回滚 首次配置要过 GitHub App 授权
Workers + 静态资源 写 wrangler.jsonc,wrangler deploy 命令行一键、静态请求免费不限量 需要本地登录,Git 集成要另配 Workers Builds
Pages 直接上传 wrangler pages deploy dist 最快 失去 push 自动部署,每次手推

Workers 路线如果是纯静态,配置简单到只有几行,关键是不要写 main:

{
  "name": "my-astro-blog",
  "compatibility_date": "2026-11-16",
  "assets": {
    "directory": "./dist"
  }
}

没有 main 意味着不跑任何 Worker 代码,只做静态资源托管。这条路线我在一开始也考虑过,最终选 Pages 的原因是更想要“推代码就上线”的顺滑感。

三、构建环境:一个必须先对表的版本矩阵

Cloudflare Pages 的 v3 构建镜像默认值是固定的:

项 镜像默认值 本站情况
Node.js 22.23.4 engines: >=22.12.0 ✅ 无需覆盖
pnpm 10.11.1 本机 12.15.0 ⚠️
系统 Ubuntu 22.04 x86_64 —

问题就在 pnpm 版本:本项目的 pnpm-workspace.yaml 用了两个较新的字段:

allowBuilds:
  esbuild: true
  sharp: true
minimumReleaseAgeExclude:
  - [email protected]

allowBuilds 和 minimumReleaseAgeExclude 都是新版 pnpm 才认识的。如果镜像用 10.11.1 跑,轻则忽略构建脚本(Ignored build scripts: esbuild),重则直接报未知字段。

解决办法不是改代码,而是在 Pages 项目里加一条环境变量,让镜像装上和本地一致的版本:

变量名 值 作用范围
PNPM_VERSION 12.15.0 Production + Preview 两个环境都要配

官方文档明确 pnpm 的“支持版本”是 Any version,且可以用 PNPM_VERSION 覆盖。同类变量还有 NODE_VERSION、YARN_VERSION、BUN_VERSION。

还有一个零成本的收益:本项目构建阶段不读取任何环境变量。全站搜索 import.meta.env 和 process.env 命中为 0,.env 只服务于本地的文章索引脚本。所以 Pages 里一个密钥都不用配 —— 把 .env 内容搬上去纯属扩大泄漏面。

四、最容易点错的一步:Connect to Git ≠ Upload assets

这是本次唯一真正的事故,值得单独讲。

Cloudflare 的 “Create an application” 页面会把几个入口摆在一起,其中两个长得很像:

  • Connect to Git:连接仓库,每次推送自动构建;
  • Upload assets / Direct Upload:直接上传一个目录,适合手动发布。

我选错了后者。项目建好后域名分到了,但部署产物是空的 —— 于是访问任何路径都返回:

HTTP/2 522
server: cloudflare
cf-ray: a5b6817ff92928cb-LAX

error code: 522

522 到底是什么意思

522 表示 Cloudflare 边缘连不上“源”。对 Pages 来说,源就是你的部署产物 —— 没有部署,自然没有东西可服务。

这件事的关键判据只有一句:

用 Connect to Git 建的项目,会立刻触发首次构建,无论成功还是失败,Deployments 里都会留下一条记录。

所以当 Deployments 列表完全为空时,不要怀疑代码、不要怀疑构建配置、不要折腾 pnpm 版本 —— 问题是“仓库从来没接上”。

为什么不能凭 522 直接下结论

一开始我也怀疑是自己的网络被墙,毕竟 *.pages.dev 在国内常有访问问题。为了区分“站点坏了”和“我连不上”,做了四层排除:

① DNS 层面:用随机域名做对照,排除通配符干扰。

dig +short my-astro-blog-xxxx.pages.dev A     # 172.66.44.106 ← 解析正常
dig +short zzz-not-exist-98765.pages.dev A    # NXDOMAIN     ← 说明不是泛解析

② 边缘层面:看响应头有没有 cf-ray。有,说明请求确实到了 Cloudflare 边缘,不是本地 DNS/防火墙拦的。

③ 换出口:直连、走本地 socks5 代理、强制 HTTP/1.1,三种方式结果一致(都是 522),排除单一线路问题。

④ 对照组:这一招最关键 —— 拿别人的 Pages 项目做对照。

curl -s -o /dev/null -w '%{http_code}\n' https://my-astro-blog.pages.dev   # 200 ← 别人家的,正常
curl -s -o /dev/null -w '%{http_code}\n' https://pages-demo.pages.dev      # 403 ← 存在,有访问保护
curl -s -o /dev/null -w '%{http_code}\n' https://nextjs.pages.dev           # 404 ← 存在,无内容
curl -s -o /dev/null -w '%{http_code}\n' https://<你的项目>.pages.dev        # 522 ← 只有我的有问题

别人的项目 200,我的 522 —— 到这里就能确定:不是网络,是我的项目后面没有东西。

顺便提醒:用第三方在线代理(codetabs、allorigins 之类)做交叉验证要小心。我第一次用它们时,连 astro.build 都返回 522,说明是代理自身故障,结论完全不可用。对照组永远是拿一个已知正常的同类站点做比较,而不是换个工具再试一次。

修复

进项目 → Settings → Build & deployments → Git repository → Connect to Git,授权 GitHub App 时记得勾选私有仓库(默认不在授权列表里,这是第二常见的卡点)。保存后立刻触发首次构建,Deployments 出现第一条记录,几分钟后站点从 522 变 200。

五、上线验收:用 curl 而不是肉眼

站点能打开不代表部署正确。下面这组检查每次上线都值得跑一遍:

B=https://blog.cospaye.com

# 1. 核心页面状态码
for p in / /posts/ /videos/ /about/ /privacy/ /stats/ /support/; do
  printf '%-12s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' "$B$p")"
done

# 2. 索引条数是否与文章数一致
curl -s "$B/search-index.json" | node -e "
let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{
  const a=JSON.parse(s); console.log('索引条数:', a.length);
})"

# 3. 错误路径必须真 404(而不是 200 + 首页)
curl -s -o /dev/null -w '%{http_code}\n' "$B/nope-xyz"

# 4. 尾斜杠是否规范化
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' "$B/posts"

# 5. 哈希资源是否被永久缓存
curl -sI "$B/_astro/xxx.css" | grep -i cache-control

# 6. HTTP 是否跳 HTTPS
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' "http://blog.cospaye.com/"

本次验收里,第 3 项暴露了一个隐蔽问题。

六、软 404:Pages 最容易被忽略的默认行为

站点刚上线时,我访问一个不存在的路径,返回的是:

HTTP/2 200
content-type: text/html

<title>小渔 - 个人博客</title>    ← 首页的标题

把响应体和首页做字节比对,完全相同。再测一圈:

请求路径 状态 返回内容
/nope-xyz 200 首页
/nope/deep/path 200 首页
/x.css 200 首页(text/html)
/_astro/nonexistent.css 200 首页(text/html)

这就是典型的软 404:Cloudflare Pages 在找不到文件、且构建产物里没有 404.html 时,会把所有未匹配请求回退到 index.html 并返回 200。

后果比想象中严重:

  • 搜索引擎会把任意垃圾 URL 当成有效页面收录;
  • 用户点错链接看到的是首页,而不是“页面不存在”;
  • 监控、日志、外链检查全部失真 —— 因为所有路径都“成功”。

修复:在 src/pages/404.astro 建一个 404 页面,Astro 会输出 dist/404.html,Pages 检测到它之后才会对未匹配路径返回真正的 404。

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="页面未找到" description="你访问的页面不存在。" noindex>
  <div class="text-6xl font-black text-blue-500">404</div>
  <h1>页面走丢了</h1>
  <a href="/">返回首页</a>
</BaseLayout>

修复后 curl -o /dev/null -w '%{http_code}' $B/nope 输出 404,问题收敛。

补充一个细节:/404.html 本身会被 Pages 规范化成 308 跳到 /404,这是正常行为,不影响错误页生效。

七、缓存头:让哈希资源真正“永久”缓存

Astro 输出的资源文件名自带内容指纹,例如:

/_astro/BaseLayout.BFeXUTt2.css

文件内容一变,文件名就变,所以这类资源可以安全地永久缓存。但 Pages 的默认响应头是:

cache-control: public, max-age=0, must-revalidate

意思是每次访问都要回源验证一遍。正确做法是在 public/_headers 里覆盖:

# 带内容指纹的构建产物,可安全永久缓存
/_astro/*
  Cache-Control: public, max-age=31536000, immutable

# RSS 更新频率适中
/rss.xml
  Content-Type: application/rss+xml; charset=utf-8
  Cache-Control: public, max-age=600

# 文章图片:文件名基本不变,适度缓存
/images/*
  Cache-Control: public, max-age=2592000

public/_headers 会被构建复制到 dist/_headers,由 Pages 读取,不会作为静态文件对外提供。生效后验证:

curl -sI https://blog.cospaye.com/_astro/xxx.css | grep -i cache-control
# cache-control: public, max-age=31536000, immutable

八、内链尾斜杠:省掉一次 308 往返

Astro 默认把页面输出为 目录/index.html,所以规范 URL 是带尾斜杠的 /posts/foo/。如果站内链接写成 /posts/foo,每次点击都会先吃一个 308:

/posts/foo -> 308 -> /posts/foo/

单次影响很小,但这是每一次站内跳转都多一次往返。修复方式是把链接统一补上尾斜杠,改完后:

curl -s https://blog.cospaye.com/posts/ | grep -oE 'href="/posts/[^"]*"' | head -3
# href="/posts/20250114-mac-hidpi/"

九、绑定自定义域

Pages 项目 → Custom domains → Set up a custom domain → 填入子域。

因为主域已托管在 Cloudflare,系统会自动建 CNAME 记录并签发证书,通常 1–5 分钟生效。两个常见故障:

  • 该子域已存在 A/CNAME 记录(比如指向旧服务器)→ 到 DNS 记录里删掉冲突记录再重试;
  • 状态长时间 Initializing → 用 dig 确认解析是否已经指到 Pages,再等证书签发。

十、回滚:这个方案最大的安全网

Pages 项目 → Deployments → 选中上一个成功版本 → Rollback to this deployment。

接管时间几十秒,不需要重新构建。这条路径值得在上线前就记牢 —— 一旦新版本出问题,它比“回滚代码再等构建”快一个数量级。

十一、日常发布流程与一个遗留限制

日常只需要:

# 写文章:src/content/posts/*.md
git add . && git commit -m "post: 新文章" && git push
# 1~2 分钟后自动构建完成

免费额度下,Pages 提供每月 500 次构建、1 个并发构建,对个人博客完全够用。

但有一个限制需要提前知道:如果站点接了 AI 检索(本站的聊天助手),索引更新无法随 Pages 构建一起完成。本站的索引脚本是本地运行的:

pnpm index:blog

而且脚本里硬编码了本地代理地址,在 CI 环境里跑不通。所以完整流程其实是:写文章 → push 触发构建 → 本地再跑一次索引。这是后续要改造的部分(改成 Worker 侧定时索引),本文按下不表。

十二、故障排查速查表

现象 原因 处理
访问 522,Deployments 为空 项目是 Direct Upload 建的,从未接仓库 Settings → Connect to Git;或删项目重建
仓库列表里看不到项目 GitHub App 未授权该私有库 GitHub → Settings → Applications → Cloudflare Pages → Configure → 勾选仓库
Unknown field allowBuilds 镜像 pnpm 版本过低 加 PNPM_VERSION=12.15.0
Ignored build scripts: esbuild 且构建失败 构建脚本被跳过 降级 PNPM_VERSION=10.11.1 + 在 package.json 用 pnpm.onlyBuiltDependencies
构建成功但首页 404 输出目录填错 Build output directory 必须是 dist
构建成功但文章数为 0 某篇 frontmatter 缺 title/description/pubDate 看构建日志的 schema 报错
任意路径都返回 200 + 首页 缺 404.html(软 404) 加 src/pages/404.astro
自定义域一直 Initializing 存在冲突的旧 DNS 记录 删除后重试,dig 验证
git push 报 Permission denied (publickey) SSH 公钥未加到 GitHub ssh -T [email protected] 复测

结语

回头看,这次迁移的技术难度不高,真正花时间的是两件“看不见”的事:

  1. 确认站点真的变好了 —— 用 curl 检查状态码、索引条数、缓存头,而不是“页面能打开就算成功”;
  2. 把 522 这种模糊错误拆成可判定的证据链 —— DNS、边缘、出口、对照组,逐层排除。

最终的架构也很朴素:纯静态产物 + Git 集成 + 一个 404 页 + 一份 _headers。没有 adapter,没有密钥,没有 Worker 代码。将来若要换成 Workers 静态资源,也只需要补一个 wrangler.jsonc,迁移成本几乎为零 —— 这大概就是“把简单做到位”的价值。

感谢阅读与支持

如果本文对您有所启发或帮助,欢迎点赞鼓励或请博主喝杯咖啡!

☕支持
延伸阅读全部文章→