Skip to content

Cloudflare 全栈部署指南

· 10 min

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 仓库#

  1. 登录 Cloudflare Dashboard
  2. 进入 Workers & Pages，点击 Create，选择 Pages
  3. 选择 Connect to Git
  4. 授权 GitHub 或 GitLab
  5. 选择仓库，点击 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/                  → 静态资源
└── ...
functions/api/hello.js
export async function onRequest(context) {
  return new Response(JSON.stringify({ message: 'Hello World' }), {
    headers: { 'Content-Type': 'application/json' },
  })
}

自定义域名与 DNS#

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

添加域名#

  1. Dashboard 点击 Add a site
  2. 输入域名（如 example.com）
  3. 选择计划（Free 即可）
  4. 到域名注册商修改 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 模式后可获得：

SSL/TLS 配置#

推荐使用 Full (strict) 模式：

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

绑定 Pages 域名#

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

Cloudflare Workers#

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

创建 Worker#

方式一：Dashboard 创建

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

方式二：wrangler CLI（推荐）

Terminal window
# 安装 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 示例#

src/index.js
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 命名空间：

Terminal window
wrangler kv namespace create MY_KV

绑定到 Worker：

wrangler.toml
[[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 })
  },
}

免费额度：

D1 数据库#

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

创建数据库：

Terminal window
wrangler d1 create my-database

绑定到 Worker：

wrangler.toml
[[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 迁移：

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


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

免费额度：

R2 对象存储#

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

创建存储桶：

Terminal window
wrangler r2 bucket create my-bucket

绑定到 Worker：

wrangler.toml
[[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 })
  },
}

免费额度：

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"

部署到指定环境：

Terminal window
wrangler deploy --env preview

与其他平台对比#

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

选择建议：

最佳实践#

1. 使用 wrangler 本地开发#

Terminal window
# 本地开发服务器
wrangler dev


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

2. 环境变量管理#

Terminal window
# 查看已有 secrets
wrangler secret list


# 添加敏感变量
wrangler secret put API_KEY


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

3. 缓存策略#

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

public/_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

常见问题#

构建失败#

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

域名解析慢#

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

Workers 限制#

限制项FreePaid
请求数/天100,000无限
CPU 时间/请求10ms30s
Worker 大小1 MB10 MB
环境变量64 个128 个

504 超时#

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

参考资料#