cloudflare-pages

用途：Cloudflare Pages 用于部署前端项目，提供预览构建、边缘函数和全球 CDN 分发。适用场景包括部署静态站点（React、Vue、Astro、Hugo、Next.js 静态导出）、使用 Pages Functions 构建全栈应用、需要每个拉取请求自动预览部署的项目、希望零配置 CDN 加自定义域名与 TLS 的团队，以及从 Vercel、Netlify 或 GitHub Pages 迁移的项目。\n\n前置条件：本地需 Node.js 18+ 与 npm；Cloudflare 账户（多数项目免费层可用）；安装 Wrangler CLI（npm install -g wrangler）；通过 wrangler login 或 CLOUDFLARE_API_TOKEN 环境变量认证；源代码存放在 GitHub 或 GitLab 仓库中以使用面板集成。资料提醒需固定受支持的 Wrangler/Node 版本，框架适配器与平台限制会变化；全栈 Next.js 需采用当前受支持的 Workers/OpenNext 流程，而非默认沿用旧的 next-on-pages 适配器；部署、删除或变更域名前应确认账户、项目与环境，预览可能暴露私有构建，需要访问控制。\n\n项目设置：可用 npx wrangler pages project create my-site 创建项目，project list 列出项目，project delete 删除项目及全部部署。本地构建后执行 npx wrangler pages deploy dist --project-name=my-site 部署输出目录，加 --branch 参数可触发预览 URL；deployment list 查看部署，deployment tail 跟踪日志。也可在面板 Workers & Pages 中连接 GitHub/GitLab，配置生产分支、构建命令与输出目录，并按环境设置变量。资料给出各框架的构建命令与输出目录对照（React CRA 输出 build、Vite 输出 dist、Next.js 静态导出输出 out、Astro 输出 dist、Hugo 输出 public、SvelteKit 输出 .svelte-kit/cloudflare）。\n\n预览部署：每个非生产分支自动获得唯一预览 URL，格式为 <commit-hash>.<project-name>.pages.dev 或 <branch-name>.<project-name>.pages.dev。可在 wrangler.toml 或面板中配置分支包含/排除规则，启用 GitHub App 在 PR 中评论部署 URL。\n\nPages Functions：在项目根目录 functions/ 下放置文件即可提供与静态站点一同部署的服务端逻辑，支持 onRequestGet 等处理函数、[id] 动态路由参数、_middleware.ts 中间件，以及 KV、D1、R2 绑定。资料强调 _headers 只对静态资源生效，Functions 响应的安全与 CORS 头需在函数内设置并按需实现 OPTIONS；私有数据场景下绑定与缓存键需按授权用户/租户隔离，示例中的共享键仅适用于公开数据。\n\n配置与域名：wrangler.toml 可声明 name、compatibility_date、pages_build_output_dir 以及 KV、D1、R2 绑定和 [vars] 环境变量。public/_headers 设置缓存与安全响应头，public/_redirects 配置重定向规则。自定义域名可通过面板设置，也可用 Cloudflare API 添加。\n\nCI/CD：资料给出 GitHub Actions 工作流示例，使用 cloudflare/wrangler-action@v3 执行 pages deploy，并提示该示例需要可信分支的密钥边界和明确的预览分支，不要用生产凭据部署不受信任的 PR 构建。\n\n限制与注意事项：基础设施命令可能中断服务，执行变更前应确认目标并准备备份；构建内存不足需检查平台限制与日志；Functions 返回 404 通常是 functions/ 目录不在仓库根目录；预览显示旧内容可硬刷新并核对部署列表；自定义域名 SSL 报错需先核实域名状态与 DNS 要求；_headers 被忽略通常是文件未放入构建输出目录；绑定未定义需检查 wrangler.toml 或面板配置；函数体积超限需检查包体与官方限制。资料还说明本条目为文档导入，上游脚本与模板未随附。