Skip to content
返回部署

Cloudflare Pages 部署指南

在 Cloudflare 全球边缘网络上进行 Git 连接的静态与 SSR 部署，支持 Workers 与 Functions。

边缘入门

为什么

Cloudflare Pages 从 300+ 边缘位置提供静态资源和 SSR，无冷启动，免费计划含无限带宽。Workers 集成实现边缘逻辑（鉴权、A/B 测试、地理路由），0ms 冷启动，区别于其他平台的 serverless 函数。

Cloudflare 边缘网络覆盖 330+ 城市，全球 p95 延迟低于 50ms。边缘函数相比源服务器将 TTFB 降低 60-80%，Akamai 报告 2024 年 40% 的企业使用边缘计算。

何时使用

静态站、Astro/Next.js SSR、边缘密集应用（地理路由、边缘鉴权）和成本敏感需免费无限带宽的项目选 Cloudflare Pages。需要长时运行进程或重计算时避免（用 Fly.io 或 VPS）。

如何做

1. 连接仓库 — dash.cloudflare.com → Pages → 创建 → 连接 GitHub/GitLab 2. 设置构建 — 框架预设（Astro/Next）自动检测，或手动设构建命令 + 输出目录 3. 环境变量 — 面板设置，NODE_VERSION=20 固定运行时 4. 预览部署 — 每个 PR 自动获得 <branch>.<project>.pages.dev URL 5. 生产 — 推送到 main（或配置分支），部署原子化，可即时回滚 6. Functions — /functions 目录，每个文件成为边缘端点（如 /functions/api/geo.ts） 7. 自定义域名 — 添加 CNAME 到 <project>.pages.dev，Cloudflare 自动管理 TLS 8. Wrangler CLI — npx wrangler pages deploy ./dist 用于手动部署或 git 集成外的 CI

示例

// functions/api/geo.ts — 边缘函数（运行于 Cloudflare Workers 运行时） export const onRequest: PagesFunction = async (context) => { const country = context.request.cf?.country || "unknown"; const city = context.request.cf?.city || "unknown"; return Response.json({ country, city, message: `从靠近 ${city}，${country} 的边缘服务`, timestamp: Date.now(), }); }; // _routes.json — 控制哪些路径运行 Functions vs 静态 { "version": 1, "include": ["/api/*"], "exclude": ["/api/static/*"] } // wrangler.toml — 高级配置 + 绑定 name = "my-pages-app" compatibility_date = "2024-09-01" pages_build_output_dir = "./dist" [[d1_databases]] binding = "DB" database_name = "my-db" database_id = "abc-123" # 通过 CLI 部署（如从 GitHub Actions） # npx wrangler pages deploy ./dist --project-name=my-app --branch=main

常见问题

  • ⚠构建报 'wrangler not found' — Pages 面板需 wrangler 在 devDependencies，非全局
  • ⚠Functions 30s 超时 — 边缘 CPU 限制，长任务移到 Durable Object 或外部服务
  • ⚠D1 数据库未绑定 — wrangler.toml 绑定名与代码中 env.DB 引用不匹配
  • ⚠自定义域名显示 'pending' — DNS 传播最多 24h，或 CNAME 指向错误目标

最佳实践

  • ✓固定 @cloudflare/workers-types 和 wrangler 版本 — 边缘运行时 API 跨版本变化
  • ✓用 _routes.json 将 Functions 限于 /api/* — 静态资源无函数调用更快
  • ✓wrangler.toml 设 compatibility_date — 可预测地启用稳定运行时特性
  • ✓用 D1/KV/R2 绑定存状态 — 边缘函数无状态，持久化需绑定

常见问题解答

Cloudflare Pages 和 Vercel 有什么不同？

Pages 运行在 Cloudflare 边缘网络（300+ 城市）无冷启动，Vercel 默认单区域。Pages 静态站无限免费；Vercel 超免费层按带宽收费。

Pages 上能用服务端渲染吗？

能，通过 Pages Functions（Workers）——加 functions/ 文件夹按需路由。边缘运行 50ms CPU 限制。重 SSR 用 Node.js 框架在其他平台。

为什么构建报 wrangler not found？

Pages 用自己的构建环境——将 wrangler 装为 devDependency，构建命令设 npx wrangler pages deploy。框架预设（Next.js、Astro）在面板选择预设。

如何在 Pages 设自定义域名？

Pages 面板添加域名，再加 CNAME 记录指向 your-pages-project.pages.dev。Cloudflare 托管域名自动。DNS 传播在 Cloudflare 网络上不到 60 秒。

如何部署 monorepo 到 Pages？

Pages 面板设根目录为应用文件夹。Pages 只构建该目录。Turborepo 用 npx turbo run build --filter=<app> 作构建命令。