🚀 Cloudflare 快速入门指南

10分钟掌握 Cloudflare 核心服务，从零到部署

🌟 什么是 Cloudflare？

Cloudflare 是全球领先的边缘计算平台，提供 CDN、安全防护、无服务器计算等服务。让你的应用在全球 200+ 数据中心运行，实现极致性能。

🎯 核心优势

⚡ 极速响应: 边缘计算，延迟 < 1ms
🌍 全球覆盖: 200+ 数据中心，就近服务用户
💰 成本友好: 慷慨免费额度，成本比 Vercel 低 60-80%
🛡️ 安全可靠: 内置 DDoS 防护、SSL/TLS
🔧 开发友好: 一键部署，无需运维

🏗️ 适用场景

前端应用: React、Vue、Next.js 静态网站托管
API 服务: 高性能 RESTful API 开发
全栈应用: 前后端一体化部署
图片处理: 实时图片优化和 CDN 加速
微服务: 边缘函数替代传统服务器

⚡ 5分钟快速体验

# 1. 安装 Wrangler CLI
npm install -g wrangler

# 2. 登录 Cloudflare 账户
wrangler auth login

# 3. 创建第一个项目
wrangler create my-first-app

# 4. 本地预览
cd my-first-app
wrangler dev

# 5. 一键部署
wrangler deploy

🔍 Workers vs Pages：选择指南

📦 Cloudflare Workers

适合: API 开发、后端逻辑、数据处理

// Worker 示例：API 端点
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ 
        message: 'Hello from Cloudflare Worker!' 
      }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    return new Response('Not Found', { status: 404 });
  }
};

特点:

✅ 处理 HTTP 请求和响应
✅ 连接数据库和外部 API
✅ 实现复杂业务逻辑
✅ 支持定时任务

🌐 Cloudflare Pages

适合: 静态网站、前端应用、JAMstack

# 部署静态网站
wrangler pages deploy ./dist

# 部署 Next.js 应用
npm run build
wrangler pages deploy ./out

特点:

✅ 静态文件托管和 CDN
✅ 自动 HTTPS 和域名管理
✅ Git 集成，自动部署
✅ 预览环境和回滚
❌ 限制: 无法运行服务端代码，不支持 API Routes

🤝 组合使用

# 前端：Pages 托管 React 应用
wrangler pages deploy ./build --project-name=my-frontend

# 后端：Workers 提供 API 服务
wrangler deploy --name=my-api

# 数据库：D1 存储数据
wrangler d1 create my-database

🚀 Next.js 部署完整指南

🤔 选择部署方式

Pages vs Workers 对比:

Pages: 适合纯静态网站，无法使用 API Routes
Workers: 支持全栈应用，可以运行服务端代码和 API

方式一：Pages 部署（仅静态网站）

1. 配置 Next.js

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',  // 静态导出
  trailingSlash: true,
  images: {
    unoptimized: true  // 禁用图片优化
  }
};

module.exports = nextConfig;

2. 构建和部署

# 构建项目
npm run build

# 部署到 Pages
wrangler pages deploy ./out --project-name=my-nextjs-app

# 绑定自定义域名
wrangler pages domain add my-nextjs-app example.com

方式二：Pages + Functions 部署（推荐，支持 API）

重要说明: @cloudflare/next-on-pages 适配器会将 Next.js 应用转换为：

静态文件 → 部署到 Cloudflare Pages
API Routes → 自动转换为 Cloudflare Pages Functions

1. 安装适配器

npm install @cloudflare/next-on-pages

2. 配置 package.json

{
  "scripts": {
    "cf:build": "npx @cloudflare/next-on-pages",
    "cf:preview": "npm run cf:build && wrangler pages dev",
    "cf:deploy": "npm run cf:build && wrangler pages deploy"
  }
}

3. 配置 wrangler.toml（可选）

name = "my-nextjs-app"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]

# 数据库绑定（如果需要）
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"

4. 部署

# 构建和部署
npm run cf:deploy

# 或者分步执行
npm run cf:build
wrangler pages deploy

🔍 工作原理:

# Next.js 项目结构
src/
├── pages/
│   ├── index.js          # → 静态页面
│   └── api/
│       └── hello.js      # → Pages Function
└── app/
    ├── page.js           # → 静态页面
    └── api/
        └── route.js      # → Pages Function

# 构建后的输出
.vercel/output/static/    # → Pages 静态文件
.vercel/output/functions/ # → Pages Functions (API)

🔧 环境变量配置

# 本地开发环境变量
echo "NEXT_PUBLIC_API_URL=http://localhost:3000" > .dev.vars
echo "DATABASE_URL=your-db-url" >> .dev.vars

# 生产环境密钥
wrangler secret put DATABASE_URL
wrangler secret put API_SECRET_KEY

🗄️ 数据库解决方案

Cloudflare D1（推荐）

SQLite 兼容，边缘分布式数据库

# 创建数据库
wrangler d1 create my-app-db

# 创建表结构
echo "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);" > schema.sql
wrangler d1 execute my-app-db --file=schema.sql

# 插入测试数据
wrangler d1 execute my-app-db --command="INSERT INTO users (name, email) VALUES ('张三', 'zhang@example.com')"

# 查询数据
wrangler d1 execute my-app-db --command="SELECT * FROM users"

在 Worker 中使用 D1

export default {
  async fetch(request, env, ctx) {
    // 查询用户
    const { results } = await env.DB.prepare(
      "SELECT * FROM users WHERE email = ?"
    ).bind("zhang@example.com").all();
    
    return new Response(JSON.stringify(results), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

外部数据库集成

// 连接 PostgreSQL
const response = await fetch('https://your-postgres-api.com/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.DB_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'SELECT * FROM users'
  })
});

// 连接 MongoDB Atlas
const mongoResponse = await fetch(`https://data.mongodb-api.com/app/${env.MONGO_APP_ID}/endpoint/data/v1/action/find`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': env.MONGO_API_KEY
  },
  body: JSON.stringify({
    collection: 'users',
    database: 'myapp'
  })
});

📁 文件存储：Cloudflare R2

# 创建存储桶
wrangler r2 bucket create my-app-storage

# 上传文件
wrangler r2 object put my-app-storage/avatar.jpg --file=./avatar.jpg

# 配置 CORS（允许前端访问）
wrangler r2 bucket cors put my-app-storage --cors-file=cors.json

cors.json 配置

[
  {
    "AllowedOrigins": ["https://your-domain.com"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"]
  }
]

在应用中使用 R2

// 上传文件到 R2
export default {
  async fetch(request, env, ctx) {
    if (request.method === 'POST') {
      const formData = await request.formData();
      const file = formData.get('file');
      
      // 上传到 R2
      await env.MY_BUCKET.put(`uploads/${file.name}`, file.stream());
      
      return new Response('File uploaded successfully');
    }
  }
};

🔧 完整项目配置示例

wrangler.toml

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

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

# 数据库绑定
[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "your-database-id"

# 存储桶绑定
[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-app-storage"

# KV 存储绑定
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

# 生产环境配置
[env.production]
vars = { 
  ENVIRONMENT = "production",
  API_BASE_URL = "https://prod-api.example.com"
}

💡 实用技巧

1. 本地开发最佳实践

# 使用 .dev.vars 管理本地环境变量
echo "API_KEY=dev-key-123" > .dev.vars
echo "DATABASE_URL=sqlite://local.db" >> .dev.vars

# 启动本地开发服务器
wrangler dev --port 8787

# 本地数据库操作
wrangler d1 execute my-app-db --local --command="SELECT * FROM users"

2. 多环境部署

# 部署到测试环境
wrangler deploy --env staging

# 部署到生产环境
wrangler deploy --env production

# 查看不同环境的日志
wrangler tail my-app --env production

3. 性能优化

// 使用缓存提升性能
export default {
  async fetch(request, env, ctx) {
    const cacheKey = new URL(request.url).pathname;
    
    // 检查缓存
    let response = await env.CACHE.get(cacheKey);
    if (response) {
      return new Response(response, {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    // 获取数据并缓存
    const data = await fetchDataFromAPI();
    await env.CACHE.put(cacheKey, JSON.stringify(data), {
      expirationTtl: 3600  // 1小时过期
    });
    
    return new Response(JSON.stringify(data));
  }
};

4. 错误处理和监控

export default {
  async fetch(request, env, ctx) {
    try {
      // 业务逻辑
      return await handleRequest(request, env);
    } catch (error) {
      // 错误日志
      console.error('Request failed:', error);
      
      // 返回友好错误信息
      return new Response(JSON.stringify({
        error: 'Internal Server Error',
        message: 'Something went wrong'
      }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' }
      });
    }
  }
};

🆘 故障排除

常见问题解决

1. 部署失败

# 检查配置文件语法
wrangler validate

# 查看详细错误信息
wrangler deploy --verbose

# 清除缓存重新部署
wrangler deploy --force

2. 环境变量不生效

# 检查 .dev.vars 文件格式
cat .dev.vars

# 确认生产环境密钥
wrangler secret list

# 重新设置密钥
wrangler secret put API_KEY

3. 数据库连接问题

# 检查数据库绑定
wrangler d1 list

# 测试数据库连接
wrangler d1 execute my-db --command="SELECT 1"

# 查看数据库配置
cat wrangler.toml | grep -A 5 "d1_databases"

4. 域名和 SSL 问题

# 检查域名状态
wrangler pages domain list

# 重新验证域名
wrangler pages domain add my-project example.com

# 强制 HTTPS 重定向
# 在 Cloudflare Dashboard > SSL/TLS > Edge Certificates 中启用

⚠️ 在中国使用的注意事项

🚫 可能遇到的问题

1. 网络连接问题

# 可能出现的错误
Error: connect ETIMEDOUT
Error: getaddrinfo ENOTFOUND

解决方案:

使用科学上网工具进行开发和部署
考虑使用国内镜像或代理
部署后的网站访问通常正常（CDN 在国内有节点）

2. 域名备案要求

使用自定义域名需要 ICP 备案
可以先使用 Cloudflare 提供的 .pages.dev 域名测试
备案解决方案: 由于备案通常需要国内服务器，推荐方案：
1. 在 Cloudflare 部署应用
2. 通过腾讯云 CDN 加速 Cloudflare 域名
3. 在腾讯云完成 ICP 备案
4. 备案完成后绑定自定义域名

3. 某些服务可能受限

Workers AI 等 AI 服务可能无法使用
部分第三方 API 集成可能受影响
建议提前测试核心功能

💰 成本对比（vs Vercel）

服务	Cloudflare	Vercel	节省
静态托管	免费无限	100GB/月	100%
函数调用	100万次/月免费	10万次/月免费	90%
带宽	免费无限	100GB/月	100%
构建时间	500分钟/月免费	100分钟/月免费	80%
团队协作	免费	$20/月起	100%

实际案例:

# 中等规模项目月成本对比
# Vercel Pro: $20/月 + 超量费用
# Cloudflare: $0-5/月（基本免费）
# 年节省: $180-300+

🛠️ 国内开发建议

1. 开发环境配置

# 设置代理（如果需要）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 使用国内 npm 镜像
npm config set registry https://registry.npmmirror.com

# 安装 Wrangler
npm install -g wrangler

2. 替代方案

开发阶段: 使用本地开发，减少网络依赖
部署阶段: 通过 GitHub Actions 自动部署
域名方案: 先用免费域名测试，后续备案自定义域名

📚 相关资源

官方文档

社区资源

学习路径

入门: 完成本指南的快速体验
进阶: 构建一个完整的全栈应用
优化: 学习性能优化和监控
扩展: 探索高级功能和集成

💡 小贴士: Cloudflare 提供慷慨的免费额度，足够个人项目和小型应用使用。开始你的边缘计算之旅吧！

Cloudflare 快速入门指南

On this page