Cloudflare Workers 免费部署完整指南（含代码）

什么是 Cloudflare Workers？

Cloudflare Workers 是无服务器边缘计算平台，代码运行在全球 275+ 数据中心。

核心优势：

项目实战：书签管理 API

我们将构建一个完整的书签管理 API：

• 添加书签
• 获取书签列表
• 删除书签
• 数据存储在 KV

步骤 1：注册 Cloudflare 账号

1. 访问 cloudflare.com
2. 点击 “Sign Up”
3. 用邮箱注册（免费）

步骤 2：安装 Wrangler CLI

# 安装 Node.js（如果没装）
# 然后安装 Wrangler
npm install -g wrangler

# 登录 Cloudflare
wrangler login

步骤 3：创建 Workers 项目

# 创建新项目
wrangler init bookmark-api
cd bookmark-api

# 项目结构
# ├── wrangler.toml
# ├── src/
# │   └── index.js
# └── package.json

步骤 4：配置 wrangler.toml

name = "bookmark-api"
main = "src/index.js"
compatibility_date = "2024-01-01"

# 绑定 KV 命名空间
[[kv_namespaces]]
binding = "BOOKMARKS"
id = "your-kv-namespace-id"
preview_id = "your-preview-kv-namespace-id"

# 环境变量
[vars]
API_TOKEN = "your-secret-token"

步骤 5：创建 KV 命名空间

# 创建生产 KV
wrangler kv:namespace create BOOKMARKS

# 创建预览 KV
wrangler kv:namespace create BOOKMARKS --preview

复制返回的 namespace ID 到 wrangler.toml

步骤 6：编写 API 代码

src/index.js：

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

    // CORS 头
    const corsHeaders = {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    };

    // 处理 OPTIONS 请求
    if (request.method === 'OPTIONS') {
      return new Response(null, { headers: corsHeaders });
    }

    // 验证 API Token（写入操作需要）
    const token = request.headers.get('Authorization');
    const isWrite = ['POST', 'DELETE', 'PUT'].includes(request.method);

    if (isWrite && token !== `Bearer ${env.API_TOKEN}`) {
      return new Response(JSON.stringify({ error: 'Unauthorized' }), {
        status: 401,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' }
      });
    }

    // 路由处理
    try {
      if (path === '/bookmarks' && request.method === 'GET') {
        return await getBookmarks(env, corsHeaders);
      } else if (path === '/bookmarks' && request.method === 'POST') {
        return await addBookmark(request, env, corsHeaders);
      } else if (path.startsWith('/bookmarks/') && request.method === 'DELETE') {
        const id = path.split('/')[2];
        return await deleteBookmark(id, env, corsHeaders);
      } else {
        return new Response(JSON.stringify({ error: 'Not Found' }), {
          status: 404,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' }
        });
      }
    } catch (error) {
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' }
      });
    }
  }
};

async function getBookmarks(env, headers) {
  const keys = await env.BOOKMARKS.list();
  const bookmarks = [];

  for (const key of keys.keys) {
    const value = await env.BOOKMARKS.get(key.name);
    if (value) {
      bookmarks.push(JSON.parse(value));
    }
  }

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

async function addBookmark(request, env, headers) {
  const body = await request.json();
  const { url, title, tags } = body;

  if (!url || !title) {
    return new Response(JSON.stringify({ error: 'URL and title required' }), {
      status: 400,
      headers: { ...headers, 'Content-Type': 'application/json' }
    });
  }

  const id = Date.now().toString();
  const bookmark = {
    id,
    url,
    title,
    tags: tags || [],
    createdAt: new Date().toISOString()
  };

  await env.BOOKMARKS.put(id, JSON.stringify(bookmark));

  return new Response(JSON.stringify({ success: true, bookmark }), {
    status: 201,
    headers: { ...headers, 'Content-Type': 'application/json' }
  });
}

async function deleteBookmark(id, env, headers) {
  await env.BOOKMARKS.delete(id);

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

步骤 7：本地测试

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

# 测试 API
curl http://localhost:8787/bookmarks

步骤 8：部署到 Cloudflare

# 部署
wrangler deploy

# 成功后会显示：
# Deployed bookmark-api triggered
# https://bookmark-api.your-subdomain.workers.dev

步骤 9：绑定自定义域名（可选）

1. 登录 Cloudflare Dashboard
2. 进入 Workers & Pages
3. 选择你的 Worker
4. 点击 “Add Custom Domain”
5. 输入你的域名（如 api.yourdomain.com）

Cloudflare 自动处理 SSL 证书。

API 使用示例

获取书签列表

curl https://api.yourdomain.com/bookmarks

添加书签

curl -X POST https://api.yourdomain.com/bookmarks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "url": "https://example.com",
    "title": "Example Site",
    "tags": ["demo", "test"]
  }'

删除书签

curl -X DELETE https://api.yourdomain.com/bookmarks/1234567890 \
  -H "Authorization: Bearer your-secret-token"

前端集成示例

// 浏览器扩展中调用
async function saveBookmark(url, title, tags) {
  const response = await fetch('https://api.yourdomain.com/bookmarks', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-secret-token'
    },
    body: JSON.stringify({ url, title, tags })
  });

  const data = await response.json();
  return data;
}

常见问题 FAQ

Q1: 免费额度是多少？

• 每天 10 万次请求
• 每次执行最长 10 分钟
• 足够个人项目使用

Q2: KV 读写有限制吗？

• 每天 10 万次读操作
• 每天 1000 次写操作
• 存储空间 1GB

Q3: 如何查看日志？

wrangler tail

Q4: 环境变量怎么管理？

# 设置 secret
wrangler secret put API_TOKEN

Q5: 如何回滚版本？

wrangler deploy --name bookmark-api@previous-version

成本计算

我的建议：先用免费版，流量起来再升级。

总结

你现在拥有：

✅ 全球分布的 API 服务 ✅ 免费 KV 数据库 ✅ 自定义域名支持 ✅ 秒级部署

下一步：

• 添加用户认证
• 集成浏览器扩展
• 添加搜索功能

💼 需要类似服务？

我提供 Cloudflare 开发服务：

📧 联系：[email protected]

相关阅读

• 从零搭建书签管理系统
• Next.js VPS 部署教程
• Chrome 扩展开发指南