名称: cloudflare 描述: 在Cloudflare边缘平台上构建应用程序的指南。适用于实现服务器less函数（Workers）、边缘数据库（D1）、存储（R2、KV）、实时应用（Durable Objects）、AI功能（Workers AI、AI Gateway）、静态站点（Pages）或任何边缘计算解决方案。许可证: MIT 版本: 1.0.0

Cloudflare 开发者平台技能

Cloudflare 开发者平台是一个全面的边缘计算生态系统，用于在Cloudflare的全球网络上构建全栈应用程序。它包括服务器less函数、数据库、存储、AI/ML能力和静态站点托管。

何时使用此技能

在以下情况下使用此技能：

在边缘构建服务器less应用程序
实现边缘数据库（D1 SQLite）
处理对象存储（R2）或键值存储（KV）
创建带有WebSockets的实时应用（Durable Objects）
集成AI/ML功能（Workers AI、AI Gateway、Agents）
部署带有服务器less函数的静态站点（Pages）
使用框架（Next.js、Remix、Astro等）构建全栈应用程序
实现消息队列和后台作业（Queues）
优化全球性能和低延迟

核心概念

边缘计算平台

Cloudflare边缘网络：代码在分布在300多个城市的全球服务器上运行，从最近的位置执行请求以实现超低延迟。

关键组件：

Workers：边缘上的服务器less函数
D1：带有全局读取复制的SQLite数据库
KV：分布式键值存储，具有最终一致性
R2：对象存储，零出口费用
Durable Objects：有状态计算，支持WebSocket
Queues：消息队列系统，用于异步处理
Pages：静态站点托管，带有服务器less函数
Workers AI：在边缘运行AI模型
AI Gateway：AI提供商的统一接口

执行模型

V8隔离环境：轻量级执行环境（比容器更快），具有：

毫秒级冷启动
零基础设施管理
自动扩展
按请求付费定价

处理器类型：

fetch：HTTP请求
scheduled：Cron作业
queue：消息处理
tail：日志聚合
email：邮件处理
alarm：Durable Object定时器

开始使用Workers

安装

# 安装Wrangler CLI
npm install -g wrangler

# 登录到Cloudflare
wrangler login

# 创建新项目
wrangler init my-worker
cd my-worker

# 开始本地开发
wrangler dev

# 部署到生产环境
wrangler deploy

基本Worker

// src/index.ts
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response('Hello from Cloudflare Workers!');
  }
};

配置（wrangler.toml）

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

# 环境变量
[vars]
ENVIRONMENT = "production"

# 绑定（按产品添加）

语言支持

JavaScript/TypeScript：主要语言（完全Node.js兼容）
Python：通过Workers Python的Beta支持
Rust：编译为WebAssembly

存储产品

D1（SQLite数据库）

使用案例：关系数据、复杂查询、ACID事务

设置：

# 创建数据库
wrangler d1 create my-database

# 添加到wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "YOUR_DATABASE_ID"

# 生成和应用架构
wrangler d1 execute my-database --file=./schema.sql

用法：

export default {
  async fetch(request: Request, env: Env) {
    // 查询
    const result = await env.DB.prepare(
      "SELECT * FROM users WHERE id = ?"
    ).bind(userId).first();

    // 插入
    await env.DB.prepare(
      "INSERT INTO users (name, email) VALUES (?, ?)"
    ).bind("Alice", "alice@example.com").run();

    // 批处理（原子性）
    await env.DB.batch([
      env.DB.prepare("UPDATE accounts SET balance = balance - 100 WHERE id = ?").bind(user1),
      env.DB.prepare("UPDATE accounts SET balance = balance + 100 WHERE id = ?").bind(user2)
    ]);

    return new Response(JSON.stringify(result));
  }
};

关键功能：

全局读取复制（低延迟读取）
单写入器一致性
标准SQLite语法
25GB数据库大小限制

KV（键值存储）

使用案例：缓存、会话、功能标志、速率限制

设置：

# 创建命名空间
wrangler kv:namespace create MY_KV

# 添加到wrangler.toml
[[kv_namespaces]]
binding = "KV"
id = "YOUR_NAMESPACE_ID"

用法：

export default {
  async fetch(request: Request, env: Env) {
    // 放入带TTL
    await env.KV.put("session:token", JSON.stringify(data), {
      expirationTtl: 3600 // 1小时
    });

    // 获取
    const data = await env.KV.get("session:token", "json");

    // 删除
    await env.KV.delete("session:token");

    // 列出带前缀
    const list = await env.KV.list({ prefix: "user:123:" });

    return new Response(JSON.stringify(data));
  }
};

关键功能：

亚毫秒级读取（边缘缓存）
最终一致性（约60秒全局）
25MB值大小限制
自动过期（TTL）

R2（对象存储）

使用案例：文件存储、媒体托管、备份、静态资源

设置：

# 创建桶
wrangler r2 bucket create my-bucket

# 添加到wrangler.toml
[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "my-bucket"

用法：

export default {
  async fetch(request: Request, env: Env) {
    // 放入对象
    await env.R2_BUCKET.put("path/to/file.jpg", fileBuffer, {
      httpMetadata: {
        contentType: "image/jpeg"
      }
    });

    // 获取对象
    const object = await env.R2_BUCKET.get("path/to/file.jpg");
    if (!object) {
      return new Response("未找到", { status: 404 });
    }

    // 流式响应
    return new Response(object.body, {
      headers: {
        "Content-Type": object.httpMetadata?.contentType || "application/octet-stream"
      }
    });

    // 删除
    await env.R2_BUCKET.delete("path/to/file.jpg");

    // 列出
    const list = await env.R2_BUCKET.list({ prefix: "uploads/" });
  }
};

关键功能：

S3兼容API
零出口费用（巨大成本优势）
无限存储
5TB对象大小限制
多部分上传支持

Durable Objects

使用案例：实时应用、WebSockets、协调、有状态逻辑

设置：

# wrangler.toml
[[durable_objects.bindings]]
name = "COUNTER"
class_name = "Counter"
script_name = "my-worker"

用法：

// 定义Durable Object类
export class Counter {
  state: DurableObjectState;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
  }

  async fetch(request: Request) {
    // 获取当前计数
    let count = (await this.state.storage.get<number>('count')) || 0;

    // 递增
    count++;
    await this.state.storage.put('count', count);

    return new Response(JSON.stringify({ count }));
  }
}

// 在Worker中使用
export default {
  async fetch(request: Request, env: Env) {
    // 获取Durable Object实例
    const id = env.COUNTER.idFromName("global-counter");
    const counter = env.COUNTER.get(id);

    // 转发请求
    return counter.fetch(request);
  }
};

WebSocket示例：

export class ChatRoom {
  state: DurableObjectState;
  sessions: Set<WebSocket>;

  constructor(state: DurableObjectState) {
    this.state = state;
    this.sessions = new Set();
  }

  async fetch(request: Request) {
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    this.state.acceptWebSocket(server);
    this.sessions.add(server);

    return new Response(null, { status: 101, webSocket: client });
  }

  async webSocketMessage(ws: WebSocket, message: string) {
    // 广播给所有连接客户端
    for (const session of this.sessions) {
      session.send(message);
    }
  }

  async webSocketClose(ws: WebSocket) {
    this.sessions.delete(ws);
  }
}

关键功能：

单实例协调（强一致性）
持久存储（付费计划上限1GB）
WebSocket支持
不活动对象自动休眠

Queues

使用案例：后台作业、邮件发送、异步处理

设置：

# wrangler.toml
[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"

[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30

用法：

// 生产者：发送消息
export default {
  async fetch(request: Request, env: Env) {
    await env.MY_QUEUE.send({
      type: 'email',
      to: 'user@example.com',
      subject: 'Welcome!'
    });

    return new Response('消息已排队');
  }
};

// 消费者：处理消息
export default {
  async queue(batch: MessageBatch<any>, env: Env) {
    for (const message of batch.messages) {
      try {
        await processMessage(message.body);
        message.ack(); // 确认成功
      } catch (error) {
        message.retry(); // 失败时重试
      }
    }
  }
};

关键功能：

至少一次交付
自动重试（指数退避）
死信队列支持
批处理

AI产品

Workers AI

使用案例：直接在边缘运行AI模型

设置：

# wrangler.toml
[ai]
binding = "AI"

用法：

export default {
  async fetch(request: Request, env: Env) {
    // 文本生成
    const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
      messages: [
        { role: 'user', content: '什么是边缘计算？' }
      ]
    });

    // 图像分类
    const imageResponse = await env.AI.run('@cf/microsoft/resnet-50', {
      image: imageBuffer
    });

    // 文本嵌入
    const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: 'Hello world'
    });

    return new Response(JSON.stringify(response));
  }
};

可用模型：

LLMs：Llama 3、Mistral、Gemma、Qwen
图像：Stable Diffusion、DALL-E、ResNet
嵌入：BGE、GTE
翻译、摘要、情感分析

AI Gateway

使用案例：AI提供商的统一接口，带缓存、速率限制、分析

设置：

// 通过AI Gateway使用OpenAI
const response = await fetch(
  'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4',
      messages: [{ role: 'user', content: 'Hello!' }]
    })
  }
);

功能：

请求缓存（降低成本）
速率限制
分析和日志
支持OpenAI、Anthropic、HuggingFace等

Agents

使用案例：使用工具和工作流构建AI代理

import { Agent } from '@cloudflare/agents';

export default {
  async fetch(request: Request, env: Env) {
    const agent = new Agent({
      model: '@cf/meta/llama-3-8b-instruct',
      tools: [
        {
          name: 'get_weather',
          description: '获取当前天气',
          parameters: {
            type: 'object',
            properties: {
              location: { type: 'string' }
            }
          },
          handler: async ({ location }) => {
            // 获取天气数据
            return { temperature: 72, conditions: 'sunny' };
          }
        }
      ]
    });

    const result = await agent.run('旧金山天气如何？');
    return new Response(JSON.stringify(result));
  }
};

AI搜索（RAG）

使用案例：构建检索增强生成应用

import { VectorizeIndex } from '@cloudflare/workers-types';

export default {
  async fetch(request: Request, env: Env) {
    // 生成嵌入
    const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
      text: query
    });

    // 搜索向量数据库
    const results = await env.VECTORIZE_INDEX.query(embeddings.data[0], {
      topK: 5
    });

    // 生成带上下文的响应
    const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
      messages: [
        {
          role: 'system',
          content: `上下文：${results.matches.map(m => m.metadata.text).join('
')}`
        },
        { role: 'user', content: query }
      ]
    });

    return new Response(JSON.stringify(response));
  }
};

Cloudflare Pages

静态站点 + 服务器less函数

部署：

# 通过Git部署（推荐）
# 在Cloudflare仪表板中连接GitHub仓库

# 或通过CLI部署
wrangler pages deploy ./dist

Pages函数

基于目录的路由在functions/中：

functions/
├── api/
│   ├── users/
│   │   └── [id].ts       # /api/users/:id
│   └── posts.ts          # /api/posts
└── _middleware.ts        # 全局中间件

示例函数：

// functions/api/users/[id].ts
export async function onRequestGet(context) {
  const { params, env } = context;
  const user = await env.DB.prepare(
    "SELECT * FROM users WHERE id = ?"
  ).bind(params.id).first();

  return new Response(JSON.stringify(user), {
    headers: { 'Content-Type': 'application/json' }
  });
}

中间件：

// functions/_middleware.ts
export async function onRequest(context) {
  const start = Date.now();
  const response = await context.next();
  const duration = Date.now() - start;

  console.log(`${context.request.method} ${context.request.url} - ${duration}ms`);
  return response;
}

框架支持

Next.js：

npx create-next-app@latest my-app
cd my-app
npm install -D @cloudflare/next-on-pages
npx @cloudflare/next-on-pages
wrangler pages deploy .vercel/output/static

Remix：

npx create-remix@latest --template cloudflare/remix

Astro：

npm create astro@latest
# 设置过程中选择“Cloudflare”适配器

SvelteKit：

npm create svelte@latest
npm install -D @sveltejs/adapter-cloudflare

Wrangler CLI 核心命令

核心命令

# 开发
wrangler dev                    # 本地开发服务器
wrangler dev --remote          # 在真实Cloudflare基础设施上开发

# 部署
wrangler deploy                # 部署到生产环境
wrangler deploy --dry-run     # 预览更改而不部署

# 日志
wrangler tail                  # 实时日志
wrangler tail --format pretty # 格式化日志

# 版本
wrangler deployments list      # 列出部署
wrangler rollback [version]   # 回滚到先前版本

# 秘密
wrangler secret put SECRET_NAME    # 添加秘密
wrangler secret list               # 列出秘密
wrangler secret delete SECRET_NAME # 删除秘密

项目管理

# 创建项目
wrangler init my-worker        # 创建Worker
wrangler pages project create  # 创建Pages项目

# 数据库
wrangler d1 create my-db           # 创建D1数据库
wrangler d1 execute my-db --file=schema.sql
wrangler d1 execute my-db --command="SELECT * FROM users"

# KV
wrangler kv:namespace create MY_KV
wrangler kv:key put --binding=MY_KV "key" "value"
wrangler kv:key get --binding=MY_KV "key"

# R2
wrangler r2 bucket create my-bucket
wrangler r2 object put my-bucket/file.txt --file=./file.txt

集成模式

全栈应用架构

┌─────────────────────────────────────────┐
│         Cloudflare Pages（前端）        │
│    Next.js / Remix / Astro / SvelteKit  │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│      Workers（API层/BFF）               │
│    - 路由                               │
│    - 认证                               │
│    - 业务逻辑                           │
└─┬──────┬──────┬──────┬──────┬───────────┘
  │      │      │      │      │
  ▼      ▼      ▼      ▼      ▼
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────────────┐
│ D1 │ │ KV │ │ R2 │ │ DO │ │ Workers AI │
└────┘ └────┘ └────┘ └────┘ └────────────┘

多语言存储模式

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // KV：快速缓存
    const cached = await env.KV.get(url.pathname);
    if (cached) return new Response(cached);

    // D1：结构化数据
    const user = await env.DB.prepare(
      "SELECT * FROM users WHERE id = ?"
    ).bind(userId).first();

    // R2：媒体文件
    const avatar = await env.R2_BUCKET.get(`avatars/${user.id}.jpg`);

    // Durable Objects：实时协调
    const chat = env.CHAT_ROOM.get(env.CHAT_ROOM.idFromName(roomId));

    // Queue：异步处理
    await env.EMAIL_QUEUE.send({ to: user.email, template: 'welcome' });

    return new Response(JSON.stringify({ user, avatar }));
  }
};

认证模式

import { verifyJWT, createJWT } from './jwt';

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // 登录
    if (url.pathname === '/api/login') {
      const { email, password } = await request.json();

      const user = await env.DB.prepare(
        "SELECT * FROM users WHERE email = ?"
      ).bind(email).first();

      if (!user || !await verifyPassword(password, user.password_hash)) {
        return new Response('无效凭据', { status: 401 });
      }

      const token = await createJWT({ userId: user.id }, env.JWT_SECRET);

      return new Response(JSON.stringify({ token }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    // 受保护路由
    const authHeader = request.headers.get('Authorization');
    if (!authHeader) {
      return new Response('未授权', { status: 401 });
    }

    const token = authHeader.replace('Bearer ', '');
    const payload = await verifyJWT(token, env.JWT_SECRET);

    // 在KV中存储会话
    await env.KV.put(`session:${payload.userId}`, JSON.stringify(payload), {
      expirationTtl: 86400 // 24小时
    });

    return new Response('已认证');
  }
};

缓存策略

export default {
  async fetch(request: Request, env: Env) {
    const cache = caches.default;
    const cacheKey = new Request(request.url);

    // 检查缓存
    let response = await cache.match(cacheKey);
    if (response) return response;

    // 检查KV（分布式缓存）
    const kvCached = await env.KV.get(request.url);
    if (kvCached) {
      response = new Response(kvCached);
      await cache.put(cacheKey, response.clone());
      return response;
    }

    // 从源获取（D1、R2等）
    const data = await fetchFromOrigin(request, env);
    response = new Response(data);

    // 存储在两个缓存中
    await cache.put(cacheKey, response.clone());
    await env.KV.put(request.url, data, { expirationTtl: 3600 });

    return response;
  }
};

最佳实践

性能

最小化冷启动：保持Worker轻量级（<1MB捆绑）
使用绑定而非Fetch：直接绑定比HTTP调用更快
边缘缓存：利用KV和Cache API访问频繁访问的数据
批处理操作：使用D1批处理进行多个查询
流式大响应：使用Response.body流处理大文件

安全

秘密管理：使用wrangler secret处理API密钥
环境隔离：分离生产/暂存/开发环境
输入验证：清理用户输入
速率限制：使用KV或Durable Objects进行速率限制
CORS：配置适当的CORS头

成本优化

R2处理大文件：零出口费用vs S3
KV用于缓存：减少D1/R2请求
请求去重：缓存相同请求
高效查询：正确索引D1表
监控使用情况：使用Cloudflare分析

开发工作流

本地开发：使用wrangler dev进行测试
类型安全：使用TypeScript与@cloudflare/workers-types
测试：使用Vitest与unstable_dev()
CI/CD：GitHub Actions与cloudflare/wrangler-action
逐步部署：使用基于百分比的滚动部署

常见模式

API网关

import { Hono } from 'hono';

const app = new Hono();

app.get('/api/users/:id', async (c) => {
  const user = await c.env.DB.prepare(
    "SELECT * FROM users WHERE id = ?"
  ).bind(c.req.param('id')).first();

  return c.json(user);
});

app.post('/api/users', async (c) => {
  const { name, email } = await c.req.json();

  await c.env.DB.prepare(
    "INSERT INTO users (name, email) VALUES (?, ?)"
  ).bind(name, email).run();

  return c.json({ success: true }, 201);
});

export default app;

图像转换

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);
    const imageKey = url.pathname.replace('/images/', '');

    // 从R2获取
    const object = await env.R2_BUCKET.get(imageKey);
    if (!object) {
      return new Response('未找到', { status: 404 });
    }

    // 使用Cloudflare Images转换
    return new Response(object.body, {
      headers: {
        'Content-Type': object.httpMetadata?.contentType || 'image/jpeg',
        'Cache-Control': 'public, max-age=86400',
        'cf-image-resize': JSON.stringify({
          width: 800,
          height: 600,
          fit: 'cover'
        })
      }
    });
  }
};

速率限制（KV）

async function rateLimit(ip: string, env: Env): Promise<boolean> {
  const key = `ratelimit:${ip}`;
  const limit = 100; // 每分钟请求数
  const window = 60; // 秒

  const current = await env.KV.get(key);
  const count = current ? parseInt(current) : 0;

  if (count >= limit) {
    return false; // 速率限制超出
  }

  await env.KV.put(key, (count + 1).toString(), {
    expirationTtl: window
  });

  return true;
}

export default {
  async fetch(request: Request, env: Env) {
    const ip = request.headers.get('CF-Connecting-IP') || 'unknown';

    if (!await rateLimit(ip, env)) {
      return new Response('速率限制超出', { status: 429 });
    }

    return new Response('OK');
  }
};

计划作业

# wrangler.toml
[triggers]
crons = ["0 0 * * *"] # 每天午夜

export default {
  async scheduled(event: ScheduledEvent, env: Env) {
    // 清理旧会话
    const sessions = await env.KV.list({ prefix: 'session:' });
    for (const key of sessions.keys) {
      const session = await env.KV.get(key.name, 'json');
      if (session.expiresAt < Date.now()) {
        await env.KV.delete(key.name);
      }
    }
  }
};

故障排除

常见问题

“模块未找到”错误

确保依赖项在package.json中
部署前运行npm install
检查wrangler.toml中的compatibility_date

数据库连接错误（D1）

验证wrangler.toml中的database_id
检查数据库是否存在：wrangler d1 list
运行迁移：wrangler d1 execute DB --file=schema.sql

KV未找到错误

创建命名空间：wrangler kv:namespace create MY_KV
添加绑定到wrangler.toml
配置更改后部署

冷启动超时

减少捆绑大小（<1MB理想）
移除不必要依赖项
对大库使用动态导入

CORS错误

添加CORS头到响应：

return new Response(data, {
  headers: {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type'
  }
});

部署失败

检查wrangler版本：wrangler --version
验证认证：wrangler whoami
查看控制台输出中的构建错误

调试

# 实时日志
wrangler tail

# 带断点的本地调试
wrangler dev --local

# 远程调试
wrangler dev --remote

# 检查部署状态
wrangler deployments list

决策矩阵

需求	选择
亚毫秒级读取	KV
SQL查询	D1
大文件（>25MB）	R2
实时WebSockets	Durable Objects
异步后台作业	Queues
ACID事务	D1
强一致性	Durable Objects
零出口成本	R2
AI推理	Workers AI
静态站点托管	Pages
服务器less函数	Workers
多提供商AI	AI Gateway

框架特定指南

Next.js

使用@cloudflare/next-on-pages适配器
配置next.config.js用于边缘运行时
通过wrangler pages deploy部署

Remix

使用官方Cloudflare模板
配置server.ts用于Workers
通过context.cloudflare.env访问绑定

Astro

使用@astrojs/cloudflare适配器
在astro.config.mjs中启用SSR
通过Astro.locals.runtime.env访问环境

SvelteKit

使用@sveltejs/adapter-cloudflare
在svelte.config.js中配置
通过event.platform.env访问平台

资源

文档：https://developers.cloudflare.com
Wrangler CLI：https://developers.cloudflare.com/workers/wrangler/
Discord社区：https://discord.cloudflare.com
示例：https://developers.cloudflare.com/workers/examples/
GitHub：https://github.com/cloudflare
状态页面：https://www.cloudflarestatus.com

实施清单

Workers设置

[ ] 安装Wrangler CLI（npm install -g wrangler）
[ ] 登录到Cloudflare（wrangler login）
[ ] 创建项目（wrangler init）
[ ] 配置wrangler.toml
[ ] 添加环境变量/秘密
[ ] 本地测试（wrangler dev）
[ ] 部署（wrangler deploy）

存储设置（根据需要）

[ ] 创建D1数据库并应用架构
[ ] 创建KV命名空间
[ ] 创建R2桶
[ ] 配置Durable Objects
[ ] 设置Queues
[ ] 添加绑定到wrangler.toml

Pages设置

[ ] 连接Git仓库或使用CLI
[ ] 配置构建设置
[ ] 设置环境变量
[ ] 添加Pages函数（如果需要）
[ ] 部署和测试

生产清单

[ ] 设置自定义域名
[ ] 配置DNS记录
[ ] 启用SSL/TLS
[ ] 设置监控/分析
[ ] 配置速率限制
[ ] 实施错误处理
[ ] 设置CI/CD管道
[ ] 测试逐步部署
[ ] 文档化回滚过程
[ ] 配置日志/可观测性