把 Astro 博客迁到 Cloudflare Pages:一次踩坑完整的部署复盘
文章目录
这个博客最终跑在 https://blog.cospaye.com,托管在 Cloudflare Pages 上,推送即部署。
迁移本身并不难,难的是那些文档里不会写、但一定会让你卡住的地方:建项目时点错一个入口,你会得到一个访问就报 522 的空壳站;不加 404 页,你所有的错误链接都会静默地返回 200 和一份首页副本。这篇复盘按真实操作顺序记录全过程,包括踩过的坑和最终的验证方法。
一、先回答一个问题:你的 Astro 站到底需不需要 SSR
Cloudflare 上部署 Astro 有两条完全不同的路:
- 纯静态:构建出 HTML 扔到边缘,不需要 adapter;
- 按需渲染(SSR):需要
@astrojs/cloudflareadapter,生成一个 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] 复测 |
结语
回头看,这次迁移的技术难度不高,真正花时间的是两件“看不见”的事:
- 确认站点真的变好了 —— 用 curl 检查状态码、索引条数、缓存头,而不是“页面能打开就算成功”;
- 把 522 这种模糊错误拆成可判定的证据链 —— DNS、边缘、出口、对照组,逐层排除。
最终的架构也很朴素:纯静态产物 + Git 集成 + 一个 404 页 + 一份 _headers。没有 adapter,没有密钥,没有 Worker 代码。将来若要换成 Workers 静态资源,也只需要补一个 wrangler.jsonc,迁移成本几乎为零 —— 这大概就是“把简单做到位”的价值。
如果本文对您有所启发或帮助,欢迎点赞鼓励或请博主喝杯咖啡!