把 Astro 部署到 Cloudflare Pages 的几个坑

Astro 输出的 dist/ 是一个纯静态目录，正好是 Cloudflare Pages 想要的东西。理论上整个部署只需要填三个字段，实际上第一次尝试时总有几个地方会绊住人。

三个字段

在 Cloudflare Pages 的创建向导里：

字段	值
Framework preset	Astro
Build command	npm run build
Build output directory	dist

安装命令保持默认的 npm install。只有在你已经提交了 lockfile 时才改用 npm ci——而 lockfile 本来就该提交。

Node 版本的陷阱

这是最常出问题的地方。Cloudflare 默认的构建镜像带的 Node 版本偏旧，而新版 Astro 要求 Node 20+。症状是构建日志在某个依赖深处的语法错误处挂掉，看上去跟版本问题毫无关系。

解决办法是给 Pages 项目加一个环境变量：

NODE_VERSION = 22

在 Settings → Environment variables 里为生产环境和预览环境都设上。仓库里再放一个 .nvmrc，作为本地开发的第二道保险。

部署前先设置 site

Astro 需要一个绝对域名才能生成 sitemap.xml 和 canonical 链接。缺了 site，构建只会警告一下，然后你的 sitemap 里全是相对路径，搜索引擎直接忽略。

// astro.config.mjs
export default defineConfig({
  site: 'https://your-domain.com',
  output: 'static',
});

绑定自定义域名之后记得改这里再重新部署。canonical 地址过期是个缓慢又安静的 SEO 问题。

静态输出不需要 adapter

如果看到文档让你装 @astrojs/cloudflare，先确认你到底要不要 SSR。做博客不需要。output: 'static' 不需要任何 adapter，构建更快，而且可以放到任何地方托管。

只有当你有明确理由时才上 SSR——需要登录的页面、按请求个性化、表单要写入存储。

缓存头

Cloudflare 本身就会激进地缓存静态资源。想自己控制的话，在 public/ 放一个 _headers 文件：

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

/*.html
  Cache-Control: public, max-age=0, must-revalidate

带版本号的静态资源长缓存，HTML 不缓存，这样改动能立刻生效。

预览部署

每个分支和 Pull Request 都会自动获得独立 URL。用起来，它不花什么成本，而且能避免你从读者口中得知「线上构建挂了」。