Cloudflare Pages 部署指南
这页适合作为“静态站点与前端项目上线入口”。Cloudflare Pages 的优势不只是部署快，而是 Git 集成、预览环境、边缘网络和自定义域名可以一套接起来。
适合什么项目
更适合放到 Pages 的场景：
- Nuxt、Vite、Astro 这类前端或静态站点
- 文档站、博客、导航站、营销页
- 需要 PR 预览链接的前端项目
- 想把静态资源和简单边缘函数一起托管
如果项目主要是复杂服务端逻辑、长连接、大量后台任务，更适合把 Pages 和 Workers / 其他后端服务拆开部署。
创建项目
通过 Git 连接
- 登录 Cloudflare Dashboard
- Workers & Pages → Create → Pages → Connect to Git
- 选择仓库，配置构建设置
构建配置
| 框架 | 构建命令 | 输出目录 |
|---|---|---|
| Nuxt | npx nuxi build | dist |
| Next.js | npm run build | .next |
| Vite | npm run build | dist |
| Astro | npm run build | dist |
Wrangler CLI 部署
# 安装
pnpm add -D wrangler
# 登录
npx wrangler login
# 部署
npx wrangler pages deploy dist --project-name=my-project
wrangler.jsonc 配置
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-project",
"pages_build_output_dir": "dist",
"compatibility_date": "2025-07-15",
"compatibility_flags": ["nodejs_compat"],
}
推荐发布顺序
比较稳的部署顺序通常是：
- 先在本地把构建命令跑通
- 再确认输出目录和
wrangler配置一致 - 再接 Git 自动部署
- 再配置环境变量、域名和缓存头
- 最后才补 Functions、D1、KV、R2 等边缘能力
先让“纯静态构建可稳定上线”，后面扩功能会轻松很多。
自定义域名
- Pages 项目 → Custom domains → Set up a custom domain
- 输入域名（如
example.com） - Cloudflare 自动配置 DNS 和 SSL
多域名
可以绑定多个域名，包括 www 和裸域。
环境变量
Dashboard → Pages 项目 → Settings → Environment variables
# 生产环境
NODE_VERSION=22
NUXT_PUBLIC_SITE_URL=https://example.com
# 预览环境（可单独配置）
NUXT_PUBLIC_SITE_URL=https://preview.example.com
也可以在 wrangler.jsonc 中配置：
{
"vars": {
"ENVIRONMENT": "production",
},
}
预览环境和生产环境建议分开配置，特别是 API 地址、鉴权回调域名、第三方统计和实验性开关。
重定向
public/_redirects：
/old-page /new-page 301
/blog/* /docs/:splat 301
/github https://github.com/user 302
Headers
public/_headers：
/*
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
/assets/*
Cache-Control: public, max-age=31536000, immutable
Pages Functions
在 functions/ 目录下创建 API 端点：
// functions/api/hello.ts
export const onRequestGet: PagesFunction = async (context) => {
return new Response(JSON.stringify({ message: "Hello" }), {
headers: { "Content-Type": "application/json" },
});
};
访问 /api/hello 即可调用。
当前项目这类 Nuxt 站点的注意点
Nuxt / Nitro 项目接入 Pages 时，最容易出问题的通常是：
- 输出目录写错
- 本地和云端使用了不同包管理器或锁文件
- Node 版本与依赖树不匹配
- 环境变量只配了本地，没有配 Preview / Production
部署前建议至少本地确认一次：
bun run build
如果云端构建环境实际使用 npm install，就要特别注意依赖版本是否能被 npm 正常解析。
构建缓存
Cloudflare Pages 支持构建缓存加速：
# package.json
{
"scripts": {
"build": "nuxi build",
"deploy": "wrangler pages deploy dist"
}
}
预览部署
每个 PR / 非主分支推送都会生成预览 URL：
https://<commit-hash>.my-project.pages.dev
限制
- 单次部署最大 25,000 个文件
- 单个文件最大 25 MB
- 每月免费 500 次构建
- Functions 免费版每天 100,000 次请求
常见问题
本地能构建，Pages 上构建失败
优先排查：
- Node 版本是否一致
- 构建命令和输出目录是否配置正确
- 锁文件是否和包管理器匹配
- 是否存在 peer dependency 冲突
部署成功但页面空白
这通常与静态资源路径、SPA 回退、环境变量或客户端运行时报错有关。优先检查：
- 浏览器控制台
- 资源请求是否 404
_redirects是否缺少 SPA fallback
自定义域名迟迟不生效
先检查：
- 域名是否已接入 Cloudflare
- DNS 是否已正确解析
- 是否给了足够传播时间
- SSL 状态是否还在签发中
风险提醒
- Preview 和 Production 的变量不要混用
- 不要把私密密钥直接放进前端公开变量
- 重定向和缓存头上线前最好先用预览域名验证一遍
延伸阅读
参考链接
- Cloudflare Pages 文档 — 官方文档
- Wrangler CLI — CLI 工具
- Pages Functions — 无服务器函数