Cloudflare Workers 完全指南：从入门到实战的边缘计算部署手册

用户请求 → 某个机房的服务器 → 处理 → 返回

用户请求 → 最近的边缘节点（全球 300+） → 处理 → 返回

# 全局安装
npm install -g wrangler

# 或使用 npx（推荐，无需全局安装）
npx wrangler --version

npx wrangler login

# 使用官方脚手架创建项目
npm create cloudflare@latest -- my-first-worker

# 按提示选择：
# - 选择 "Hello World" example
# - 选择 "Worker only"
# - 选择 JavaScript 或 TypeScript
# - 是否启用 git：Yes
# - 是否立即部署：No（先本地测试）

my-first-worker/
├── src/
│   └── index.js      # Worker 代码
├── wrangler.toml     # 配置文件（或 wrangler.jsonc）
├── package.json
└── node_modules/

name = "my-first-worker"        # Worker 名称，也是访问路径
main = "src/index.js"           # 入口文件
compatibility_date = "2024-01-01"  # 兼容日期

# 可选：绑定 KV 存储
# [[kv_namespaces]]
# binding = "MY_KV"
# id = "xxxxxxxx"

# 可选：绑定 D1 数据库
# [[d1_databases]]
# binding = "DB"
# database_name = "my-db"
# database_id = "xxxxxxxx"

# 可选：环境变量
# [vars]
# API_KEY = "your-api-key"

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  },
};

cd my-first-worker
npx wrangler dev

⎔ Starting local server...
[wrangler] Ready on http://localhost:8787

npx wrangler deploy

Uploaded my-first-worker (1.23 sec)
Published my-first-worker (0.45 sec)
  https://my-first-worker.your-subdomain.workers.dev

export default {
  async fetch(request, env, ctx) {
    // 获取请求信息
    const url = new URL(request.url);
    const method = request.method;           // GET, POST, etc.
    const path = url.pathname;               // /api/users
    const params = url.searchParams;         // ?id=123
    const headers = request.headers;         // 请求头

    // 获取 POST 请求体
    if (method === 'POST') {
      const body = await request.json();     // JSON 格式
      // 或 await request.text()             // 文本格式
      // 或 await request.formData()         // 表单格式
    }

    // 获取客户端信息
    const ip = request.headers.get('CF-Connecting-IP');
    const country = request.cf?.country;     // 国家代码
    const city = request.cf?.city;           // 城市

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

// 简单文本响应
return new Response('Hello');

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

// 自定义状态码
return new Response('Not Found', { status: 404 });

// 重定向
return Response.redirect('https://example.com', 302);

// 带 CORS 头的响应
return new Response(data, {
  headers: {
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  },
});

export default {
  async fetch(request, env, ctx) {
    // 代理请求到其他服务
    const response = await fetch('https://api.example.com/data', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer ' + env.API_KEY,
      },
    });

    // 返回代理结果
    return response;
  },
};

npx wrangler kv:namespace create "MY_CACHE"

[[kv_namespaces]]
binding = "MY_CACHE"
id = "输出的 ID"

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

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

    // 删除
    await env.MY_CACHE.delete('key');

    // 写入带过期时间（秒）
    await env.MY_CACHE.put('session', 'data', { expirationTtl: 3600 });

    return new Response(value);
  },
};

npx wrangler d1 create my-database

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "输出的 ID"

CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT UNIQUE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

npx wrangler d1 execute my-database --file=./schema.sql

export default {
  async fetch(request, env, ctx) {
    // 查询所有用户
    const { results } = await env.DB.prepare(
      'SELECT * FROM users'
    ).all();

    // 带参数查询（防 SQL 注入）
    const user = await env.DB.prepare(
      'SELECT * FROM users WHERE id = ?'
    ).bind(1).first();

    // 插入数据
    await env.DB.prepare(
      'INSERT INTO users (name, email) VALUES (?, ?)'
    ).bind('张三', '[email protected]').run();

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

// src/index.js

// 配置目标 API
const TARGET_HOST = 'api.openai.com';

// 允许代理的路径前缀（安全考虑）
const ALLOWED_PATHS = ['/v1/chat', '/v1/models', '/v1/embeddings'];

export default {
  async fetch(request, env, ctx) {
    // 处理 CORS 预检请求
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
          'Access-Control-Allow-Headers': '*',
          'Access-Control-Max-Age': '86400',
        },
      });
    }

    const url = new URL(request.url);
    const path = url.pathname;

    // 安全检查：只代理允许的路径
    const isAllowed = ALLOWED_PATHS.some(p => path.startsWith(p));
    if (!isAllowed) {
      return new Response(JSON.stringify({ error: 'Path not allowed' }), {
        status: 403,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    // 构建代理请求
    const targetUrl = `https://${TARGET_HOST}${path}${url.search}`;

    // 复制原始请求头，移除不需要的
    const headers = new Headers(request.headers);
    headers.delete('host');
    headers.delete('cf-connecting-ip');
    headers.delete('cf-ipcountry');

    // 发起代理请求
    const response = await fetch(targetUrl, {
      method: request.method,
      headers: headers,
      body: request.body,
    });

    // 复制响应，添加 CORS 头
    const newResponse = new Response(response.body, response);
    newResponse.headers.set('Access-Control-Allow-Origin', '*');

    return newResponse;
  },
};

https://api.openai.com/v1/chat/completions

https://your-worker.your-subdomain.workers.dev/v1/chat/completions

// src/index.js

// 生成短码
function generateCode(length = 6) {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  let result = '';
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return result;
}

// 验证 URL 格式
function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;
  }
}

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

    // CORS 处理
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      });
    }

    // 创建短链接 POST /create
    if (path === '/create' && request.method === 'POST') {
      try {
        const { url: targetUrl } = await request.json();

        if (!targetUrl || !isValidUrl(targetUrl)) {
          return Response.json({ error: 'Invalid URL' }, { status: 400 });
        }

        // 生成唯一短码
        let code = generateCode();
        let existing = await env.LINKS.get(code);
        while (existing) {
          code = generateCode();
          existing = await env.LINKS.get(code);
        }

        // 存储映射关系（90 天过期）
        await env.LINKS.put(code, targetUrl, { expirationTtl: 90 * 24 * 60 * 60 });

        const shortUrl = `${url.origin}/${code}`;
        return Response.json({
          shortUrl,
          code,
          originalUrl: targetUrl
        }, {
          headers: { 'Access-Control-Allow-Origin': '*' },
        });
      } catch (e) {
        return Response.json({ error: 'Invalid request' }, { status: 400 });
      }
    }

    // 短链接跳转 GET /:code
    if (path.length > 1 && request.method === 'GET') {
      const code = path.slice(1); // 移除开头的 /
      const targetUrl = await env.LINKS.get(code);

      if (targetUrl) {
        return Response.redirect(targetUrl, 302);
      } else {
        return new Response('Short link not found', { status: 404 });
      }
    }

    // 首页
    return new Response(`
      <h1>URL Shortener</h1>
      <p>POST /create with {"url": "https://example.com"}</p>
    `, {
      headers: { 'Content-Type': 'text/html' },
    });
  },
};

name = "url-shortener"
main = "src/index.js"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "LINKS"
id = "你的 KV namespace ID"

curl -X POST https://your-worker.workers.dev/create \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/very-long-path"}'

{
  "shortUrl": "https://your-worker.workers.dev/abc123",
  "code": "abc123",
  "originalUrl": "https://www.example.com/very-long-path"
}

npm create hono@latest my-api
# 选择 cloudflare-workers 模板
cd my-api
npm install

// src/index.js
import { Hono } from 'hono';
import { cors } from 'hono/cors';

const app = new Hono();

// 全局中间件
app.use('*', cors());

// 路由定义
app.get('/', (c) => c.text('Hello Hono!'));

app.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ id, name: 'User ' + id });
});

app.post('/users', async (c) => {
  const body = await c.req.json();
  return c.json({ created: true, data: body });
});

// 404 处理
app.notFound((c) => c.json({ error: 'Not Found' }, 404));

// 错误处理
app.onError((err, c) => {
  console.error(err);
  return c.json({ error: 'Internal Server Error' }, 500);
});

export default app;

import { Hono } from 'hono';

// 定义环境类型
type Bindings = {
  DB: D1Database;
};

const app = new Hono<{ Bindings: Bindings }>();

app.get('/users', async (c) => {
  const { results } = await c.env.DB.prepare(
    'SELECT * FROM users LIMIT 100'
  ).all();
  return c.json(results);
});

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

  if (!user) {
    return c.json({ error: 'User not found' }, 404);
  }
  return c.json(user);
});

export default app;

# 部署到生产环境
npx wrangler deploy

# 部署到预览环境
npx wrangler deploy --env preview

# 查看部署日志
npx wrangler tail

# 添加 Secret
npx wrangler secret put API_KEY
# 然后输入密钥值

# 在代码中使用
const apiKey = env.API_KEY;

# 实时查看日志
npx wrangler tail

# 带过滤器
npx wrangler tail --format pretty --status error

name: Deploy to Cloudflare Workers

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}