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

> 2025年最新 Cloudflare Workers 搭建 Gemini API 代理完整教程，从注册到部署全流程指导，含4种方案对比、故障排查、安全配置，附替代中转服务推荐

- Source: https://www.aifreeapi.com/zh/posts/cloudflare-workers-gemini-api-proxy
- Language: zh
- Published: 2025-12-28
- Updated: 2025-12-28
- Publisher: AI Free API (https://www.aifreeapi.com)

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

![Cloudflare Workers 搭建 Gemini API 代理架构图](https://www.aifreeapi.com/posts/zh/cloudflare-workers-gemini-api-proxy/img/cover.png)

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

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

### 必备账号清单

| 账号类型 | 用途 | 获取难度 | 是否必需 |
|---------|------|---------|---------|
| Cloudflare 账号 | 部署 Worker | 简单（邮箱注册） | 是 |
| Google 账号 | 申请 Gemini API Key | 简单 | 是 |
| 域名 | 自定义域名访问 | 需购买或使用免费域名 | 是 |

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

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

### 域名准备指南

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

**获取域名的方式**：

| 方式 | 成本 | 推荐度 | 说明 |
|-----|------|-------|------|
| 购买域名 | 10-50元/年 | 推荐 | Namesilo、Cloudflare 等平台 |
| 免费域名 | 免费 | 可用 | eu.org、freenom 等（稳定性较差） |
| 已有域名 | 免费 | 最推荐 | 直接使用现有域名的子域名 |

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

### 翻墙环境说明

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

了解更多关于 Gemini 免费额度的限制，可以参考 [Gemini API 免费额度限制详解](/zh/posts/gemini-api-free-tier-limit-20-requests)。

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

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

### 方案对比表

| 方案 | 成本 | 技术难度 | 稳定性 | 延迟 | 适用场景 |
|-----|------|---------|-------|------|---------|
| Cloudflare Workers | 免费（100K/天） | 低 | 高 | 20-60ms | 个人开发者、学习使用 |
| Vercel Serverless | 免费（有限制） | 低 | 中 | 50-100ms | 前端开发者、小项目 |
| Docker 自建 | 服务器成本 | 高 | 可控 | 取决于服务器 | 企业、高定制需求 |
| API 中转服务 | 按量付费 | 零 | 高 | 30-80ms | 不想折腾、追求稳定 |

### 不同场景推荐

**个人开发者/学习使用**：推荐 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 网关开发者指南](/zh/posts/best-llm-api-gateway-developers-guide)。

![Cloudflare Workers 代理架构图](https://www.aifreeapi.com/posts/zh/cloudflare-workers-gemini-api-proxy/img/architecture.png)

## Cloudflare Workers 部署完整教程

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

### Cloudflare 账号注册与 Workers 创建

**步骤 1：登录 Cloudflare**

访问 [dash.cloudflare.com](https://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" 进入代码编辑界面。删除默认代码，粘贴以下代理代码：

```javascript
// 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）：

```bash
# 测试代理是否工作（使用 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：等待生效**

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

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

更多关于 Gemini API 国内访问的详细教程，可以参考 [Gemini API 国内中转实战指南](/zh/posts/gemini-api-china-access)。

### 性能优化技巧

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

### 多 API Key 轮换配置

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

```javascript
// 多 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());
```

![Cloudflare Workers 部署流程](https://www.aifreeapi.com/posts/zh/cloudflare-workers-gemini-api-proxy/img/deployment-flow.png)

## 常见问题与故障排查

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

### "User location is not supported" 解决

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

**错误原因**：
- 香港、中国大陆等地区不在 Gemini 支持列表
- 使用的代理 IP 被识别为不支持地区

**解决方案**：

| 解决方法 | 操作步骤 | 成功率 |
|---------|---------|-------|
| 切换代理节点 | 使用美国、日本、新加坡等节点 | 90% |
| 检查 Worker 区域 | 确保 Worker 部署在支持区域 | 85% |
| 使用 API 中转服务 | 直接使用 laozhang.ai 等服务 | 100% |

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

更多关于地区限制的解决方案，可以参考 [解决 Gemini 不支持所在地区问题的 8 种方法](/zh/posts/solve-gemini-region-restriction-problem)。

### 连接失败与超时问题

**错误表现**：
- `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_INVALID` | API Key 格式错误或已失效 | 在 AI Studio 重新生成 |
| `PERMISSION_DENIED` | API Key 没有访问权限 | 检查 Key 的权限设置 |
| `QUOTA_EXCEEDED` | 超出免费额度 | 等待重置或升级付费 |
| `429 Too Many Requests` | 请求频率过高 | 降低请求频率或使用多 Key |

**如何获取新的 API Key**：

1. 访问 [Google AI Studio](https://aistudio.google.com/)（需翻墙）
2. 点击 "Get API Key"
3. 选择创建新 Key 或使用现有项目
4. 复制保存 API Key

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

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

### API 中转服务原理

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

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

### laozhang.ai 优势与快速上手

[laozhang.ai](https://api.laozhang.ai/register?aff=JnIT) 是一个专业的 AI API 中转服务，特别适合国内用户使用。

**核心优势**：

| 特性 | 说明 |
|-----|------|
| 开箱即用 | 注册即可使用，无需任何配置 |
| 多模型支持 | Gemini、GPT-4、Claude 等 300+ 模型 |
| 稳定可靠 | 99.9% SLA 保证，7x24 技术支持 |
| 价格实惠 | 与官方价格一致或更低 |
| 国内直连 | 无需翻墙，国内网络直接访问 |

**快速上手**：

```python
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())
```

### 价格对比与选择建议

| 方案 | Gemini 2.5 Flash 价格 | 适用场景 |
|-----|----------------------|---------|
| 自建 Cloudflare | 免费（前 100K/天） | 学习、个人项目 |
| laozhang.ai | $0.075 / 100万 Token | 生产环境、企业应用 |
| Google 官方 | $0.075 / 100万 Token | 需要翻墙环境 |

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

了解更多 Gemini API 的价格信息，可以参考 [Gemini 2.5 API 价格完全指南](/zh/posts/gemini-2-5-api-pricing-guide)。

## 安全最佳实践

在使用 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` 访问

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

### 请求限制与监控

**设置请求限制**：

```javascript
// 简单的速率限制示例
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 账号、域名、API Key | 5-10 分钟 |
| 2 | 创建 Cloudflare Worker | 2 分钟 |
| 3 | 部署代理代码 | 1 分钟 |
| 4 | 配置自定义域名 | 2 分钟 |
| 5 | 验证测试 | 2 分钟 |

**三种选择路径**：

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

想了解如何在 IDE 中配置 Gemini API，可以参考 [Cline + Gemini API 完整配置指南](/zh/posts/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](https://api.laozhang.ai/register?aff=JnIT) 这样的专业中转服务会是更好的选择。

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