Pages 入门：把静态站交给全球网络
读完这篇你能做到：把一份静态站点交给 Cloudflare Pages，拿到一个可以直接访问的 *.pages.dev 域名，并且清楚每次 git push 之后平台上发生了哪几件事。整个过程不需要买服务器，也不需要先配 DNS。
前置条件只有三样：一个能构建出静态产物的项目（Vite、Astro、Hugo、纯 HTML 都行）、一个 GitHub 或 GitLab 仓库（只想上传本地产物的话可以跳过）、以及一个 Cloudflare 账号。选型还没定的，先看 52-workers-vs-pages.md，那里用三个问题区分了 Pages 和 Workers。
1. Pages 实际做的三件事
把站点交给 Pages 之后，平台做的是固定的一套动作：
- 拉取代码，在云端容器里执行你填写的构建命令，例如
npm run build。单次构建超过 20 分钟会被终止。 - 把构建输出目录（
dist、public、out之类）里的文件逐个上传到边缘网络。 - 每次部署分配一个独立 URL，最新一次部署接管生产域名。
静态文件的请求不进入 Workers 的请求计数，这是 Pages 免费档最实用的一点。只有当你往项目里加了 Functions，请求才会开始计入 Workers 额度，细节见 68-pages-functions.md。
2. 走 Git 集成
控制台路径：登录后进入 Workers & Pages，点 Create application，切到 Pages 标签，选 Connect to Git。
- 授权 GitHub 或 GitLab，选中目标仓库。私有仓库同样可以接。
- 选择框架预设。选对了预设，构建命令和输出目录会自动填好；选 None 则自己填。
- 确认构建命令与输出目录。Vite 是
npm run build加dist，Hugo 是hugo加public，纯静态仓库两项都留空。 - 展开环境变量，需要固定 Node 版本时加
NODE_VERSION，例如20。 - 点 Save and Deploy，等第一次构建跑完。
首次构建通常一到三分钟。构建日志是实时的，失败时它会停在出错的那一行，这和本地跑同样的命令得到的报错基本一致。
之后每次推送到生产分支都会触发一次构建并更新生产环境；推送到其他分支会生成预览部署，地址形如 <commit>.<project>.pages.dev，这部分在 69-pages-custom-domain-preview.md 里展开。
3. 走直接上传
本地已经构建好、或者代码不在 Git 托管平台上时，用命令行直接推产物：
npm run build
npx wrangler pages deploy ./dist --project-name=my-site这条路径不会在云端执行构建，上传什么就是什么，因此构建环境的差异不会影响结果。CI 里也常用这种方式，把构建交给自己的流水线，Pages 只负责托管。
wrangler pages deploy 会复用或新建项目，第一次跑会要求确认项目名。产物目录里的 _headers、_redirects、_routes.json 会被一并识别，这三个文件后面几篇会分别讲到。
4. 部署完成后该看的四个地方
| 位置 | 作用 |
|---|---|
<project>.pages.dev | 生产域名，可以直接对外分享 |
| Deployments 列表 | 每次部署的状态、耗时、对应 commit |
| 单个部署详情 | 预览 URL、构建日志、回滚入口 |
| Custom domains | 绑自己的域名，免费档每个项目 100 个 |
回滚不需要重新构建：在部署详情里选一个历史部署，点 Rollback，生产环境就指回那次产物。
5. 免费额度边界
| 项目 | 免费档 |
|---|---|
| 构建次数 | 每月 500 次 |
| 并发构建 | 1 个 |
| 单次构建超时 | 20 分钟 |
| 站点文件数 | 20,000 个 |
| 单文件大小 | 25 MiB |
| 自定义域 | 每项目 100 个 |
| 静态请求 | 不计费 |
两个数字值得记住。500 次构建按月算，一天推十几次也用不完；20,000 个文件对小站完全够，超过这个量通常说明该把图片和视频挪到对象存储。单文件 25 MiB 是硬边界，超过的文件放在 R2，再用子域指过去。
完整额度对照在 56-free-tier-limits-cheatsheet.md。
常见问题
构建成功了但页面 404，怎么查。
先看输出目录填得对不对。多数情况是命令产出了 dist，而配置里写的是 public，于是上传了一个空目录。其次看框架是否把文件放进了子目录，比如 dist/client。
能不能不用 Git，只用 FTP 那样的方式更新。
可以，wrangler pages deploy 就是为这个场景准备的。代价是没有云端构建记录，产物出问题只能在本地复现。
pages.dev 域名能直接当正式站用吗。
技术上可以，但它不适合做长期主域名：搜索引擎收录、品牌、以及后续换域名的迁移成本都要考虑。绑定自有域名的流程在 69-pages-custom-domain-preview.md，域名本身怎么来见 48-get-your-own-domain.md。
小结
Pages 的价值在于把"构建加托管"合成一条流水线：代码进仓库，构建在云端跑，产物分发到边缘，静态请求不计量。第一次部署只要填对构建命令和输出目录两件事，其余都有默认值。
真正需要提前想清楚的是边界：文件数、单文件大小、以及加了 Functions 之后请求开始计费。把这三条记住，后面接自定义域、配缓存、上框架都不会踩坑。
数据来源与检索时间
检索时间 2026-11-10。
| 来源 | URL | 对应数据 |
|---|---|---|
| Pages Limits | https://developers.cloudflare.com/pages/platform/limits/ | 免费档每月 500 次构建、并发 1、构建超时 20 分钟、20,000 文件、单文件 25 MiB、每项目 100 个自定义域 |
| Pages Functions Routing | https://developers.cloudflare.com/pages/functions/routing/ | 纯静态项目请求不限量；加入 Functions 后默认所有请求都会调用 Function |
| Workers 静态资源 | https://developers.cloudflare.com/workers/static-assets/ | assets.directory 与 binding 配置形态，用于对照 Pages 的产物托管方式 |
核验说明
- 文档部分：额度表、构建超时、文件数上限、自定义域数量均来自 2026-11-10 抓取的 Pages Limits 页面，为官方当前值。
- 未执行：本机账号的 Token 没有 Pages 权限，控制台创建项目、连仓库、查看构建日志这些步骤全部未执行，步骤顺序依据官方文档与控制台结构描述。
- 未执行：
wrangler pages deploy未运行，命令形态来自官方文档，未在本机验证输出。 - 本地验证（已执行）：临时目录里放一个
index.html和一份_headers，运行wrangler pages dev . --port 8799（wrangler 4.146.0），本地服务启动成功，GET /返回 200，返回内容与文件一致，日志显示解析到 1 条 header 规则。静态目录托管这条路径在本机确认可用。 - 未执行：真实 Pages 项目的创建、Git 集成、云端构建与部署均未操作，控制台步骤为文档描述。