Cloudflare Pages 免费部署：GitHub 自动发布、无限静态请求与自定义域名

操作步骤

1. 1

   先在本地确认项目能够正常构建

   进入项目目录运行 npm install，再运行 npm run build。构建成功后检查输出目录中是否生成 index.html 和其他静态文件。不要直接把只能在本地开发服务器运行的项目交给 Cloudflare；Pages 需要明确的构建命令和输出目录。

   Astro 默认静态输出通常在 dist 目录。
2. 2

   把代码推送到 GitHub 仓库

   确认 package.json、锁文件、源代码和构建配置已经提交到 GitHub。不要把 node_modules、.env、API Key、数据库密码或 Cloudflare Token 提交到仓库。私有仓库也可以连接，但需要在 GitHub App 安装页面授权 Cloudflare 访问对应仓库。

3. 3

   在 Cloudflare 创建 Pages 项目

   登录 Cloudflare Dashboard，进入 Workers & Pages，点击 Create application，选择 Pages，再选择 Import an existing Git repository。授权 GitHub 后，从列表中选择准备部署的仓库并点击 Begin setup。

   官方入口：[[Workers & Pages|https://dash.cloudflare.com/?to=/:account/workers-and-pages]]
4. 4

   选择正确的生产分支

   把真正用于上线的分支设置为 Production branch。大多数项目使用 main；如果你的正式代码位于 master、production 或其他分支，应在创建时或后续 Settings > Builds > Branch control 中修改。推送到生产分支会更新正式站点，其他允许构建的分支通常生成预览部署。

5. 5

   填写 Astro 的构建配置

   纯静态 Astro 项目填写 Build command 为 npm run build，Build output directory 为 dist。Root directory 通常留空；只有仓库是 Monorepo、项目位于子目录时才填写对应路径。当前 GPT Discount 项目就是 main + npm run build + dist。

   Cloudflare Astro 官方配置：[[Deploy an Astro site|https://developers.cloudflare.com/pages/framework-guides/deploy-an-astro-site/]]
6. 6

   先不要随意添加 SSR Adapter

   纯静态 Astro 站不需要为了部署 Pages 而强制加入 @astrojs/cloudflare。只有项目确实需要服务器端渲染、Pages Functions、请求时读取环境变量或动态 API 时，才应按 Astro 和 Cloudflare 当前适配器文档改造。静态输出更简单，也不会消耗 Functions 请求额度。

7. 7

   保存并执行第一次部署

   点击 Save and Deploy。Cloudflare 会安装依赖、执行构建命令并上传输出目录。成功后会生成一个 project-name.pages.dev 地址。项目名称会成为默认 pages.dev 子域名的一部分，创建前应避免使用临时或难以辨认的名称。

8. 8

   检查部署日志而不是只看页面错误

   构建失败时打开 Deployments，选择失败记录并查看完整日志。常见问题包括 Node 版本不兼容、缺少锁文件、依赖安装失败、输出目录写错、环境变量缺失、文件名大小写在 Windows 和 Linux 上不一致，以及构建超过 20 分钟。

9. 9

   确认 GitHub 推送会自动上线

   Cloudflare Pages GitHub Integration 会在仓库分支出现新提交时自动构建。推送到 main 后应在 Deployments 中看到对应 Commit SHA；成功后 Production 部署会指向最新提交。GitHub 没有 Actions 工作流并不影响 Pages 自动部署，因为构建由 Cloudflare 执行。

   官方说明：[[GitHub integration|https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/]]
10. 10

    使用分支和 Pull Request 预览

    非生产分支可生成独立预览地址，Pull Request 也可以自动获得持续更新的 Preview URL。合并前先用预览地址检查移动端、链接、图片和构建结果，再合并到 main。Cloudflare 当前说明，从 Fork 创建的 Pull Request 不会生成预览 URL。

11. 11

    需要时用提交信息跳过构建

    只修改 README、内部说明或其他不影响站点的文件时，可以在提交信息开头使用 [CI Skip]、[Skip CI] 或 [CF-Pages-Skip]，让 Pages 跳过该次部署。不要对实际文章或代码更新使用跳过标记，否则线上不会更新。

12. 12

    绑定自定义域名前先在 Pages 中添加域名

    进入 Pages 项目 > Custom domains > Set up a domain，先输入需要绑定的域名并继续。不要只在 DNS 控制台手动建立一个指向 pages.dev 的 CNAME；Cloudflare 官方说明，如果没有先在 Pages 项目中关联域名，可能出现 522。

    官方流程：[[Custom domains|https://developers.cloudflare.com/pages/configuration/custom-domains/]]
13. 13

    根域名和子域名使用不同方式

    绑定 example.com 这类根域名时，域名必须作为同一 Cloudflare 账号中的 Zone，并把 Nameserver 指向 Cloudflare。绑定 www.example.com、docs.example.com 等子域名时，可以使用外部 DNS；在 Pages 添加域名后，再创建 CNAME 指向 project-name.pages.dev。

14. 14

    等待 HTTPS 证书和 DNS 激活

    域名添加后等待状态变为 Active，再访问 HTTPS 地址。长时间卡住时检查 DNS 是否存在冲突记录、Nameserver 是否已经切换、CAA 是否允许 Cloudflare 签发证书，以及是否同时配置了错误的 A、AAAA 或 CNAME。

15. 15

    理解 Free 计划的构建和文件边界

    Cloudflare Pages Free 当前每月提供 500 次构建，只允许 1 个构建同时进行，单次构建最长 20 分钟。每个站点最多 20,000 个文件，单个静态文件最大 25 MiB；大视频、安装包和超大图片应改用 R2 或其他对象存储。

16. 16

    区分静态请求和 Pages Functions

    HTML、CSS、JS、图片等静态资源请求在免费和付费计划中都免费且不限量，只要请求没有触发 Functions。Pages Functions 属于 Workers 计算，Free 计划下与其他 Workers 共享每日 100,000 次请求额度，并在每天 UTC 0 点重置。

17. 17

    把密钥配置为环境变量

    进入项目 Settings > Environment variables，为 Production 和 Preview 分别配置需要的变量。公开的 Astro PUBLIC_ 变量会进入前端包，不能存放秘密；真正的密钥只应提供给服务端 Functions，并且不要写进 Markdown、Git 历史或前端 JavaScript。

18. 18

    上线后检查 404、重定向和缓存

    逐个检查首页、文章详情、带尾斜杠的路径、自定义域名和 pages.dev 地址。Astro 静态站需要确保输出目录中真实存在目标页面；需要重定向或自定义响应头时，可在 public 目录维护 _redirects 和 _headers，构建后它们会进入 dist。