Cloudflare 全栈部署指南

Cloudflare 是全球最大的边缘网络平台，拥有遍布 300+ 城市的数据中心。除了传统的 CDN 和 DNS 服务，Cloudflare 现已发展成一个完整的全栈开发平台，提供静态托管（Pages）、边缘函数（Workers）、数据库（D1）、对象存储（R2）等服务，且免费额度相当充足。

为什么选择 Cloudflare

特性	说明
免费额度	Pages/Workers/KV/R2 均有慷慨免费额度
全球网络	300+ 数据中心，国内访问速度优秀
全栈能力	静态托管 + 边缘函数 + 数据库 + 对象存储
Git 集成	GitHub/GitLab 自动部署
边缘优先	代码运行在离用户最近的节点，延迟极低
安全防护	内置 DDoS 防护、WAF、Bot 管理

Cloudflare Pages

Pages 是 Cloudflare 的静态网站托管服务，类似 Vercel 和 Netlify，支持主流前端框架的自动化部署。

连接 Git 仓库

登录 Cloudflare Dashboard
进入 Workers & Pages，点击 Create，选择 Pages
选择 Connect to Git
授权 GitHub 或 GitLab
选择仓库，点击 Begin setup

支持的框架

Pages 对以下框架提供预设配置：

前端框架：
- Next.js / Nuxt / Astro
- React / Vue / Svelte / SolidJS
- Angular / Remix / Qwik

静态生成：
- Vite / Create React App
- Gatsby / Hugo / Jekyll
- Docusaurus / VitePress

构建配置

配置项	说明
Framework preset	框架类型（自动检测）
Build command	构建命令，如 `npm run build`
Build output	输出目录，如 `dist`、`.next`
Root directory	项目根目录（Monorepo 场景）
Environment variables	环境变量

预览部署

每个 Pull Request 会自动生成预览链接：

https://<commit-hash>.<project>.pages.dev

主分支部署到生产域名：

https://<project>.pages.dev

Pages Functions

在 functions/ 目录下创建文件即可定义 API 路由：

项目结构：
├── functions/
│   ├── api/
│   │   └── hello.js      → /api/hello
│   └── [[path]].js       → 捕获所有路由
├── dist/                  → 静态资源
└── ...

export async function onRequest(context) {
  return new Response(JSON.stringify({ message: 'Hello World' }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

自定义域名与 DNS

Cloudflare 的 DNS 服务是其核心功能之一，将域名托管到 Cloudflare 可以获得更快的解析速度和更强的安全防护。

添加域名

Dashboard 点击 Add a site
输入域名（如 example.com）
选择计划（Free 即可）
到域名注册商修改 NS 记录

修改 NS 为 Cloudflare 提供的值：

NS 记录：
- ada.ns.cloudflare.com
- bob.ns.cloudflare.com

DNS 记录配置

常用记录类型：

类型	用途	示例值
A	指向 IPv4 地址	`76.76.21.21`
AAAA	指向 IPv6 地址	`2606:4700::1`
CNAME	指向另一个域名	`project.pages.dev`
TXT	文本记录（验证等）	`v=spf1 include:...`
MX	邮件服务器	`mail.example.com`

Proxy 模式

DNS 记录有两种模式：

模式	图标	说明
Proxied	橙色云	流量经过 Cloudflare CDN
DNS only	灰色云	直接解析，不经过 CDN

开启 Proxy 模式后可获得：

CDN 加速
DDoS 防护
SSL 证书
缓存优化
隐藏源站 IP

SSL/TLS 配置

推荐使用 Full (strict) 模式：

SSL/TLS → Overview → Full (strict)

模式	说明
Off	不使用 HTTPS
Flexible	用户到 CF 加密，CF 到源站不加密
Full	全程加密，但不验证源站证书
Full (strict)	全程加密，验证源站证书（推荐）

绑定 Pages 域名

Pages 项目，点击 Custom domains，选择 Add
输入域名（如 blog.example.com）
Cloudflare 自动添加 CNAME 记录

Cloudflare Workers

Workers 是 Cloudflare 的边缘函数服务，代码运行在全球 300+ 节点，冷启动时间仅毫秒级。

创建 Worker

方式一：Dashboard 创建

Workers & Pages，点击 Create，选择 Worker
在线编辑器中编写代码
Deploy

方式二：wrangler CLI（推荐）

# 安装 wrangler (Node.js >= 16.17.0)
npm install -g wrangler

# 登录
wrangler login

# 创建项目
npm create cloudflare@latest my-worker

# 本地开发
cd my-worker
npm run dev

# 部署
npm run deploy

Worker 示例

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)

    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Hello from Edge!' })
    }

    return new Response('Not Found', { status: 404 })
  },
}

路由配置

在 wrangler.toml 中配置路由：

name = "my-worker"
main = "src/index.js"

# 绑定到自定义域名
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

也可在 Dashboard 手动配置路由规则。

边缘存储服务

Cloudflare 提供多种边缘存储服务，适合不同场景。

Workers KV

全球分布式键值存储，适合读多写少的场景（配置、缓存等）。

创建 KV 命名空间：

wrangler kv namespace create MY_KV

绑定到 Worker：

[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

使用示例：

export default {
  async fetch(request, env) {
    // 写入
    await env.MY_KV.put('key', 'value')

    // 读取
    const value = await env.MY_KV.get('key')

    // 删除
    await env.MY_KV.delete('key')

    return Response.json({ value })
  },
}

免费额度：

读取：100,000 次/天
写入：1,000 次/天
存储：1 GB

D1 数据库

边缘 SQLite 数据库，适合需要关系型数据的应用。

创建数据库：

wrangler d1 create my-database

绑定到 Worker：

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

使用示例：

export default {
  async fetch(request, env) {
    // 执行查询
    const { results } = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
      .bind(1)
      .all()

    // 执行写入
    await env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
      .bind('Alice', 'alice@example.com')
      .run()

    return Response.json({ results })
  },
}

执行 SQL 迁移：

# 创建迁移文件
wrangler d1 migrations create my-database init

# 执行迁移
wrangler d1 migrations apply my-database

免费额度：

读取行数：5,000,000/天
写入行数：100,000/天
存储：5 GB

R2 对象存储

S3 兼容的对象存储，无出口流量费用。

创建存储桶：

wrangler r2 bucket create my-bucket

绑定到 Worker：

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

使用示例：

export default {
  async fetch(request, env) {
    const url = new URL(request.url)
    const key = url.pathname.slice(1)

    if (request.method === 'PUT') {
      await env.BUCKET.put(key, request.body)
      return new Response('Uploaded')
    }

    if (request.method === 'GET') {
      const object = await env.BUCKET.get(key)
      if (!object) return new Response('Not Found', { status: 404 })
      return new Response(object.body)
    }

    return new Response('Method Not Allowed', { status: 405 })
  },
}

免费额度：

存储：10 GB
A 类操作（写入）：1,000,000 次/月
B 类操作（读取）：10,000,000 次/月
出口流量：免费

wrangler.toml 配置

wrangler.toml 是 Worker 项目的配置文件：

name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

# 账户 ID（可选，多账户时需要）
# account_id = "your-account-id"

# 环境变量
[vars]
API_URL = "https://api.example.com"

# 敏感变量（使用 wrangler secret 管理）
# wrangler secret put API_KEY

# KV 存储
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# D1 数据库
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# R2 存储
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

# 定时任务
[triggers]
crons = ["0 * * * *"]  # 每小时执行

多环境配置

name = "my-worker"
main = "src/index.js"

[vars]
ENVIRONMENT = "production"

# 预览/开发环境
[env.preview]
name = "my-worker-preview"
[env.preview.vars]
ENVIRONMENT = "preview"

部署到指定环境：

wrangler deploy --env preview

与其他平台对比

特性	Cloudflare	Vercel	Netlify
静态托管	Pages	内置	内置
边缘函数	Workers	Edge Functions	Edge Functions
函数运行时	V8 isolate	Node.js/Edge	Node.js/Deno
冷启动	毫秒级	较慢	较慢
数据库	D1 内置	需外接	需外接
对象存储	R2 内置	需外接	需外接
键值存储	KV 内置	需外接	需外接
免费额度	非常充足	充足	充足
国内速度	优秀	好	一般
学习曲线	中等	低	低

选择建议：

Next.js 项目且追求开发体验：Vercel
需要边缘数据库、对象存储：Cloudflare
国内访问速度优先：Cloudflare

最佳实践

1. 使用 wrangler 本地开发

# 本地开发服务器
wrangler dev

# 本地开发时连接远程服务（KV/D1/R2）
wrangler dev --remote

2. 环境变量管理

# 查看已有 secrets
wrangler secret list

# 添加敏感变量
wrangler secret put API_KEY

# 批量设置（从 .env 文件）
wrangler secret bulk .env

3. 缓存策略

Pages 默认对静态资源进行缓存，可通过 _headers 文件自定义：

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate

4. Monorepo 部署

Pages 支持指定构建目录：

Root directory: apps/web
Build command: pnpm build
Build output: dist

常见问题

构建失败

检查 Build Logs 定位具体错误
确认 Node.js 版本（Settings 中的 Environment variables，设置 NODE_VERSION）
确认构建命令和输出目录是否正确

域名解析慢

确认 NS 记录已正确修改
等待 DNS 传播（可能需要 24-48 小时）
使用 dig 命令检查：dig example.com NS

Workers 限制

限制项	Free	Paid
请求数/天	100,000	无限
CPU 时间/请求	10ms	30s
Worker 大小	1 MB	10 MB
环境变量	64 个	128 个

504 超时

Workers 免费版 CPU 时间限制为 10ms，超时会返回 504。解决方案：

优化代码减少计算量
升级到 Paid 计划（30s CPU 时间）
将耗时操作拆分为多个请求

参考资料

为什么选择 Cloudflare

特性	说明
免费额度	Pages/Workers/KV/R2 均有慷慨免费额度
全球网络	300+ 数据中心，国内访问速度优秀
全栈能力	静态托管 + 边缘函数 + 数据库 + 对象存储
Git 集成	GitHub/GitLab 自动部署
边缘优先	代码运行在离用户最近的节点，延迟极低
安全防护	内置 DDoS 防护、WAF、Bot 管理

Cloudflare Pages

Pages 是 Cloudflare 的静态网站托管服务，类似 Vercel 和 Netlify，支持主流前端框架的自动化部署。

连接 Git 仓库

登录 Cloudflare Dashboard
进入 Workers & Pages，点击 Create，选择 Pages
选择 Connect to Git
授权 GitHub 或 GitLab
选择仓库，点击 Begin setup

支持的框架

Pages 对以下框架提供预设配置：

前端框架：
- Next.js / Nuxt / Astro
- React / Vue / Svelte / SolidJS
- Angular / Remix / Qwik

静态生成：
- Vite / Create React App
- Gatsby / Hugo / Jekyll
- Docusaurus / VitePress

构建配置

配置项	说明
Framework preset	框架类型（自动检测）
Build command	构建命令，如 `npm run build`
Build output	输出目录，如 `dist`、`.next`
Root directory	项目根目录（Monorepo 场景）
Environment variables	环境变量

预览部署

每个 Pull Request 会自动生成预览链接：

https://<commit-hash>.<project>.pages.dev

主分支部署到生产域名：

https://<project>.pages.dev

Pages Functions

在 functions/ 目录下创建文件即可定义 API 路由：

项目结构：
├── functions/
│   ├── api/
│   │   └── hello.js      → /api/hello
│   └── [[path]].js       → 捕获所有路由
├── dist/                  → 静态资源
└── ...

export async function onRequest(context) {
  return new Response(JSON.stringify({ message: 'Hello World' }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

自定义域名与 DNS

Cloudflare 的 DNS 服务是其核心功能之一，将域名托管到 Cloudflare 可以获得更快的解析速度和更强的安全防护。

添加域名

Dashboard 点击 Add a site
输入域名（如 example.com）
选择计划（Free 即可）
到域名注册商修改 NS 记录

修改 NS 为 Cloudflare 提供的值：

NS 记录：
- ada.ns.cloudflare.com
- bob.ns.cloudflare.com

DNS 记录配置

常用记录类型：

类型	用途	示例值
A	指向 IPv4 地址	`76.76.21.21`
AAAA	指向 IPv6 地址	`2606:4700::1`
CNAME	指向另一个域名	`project.pages.dev`
TXT	文本记录（验证等）	`v=spf1 include:...`
MX	邮件服务器	`mail.example.com`

Proxy 模式

DNS 记录有两种模式：

模式	图标	说明
Proxied	橙色云	流量经过 Cloudflare CDN
DNS only	灰色云	直接解析，不经过 CDN

开启 Proxy 模式后可获得：

CDN 加速
DDoS 防护
SSL 证书
缓存优化
隐藏源站 IP

SSL/TLS 配置

推荐使用 Full (strict) 模式：

SSL/TLS → Overview → Full (strict)

模式	说明
Off	不使用 HTTPS
Flexible	用户到 CF 加密，CF 到源站不加密
Full	全程加密，但不验证源站证书
Full (strict)	全程加密，验证源站证书（推荐）

绑定 Pages 域名

Pages 项目，点击 Custom domains，选择 Add
输入域名（如 blog.example.com）
Cloudflare 自动添加 CNAME 记录

Cloudflare Workers

Workers 是 Cloudflare 的边缘函数服务，代码运行在全球 300+ 节点，冷启动时间仅毫秒级。

创建 Worker

方式一：Dashboard 创建

Workers & Pages，点击 Create，选择 Worker
在线编辑器中编写代码
Deploy

方式二：wrangler CLI（推荐）

# 安装 wrangler (Node.js >= 16.17.0)
npm install -g wrangler

# 登录
wrangler login

# 创建项目
npm create cloudflare@latest my-worker

# 本地开发
cd my-worker
npm run dev

# 部署
npm run deploy

Worker 示例

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)

    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Hello from Edge!' })
    }

    return new Response('Not Found', { status: 404 })
  },
}

路由配置

在 wrangler.toml 中配置路由：

name = "my-worker"
main = "src/index.js"

# 绑定到自定义域名
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

也可在 Dashboard 手动配置路由规则。

边缘存储服务

Cloudflare 提供多种边缘存储服务，适合不同场景。

Workers KV

全球分布式键值存储，适合读多写少的场景（配置、缓存等）。

创建 KV 命名空间：

wrangler kv namespace create MY_KV

绑定到 Worker：

[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

使用示例：

export default {
  async fetch(request, env) {
    // 写入
    await env.MY_KV.put('key', 'value')

    // 读取
    const value = await env.MY_KV.get('key')

    // 删除
    await env.MY_KV.delete('key')

    return Response.json({ value })
  },
}

免费额度：

读取：100,000 次/天
写入：1,000 次/天
存储：1 GB

D1 数据库

边缘 SQLite 数据库，适合需要关系型数据的应用。

创建数据库：

wrangler d1 create my-database

绑定到 Worker：

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

使用示例：

export default {
  async fetch(request, env) {
    // 执行查询
    const { results } = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
      .bind(1)
      .all()

    // 执行写入
    await env.DB.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
      .bind('Alice', 'alice@example.com')
      .run()

    return Response.json({ results })
  },
}

执行 SQL 迁移：

# 创建迁移文件
wrangler d1 migrations create my-database init

# 执行迁移
wrangler d1 migrations apply my-database

免费额度：

读取行数：5,000,000/天
写入行数：100,000/天
存储：5 GB

R2 对象存储

S3 兼容的对象存储，无出口流量费用。

创建存储桶：

wrangler r2 bucket create my-bucket

绑定到 Worker：

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

使用示例：

export default {
  async fetch(request, env) {
    const url = new URL(request.url)
    const key = url.pathname.slice(1)

    if (request.method === 'PUT') {
      await env.BUCKET.put(key, request.body)
      return new Response('Uploaded')
    }

    if (request.method === 'GET') {
      const object = await env.BUCKET.get(key)
      if (!object) return new Response('Not Found', { status: 404 })
      return new Response(object.body)
    }

    return new Response('Method Not Allowed', { status: 405 })
  },
}

免费额度：

存储：10 GB
A 类操作（写入）：1,000,000 次/月
B 类操作（读取）：10,000,000 次/月
出口流量：免费

wrangler.toml 配置

wrangler.toml 是 Worker 项目的配置文件：

name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

# 账户 ID（可选，多账户时需要）
# account_id = "your-account-id"

# 环境变量
[vars]
API_URL = "https://api.example.com"

# 敏感变量（使用 wrangler secret 管理）
# wrangler secret put API_KEY

# KV 存储
[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# D1 数据库
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# R2 存储
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

# 定时任务
[triggers]
crons = ["0 * * * *"]  # 每小时执行

多环境配置

name = "my-worker"
main = "src/index.js"

[vars]
ENVIRONMENT = "production"

# 预览/开发环境
[env.preview]
name = "my-worker-preview"
[env.preview.vars]
ENVIRONMENT = "preview"

部署到指定环境：

wrangler deploy --env preview

与其他平台对比

特性	Cloudflare	Vercel	Netlify
静态托管	Pages	内置	内置
边缘函数	Workers	Edge Functions	Edge Functions
函数运行时	V8 isolate	Node.js/Edge	Node.js/Deno
冷启动	毫秒级	较慢	较慢
数据库	D1 内置	需外接	需外接
对象存储	R2 内置	需外接	需外接
键值存储	KV 内置	需外接	需外接
免费额度	非常充足	充足	充足
国内速度	优秀	好	一般
学习曲线	中等	低	低

选择建议：

Next.js 项目且追求开发体验：Vercel
需要边缘数据库、对象存储：Cloudflare
国内访问速度优先：Cloudflare

最佳实践

1. 使用 wrangler 本地开发

# 本地开发服务器
wrangler dev

# 本地开发时连接远程服务（KV/D1/R2）
wrangler dev --remote

2. 环境变量管理

# 查看已有 secrets
wrangler secret list

# 添加敏感变量
wrangler secret put API_KEY

# 批量设置（从 .env 文件）
wrangler secret bulk .env

3. 缓存策略

Pages 默认对静态资源进行缓存，可通过 _headers 文件自定义：

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate

4. Monorepo 部署

Pages 支持指定构建目录：

Root directory: apps/web
Build command: pnpm build
Build output: dist

常见问题

构建失败

检查 Build Logs 定位具体错误
确认 Node.js 版本（Settings 中的 Environment variables，设置 NODE_VERSION）
确认构建命令和输出目录是否正确

域名解析慢

确认 NS 记录已正确修改
等待 DNS 传播（可能需要 24-48 小时）
使用 dig 命令检查：dig example.com NS

Workers 限制

限制项	Free	Paid
请求数/天	100,000	无限
CPU 时间/请求	10ms	30s
Worker 大小	1 MB	10 MB
环境变量	64 个	128 个

504 超时

Workers 免费版 CPU 时间限制为 10ms，超时会返回 504。解决方案：

优化代码减少计算量
升级到 Paid 计划（30s CPU 时间）
将耗时操作拆分为多个请求