Cloudflare Workers 搭建免费 Gemini API 代理：2025年完整教程

Google Gemini 作为目前最强大的多模态 AI 模型之一，凭借 200 万 Token 的超长上下文窗口和强大的推理能力，吸引了大量开发者的关注。然而，由于 Google 官方政策限制，国内用户无法直接访问 Gemini API。本文将提供 2025 年 12 月最新验证有效的解决方案，手把手教你使用 Cloudflare Workers 搭建免费的 Gemini API 代理，实现国内稳定访问。

开始之前：搭建代理需要准备什么？

在开始部署之前，让我们先确认需要准备的资源，避免操作到一半发现缺东西。根据 2025 年 12 月的最新测试，以下是完整的准备清单：

必备账号清单

Cloudflare 账号注册：访问 cloudflare.com 使用邮箱免费注册即可。Cloudflare 提供慷慨的免费套餐，每日 100,000 次 Worker 请求完全免费。

Google 账号：如果没有 Google 账号，需要先注册一个。注意申请 Gemini API Key 时需要翻墙环境。

域名准备指南

这是很多用户卡住的地方。由于 workers.dev 域名在国内已被墙，必须使用自定义域名才能访问。

获取域名的方式：

域名托管到 Cloudflare：无论从哪里购买的域名，都需要将 DNS 托管到 Cloudflare，这样才能使用 Cloudflare Workers 的自定义域名功能。

翻墙环境说明

申请 Gemini API Key 时需要翻墙访问 Google AI Studio。注意：部分地区（如香港）即使翻墙也可能遇到 "User location is not supported" 错误，建议使用美国、日本等节点。

了解更多关于 Gemini 免费额度的限制，可以参考 Gemini API 免费额度限制详解。

4种代理方案深度对比：选择最适合你的

在开始搭建之前，让我们先了解目前主流的几种 Gemini API 代理方案，帮助你做出最适合自己的选择。

方案对比表

不同场景推荐

个人开发者/学习使用：推荐 Cloudflare Workers。免费额度充足（每天 10 万次请求），部署简单，全球 CDN 加速，国内访问稳定。

团队协作/中小项目：可以考虑 Cloudflare Workers + 多 API Key 轮换，或者直接使用 API 中转服务（如 laozhang.ai），省去维护成本。

企业级应用：建议使用 Docker 自建或专业的 API 中转服务，可以获得更好的稳定性保障和技术支持。

为什么推荐 Cloudflare Workers

1. 完全免费：每日 100,000 次请求免费，对个人使用完全够用
2. 全球加速：Cloudflare 在全球有 300+ 数据中心，延迟极低
3. 部署简单：无需服务器，5 分钟完成部署
4. 稳定可靠：Cloudflare 的 SLA 保证 99.9% 可用性
5. 国内可用：通过自定义域名可在国内直接访问

想深入了解更多 API 网关选择，可以参考 最佳 LLM API 网关开发者指南。

Cloudflare Workers 部署完整教程

现在开始实际操作。整个过程分为 5 个步骤，预计用时 5-10 分钟。

Cloudflare 账号注册与 Workers 创建

步骤 1：登录 Cloudflare

访问 dash.cloudflare.com，使用邮箱注册或登录你的 Cloudflare 账号。

步骤 2：进入 Workers & Pages

在左侧菜单找到 "Workers & Pages"，点击进入。

步骤 3：创建 Worker

1. 点击 "Create application"
2. 选择 "Create Worker"
3. 输入 Worker 名称（建议：gemini-proxy）
4. 点击 "Deploy" 完成初始创建

代理代码部署

创建 Worker 后，点击 "Edit code" 进入代码编辑界面。删除默认代码，粘贴以下代理代码：

// Gemini API 反向代理 Worker
// 更新时间：2025-12-28

const GEMINI_API_HOST = "generativelanguage.googleapis.com";

export default {
  async fetch(request) {
    // 处理 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": "*",
          "Access-Control-Max-Age": "86400",
        },
      });
    }

    // 构建目标 URL
    const url = new URL(request.url);
    url.host = GEMINI_API_HOST;
    url.protocol = "https:";

    // 转发请求
    const newRequest = new Request(url.toString(), {
      method: request.method,
      headers: request.headers,
      body: request.method !== "GET" ? request.body : null,
    });

    try {
      const response = await fetch(newRequest);

      // 添加 CORS 头
      const newHeaders = new Headers(response.headers);
      newHeaders.set("Access-Control-Allow-Origin", "*");

      return new Response(response.body, {
        status: response.status,
        headers: newHeaders,
      });
    } catch (error) {
      return new Response(JSON.stringify({ error: error.message }), {
        status: 500,
        headers: { "Content-Type": "application/json" },
      });
    }
  },
};

点击 "Save and Deploy" 保存并部署。

测试验证方法

部署完成后，可以使用以下命令测试（需要替换为你的 API Key）：

# 测试代理是否工作（使用 workers.dev 域名，需翻墙）
curl "https://your-worker.your-account.workers.dev/v1beta/models?key=YOUR_API_KEY"

# 测试 Gemini 模型列表
curl "https://your-worker.your-account.workers.dev/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello, Gemini!"}]}]}'

如果返回 JSON 格式的模型列表或生成结果，说明代理已正常工作。

进阶配置：自定义域名与性能优化

由于 workers.dev 域名在国内被墙，我们需要配置自定义域名才能在国内使用。

自定义域名配置步骤

前提条件：域名已托管到 Cloudflare（DNS 由 Cloudflare 管理）

步骤 1：进入 Worker 设置

在 Worker 详情页，点击 "Settings" → "Triggers"

步骤 2：添加自定义域名

1. 在 "Custom Domains" 部分，点击 "Add Custom Domain"
2. 输入你的子域名，例如：gemini.yourdomain.com
3. 点击 "Add Custom Domain"
4. Cloudflare 会自动为你添加 DNS 记录

步骤 3：等待生效

通常几分钟内即可生效。可以通过以下命令验证：

# 使用自定义域名测试（国内可直接访问）
curl "https://gemini.yourdomain.com/v1beta/models?key=YOUR_API_KEY"

更多关于 Gemini API 国内访问的详细教程，可以参考 Gemini API 国内中转实战指南。

性能优化技巧

1. 启用 Cache：对于频繁请求的内容，可以在 Worker 中添加缓存逻辑
2. 使用最近的边缘节点：Cloudflare 会自动选择最近的节点，无需额外配置
3. 压缩响应：在 Cloudflare 面板中启用 Brotli 压缩

多 API Key 轮换配置

如果需要更高的调用量或实现负载均衡，可以配置多个 API Key 轮换：

// 多 Key 轮换示例
const API_KEYS = [
  "your-api-key-1",
  "your-api-key-2",
  "your-api-key-3",
];

function getRandomKey() {
  return API_KEYS[Math.floor(Math.random() * API_KEYS.length)];
}

// 在请求时替换 API Key
// url.searchParams.set("key", getRandomKey());

常见问题与故障排查

这是本文的核心差异化内容。根据社区反馈和实际测试，我们整理了最常见的问题及解决方案。

"User location is not supported" 解决

这是最常见的错误，表示你的 IP 所在地区不被 Google AI 支持。

错误原因：

• 香港、中国大陆等地区不在 Gemini 支持列表
• 使用的代理 IP 被识别为不支持地区

解决方案：

Cloudflare Worker 特殊处理：Worker 本身运行在 Cloudflare 的边缘节点，而非你本地的 IP，因此通常不会遇到此问题。如果仍然出现，检查是否是 API Key 申请时的问题。

更多关于地区限制的解决方案，可以参考 解决 Gemini 不支持所在地区问题的 8 种方法。

连接失败与超时问题

错误表现：

• ERR_CONNECTION_REFUSED
• ERR_CONNECTION_TIMED_OUT
• ETIMEDOUT

排查步骤：

1. 检查 Worker 是否正常运行

   • 登录 Cloudflare Dashboard
   • 查看 Worker 的 Analytics，确认有请求记录

2. 检查自定义域名 DNS

   bash

   nslookup gemini.yourdomain.com
   # 应该返回 Cloudflare 的 IP

3. 检查 SSL 证书

   • 确保使用 HTTPS 访问
   • 在 Cloudflare 中确认 SSL 设置为 "Full" 或 "Full (Strict)"

4. 等待 DNS 生效

   • 新添加的域名可能需要几分钟到几小时生效
   • 可以尝试清除本地 DNS 缓存

API Key 相关错误处理

如何获取新的 API Key：

1. 访问 Google AI Studio（需翻墙）
2. 点击 "Get API Key"
3. 选择创建新 Key 或使用现有项目
4. 复制保存 API Key

不想自建？API 中转服务推荐

如果你觉得自建代理太麻烦，或者需要更稳定的服务，API 中转服务是一个很好的选择。

API 中转服务原理

API 中转服务本质上是帮你完成了代理搭建的工作。你只需要将请求发送到中转服务的地址，它会帮你转发到 Gemini API 并返回结果。

优势：

• 无需自己搭建和维护
• 通常更稳定（专业团队运维）
• 支持多种模型（Gemini + GPT + Claude）
• 提供技术支持

laozhang.ai 优势与快速上手

laozhang.ai 是一个专业的 AI API 中转服务，特别适合国内用户使用。

核心优势：

快速上手：

import requests

# 使用 laozhang.ai 中转访问 Gemini
url = "https://api.laozhang.ai/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_LAOZHANG_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Hello, Gemini!"}]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

价格对比与选择建议

选择建议：

• 学习和测试：自建 Cloudflare Workers
• 个人项目（用量大）：laozhang.ai（按量付费，无需维护）
• 企业应用：laozhang.ai（SLA 保证，技术支持）

了解更多 Gemini API 的价格信息，可以参考 Gemini 2.5 API 价格完全指南。

安全最佳实践

在使用 API 代理时，安全是一个容易被忽视但非常重要的问题。以下是一些最佳实践。

API Key 安全存储

错误做法：

• 将 API Key 硬编码在前端代码中
• 将 API Key 提交到公开的 Git 仓库
• 在日志中输出完整的 API Key

正确做法：

• 使用 Cloudflare Workers 的环境变量存储 API Key
• 设置 API Key 的使用限制
• 定期轮换 API Key

环境变量使用

在 Cloudflare Workers 中使用环境变量：

1. 进入 Worker 设置 → Variables
2. 添加环境变量，如 GEMINI_API_KEY
3. 在代码中使用 env.GEMINI_API_KEY 访问

export default {
  async fetch(request, env) {
    const apiKey = env.GEMINI_API_KEY;  // 从环境变量获取
    // ... 使用 apiKey
  }
};

请求限制与监控

设置请求限制：

// 简单的速率限制示例
const RATE_LIMIT = 100;  // 每分钟最大请求数
const requestCounts = new Map();

function checkRateLimit(ip) {
  const now = Date.now();
  const windowStart = now - 60000;  // 1分钟窗口

  const count = requestCounts.get(ip) || { count: 0, start: now };

  if (count.start < windowStart) {
    count.count = 1;
    count.start = now;
  } else {
    count.count++;
  }

  requestCounts.set(ip, count);
  return count.count <= RATE_LIMIT;
}

监控建议：

• 在 Cloudflare Analytics 中查看请求统计
• 设置异常流量告警
• 定期检查 API 调用日志

总结与常见问题

行动清单总结

通过本文，你应该已经掌握了使用 Cloudflare Workers 搭建 Gemini API 代理的完整流程。以下是关键步骤回顾：

三种选择路径：

1. 自建代理：按照本文步骤搭建 Cloudflare Workers 代理
2. 使用现有开源项目：直接部署 tech-shrimp/gemini-proxy 等项目
3. 使用 laozhang.ai：零配置直接使用，适合不想折腾的用户

想了解如何在 IDE 中配置 Gemini API，可以参考 Cline + Gemini API 完整配置指南。

常见问题 FAQ

Q1: Cloudflare Workers 免费额度够用吗？

A: 每天 100,000 次请求对个人使用完全够用。如果需要更多，可以升级 Workers Paid 计划（$5/月起）。

Q2: 自定义域名必须在 Cloudflare 购买吗？

A: 不必须。任何域名都可以，只需将 DNS 托管到 Cloudflare 即可。

Q3: 为什么配置了自定义域名还是无法访问？

A: 常见原因：DNS 还未生效（等待几分钟）、SSL 设置不正确、域名未正确托管到 Cloudflare。

Q4: 代理是否会影响 API 响应速度？

A: Cloudflare Workers 运行在全球边缘节点，延迟增加通常只有 20-60ms，几乎可以忽略。

Q5: 能否同时代理多个 AI API（Gemini + GPT）？

A: 可以，但需要修改 Worker 代码支持多个 API 端点。或者直接使用 laozhang.ai 这样的多模型中转服务。

Q6: API Key 会被 Cloudflare 看到吗？

A: Cloudflare Workers 处理请求时会看到请求内容。如果担心安全，可以在代码中对 Key 进行额外加密处理，或使用环境变量存储。

Q7: Worker 代理会被封吗？

A: Cloudflare 本身不会封禁合法的 API 代理使用。但如果违反 Google 的服务条款，可能导致 API Key 被封。

Q8: 有没有不需要域名的方案？

A: 如果完全不想处理域名问题，推荐直接使用 laozhang.ai 等 API 中转服务，注册即可使用。

写在最后

通过 Cloudflare Workers 搭建 Gemini API 代理是目前最经济实惠的国内访问方案。整个过程只需 10 分钟，即可获得稳定、快速的 API 访问能力。

如果你是技术用户，自建代理可以让你完全掌控整个流程；如果你更看重稳定性和便利性，laozhang.ai 这样的专业中转服务会是更好的选择。

无论选择哪种方案，希望本文能帮助你顺利开始 Gemini API 的开发之旅。如果在搭建过程中遇到问题，欢迎留言讨论。