Cloudflare Pages 部署 Astro：GitHub 自动构建完整教程

Cloudflare Pages 适合托管 Astro 生成的静态网站：代码提交到 GitHub 后，Pages 自动安装依赖、执行构建并发布 dist 目录。部署本身不复杂，真正容易出错的是 Node 版本、项目根目录、构建命令和输出目录不一致。

一、部署前检查

在本地项目目录运行 npm install 和 npm run build。确认构建完成后存在 dist/index.html，并检查文章、分类和工具详情等静态路由是否生成。如果本地构建失败，不要先去 Cloudflare 反复重试。

把代码提交到 GitHub，确保 package.json、锁文件、astro.config.mjs 和内容文件都在仓库中。不要提交 node_modules 与本地环境变量。

二、Pages 构建配置

在 Cloudflare 控制台选择 Workers & Pages，创建 Pages 项目并连接 GitHub 仓库。常见配置如下：

配置项	Astro 静态站常用值	说明
Framework preset	Astro 或 None	预设仅帮助填默认值
Build command	npm run build	对应 package.json 脚本
Build output directory	dist	Astro 默认输出目录
Root directory	留空或子目录	单仓库多项目时填写
Production branch	main	按仓库实际分支选择

如果构建脚本还会执行 Pagefind 等后处理命令，要确保依赖写入 package.json，不能依赖本机全局安装。

三、固定 Node 版本

本地与 Cloudflare 使用不同 Node 版本时，容易出现“本地成功、云端失败”。可以在项目配置或 Cloudflare 环境变量中明确 Node 版本，并选择依赖支持的版本。更新 Astro 后，也要同步检查 Node 最低版本要求。

构建日志出现 engine、module、lockfile 或 native dependency 错误时，先核对运行时版本与锁文件，不要直接删除所有配置。

四、连接自定义域名

首次部署会获得 pages.dev 地址。验证页面正常后，在项目的 Custom domains 中添加正式域名。若域名也托管在 Cloudflare，系统通常会协助创建 DNS 记录；外部 DNS 则需要按提示添加记录。

站点配置中的 site 应改成正式 HTTPS 域名，用于生成 Canonical、Sitemap 和分享链接。上线后检查 HTTP 是否跳转 HTTPS、www 与根域是否统一，以及页面源代码中的 Canonical 是否指向最终域名。

五、常见故障排查

构建命令不存在

检查 package.json 是否包含 "build": "astro build" 或项目实际脚本。Cloudflare 输入框只负责调用脚本，不会自动创建它。

找不到 dist

确认构建确实执行成功，输出目录与 Astro 配置一致。不要把 /dist、仓库路径或 public 误填为输出目录。

页面 404

检查路径是否在构建时生成、文件名大小写是否一致、动态路由是否实现 getStaticPaths()。静态部署无法在请求时临时生成未构建页面。

环境变量缺失

本地 .env 不会自动上传。在 Pages 项目的变量设置中分别配置 Production 与 Preview。不要把密钥写进前端可访问代码。

部署后样式丢失

检查资源路径、站点 base 配置和浏览器网络请求。静态资源返回 404 时，优先确认构建产物中的路径，而不是修改 DNS。

六、上线后的 SEO 检查

确认 robots.txt 可访问、Sitemap 使用正式域名、重点页面有唯一 Canonical。把 Sitemap 提交到 Search Console，并使用网址检查工具查看首页和核心教程。部署成功只表示文件可访问，不表示 Google 已收录。

每次发布后抽查首页、分类、文章、404、移动端导航和搜索。若添加 Pagefind，应确认构建后生成 /pagefind/ 资源并可正常搜索。

结论

稳定部署依赖四个一致：本地和云端 Node 版本一致、构建命令与 package.json 一致、输出目录与 Astro 配置一致、站点域名与 SEO 配置一致。先在本地得到可验证的静态产物，再连接 GitHub 自动部署，排错会清晰很多。