2026最新｜Cloudflare Workers 10分钟自建 Gemini API 代理：从零到国内直连，附完整代码+避坑清单

一、方案背景：跨境访问痛点与自建反代的价值

对于国内开发者而言，调用 Google Gemini 官方 API 普遍面临双重阻碍：一方面，受地区服务策略限制，官方 API 端点generativelanguage.googleapis.com在国内直连成功率极低；另一方面，跨境网络链路波动大，请求常出现 SSL 握手超时、响应延迟过高等问题，难以支撑常态化开发使用。

传统的 VPS 搭配 Nginx 反向代理方案，不仅需要支付服务器成本，还易因数据中心 IP 段触发 Google 平台风控，频繁出现 403、429 等访问异常。相比之下，基于 Cloudflare Workers 搭建自建反向代理，是兼顾成本、自由度与稳定性的折中方案：依托 Cloudflare 全球 200 余个边缘节点，无需自行维护服务器，免费额度可支持每日 10 万次请求，能够有效优化跨境访问的连通性，适合个人开发者与小型项目测试场景。

二、使用前需明确的三条核心红线

在部署前，需首先明确方案的能力边界与安全规则，避免后续出现风险：

1. 密钥属性边界：AI Studio 生成的AIza前缀密钥，是面向轻量调用的简易凭证，严禁嵌入前端或客户端代码公开暴露。据安全机构统计，公开网络中已发现近 3000 个暴露的活跃 Google API 密钥，一旦泄露将导致盗刷风险。
2. 服务规则边界：反向代理仅解决网络连通性与跨域问题，不改变 Gemini API 的地区使用限制与服务条款，所有调用仍需遵守 Google 官方的使用规则。
3. 免费额度边界：Workers 免费版存在每日请求数、CPU 运行时长的硬限制，超大体积请求（如高分辨率 base64 图片、超长上下文）易触发超时，使用时需做好请求体量控制。

三、分步实操：10 分钟完成反向代理部署

（一）第一步：获取官方 API 密钥

密钥需通过 Google AI Studio 正规渠道获取，具体步骤如下：

1. 登录 Google AI Studio 平台；
2. 在左侧菜单栏选择「Get API key」，可在新项目中创建密钥，或在已有项目下生成；
3. 获取前缀为AIzaSy的 API 密钥，妥善保管。

需注意：自 2025 年底起，Google 已对免费层调用配额进行调整，不同版本模型的免费额度存在差异。建议开发者在控制台配额页面确认可用额度与调用频率限制，避免因超额导致服务中断。

（二）第二步：Cloudflare 平台创建 Worker

1. 登录 Cloudflare 控制台，进入左侧「Workers & Pages」板块；
2. 点击「Create application」→「Create Worker」；
3. 为 Worker 设置自定义名称，点击「Deploy」完成初步创建；
4. 点击「Edit code」进入代码编辑页面，准备部署代理逻辑。

（三）第三步：部署核心代理代码

以下代码适配 2026 年最新接口规范，优化了参数拼接、流式响应透传、头部过滤等逻辑，可直接部署使用。代码支持 SSE 流式输出，兼容官方接口的核心能力。

javascript

运行

export default {
  async fetch(request, env, ctx) {
    // 1. 处理CORS预检请求
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        status: 204,
        headers: cors(),
      });
    }

    // 2. 从环境变量读取密钥，禁止硬编码在源码中
    const API_KEY = env.GEMINI_API_KEY;
    if (!API_KEY) {
      return jsonErr('Missing GEMINI_API_KEY (set it in Worker Settings → Variables/Secrets)', 500);
    }

    // 3. 访问来源控制，上线后建议关闭全量允许，指定自有域名
    const allowAll = true; 

    // 4. 构造目标官方API地址，路径映射到Google官方端点
    const url = new URL(request.url);

    // 仅允许官方API路径前缀，防止被滥用为通用转发
    if (!url.pathname.startsWith('/v1beta/') && !url.pathname.startsWith('/v1/')) {
      return jsonErr('bad path', 404);
    }

    url.hostname = 'generativelanguage.googleapis.com';
    url.protocol = 'https:';
    url.port = '';

    // 统一通过查询参数追加鉴权密钥，避免重复拼接
    url.searchParams.set('key', API_KEY);

    // 5. 清洗请求头，构造转发请求
    const cleanHeaders = filterHeaders(request.headers);

    const fwd = new Request(url.toString(), {
      method: request.method,
      headers: cleanHeaders,
      body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,
      redirect: 'manual',
    });

    // 6. 转发并透传响应，完整支持流式输出
    let resp;
    try {
      resp = await fetch(fwd);
    } catch (e) {
      return jsonErr('upstream error: ' + e.message, 502);
    }

    const out = new Response(resp.body, resp);
    setCORS(out, allowAll);

    return out;
  },
};

/* ---------- 工具函数 ---------- */

function cors() {
  return {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS, HEAD',
    'Access-Control-Allow-Headers': 'Content-Type, x-goog-api-key, Authorization',
    'Access-Control-Max-Age': '86400',
  };
}

function setCORS(r, allowAll) {
  r.headers.set('Access-Control-Allow-Origin', allowAll ? '*' : 'https://你的域名.com');
}

function jsonErr(msg, status) {
  return new Response(JSON.stringify({ error: msg }), {
    status,
    headers: { 'Content-Type': 'application/json' },
  });
}

/**
 * 过滤逐跳头部，避免Host头部冲突与转发异常
 */
function filterHeaders(h) {
  const keep = new Headers();
  const skip = new Set([
    'host','connection','keep-alive','transfer-encoding','upgrade',
    'proxy-authenticate','proxy-authorization','te','trailers','x-forwarded-for'
  ]);
  for (const [k, v] of h.entries()) {
    if (!skip.has(k.toLowerCase())) keep.set(k, v);
  }
  return keep;
}

（四）第四步：配置环境变量

密钥严禁直接写入代码文件，需通过 Cloudflare 的环境变量功能配置，步骤如下：

1. 在 Worker 详情页进入「Settings」→「Variables」，推荐使用「Secrets」加密变量；
2. 添加变量，键名为GEMINI_API_KEY，值为从 AI Studio 获取的密钥。

加密配置后，密钥不会在代码与日志中明文显示，可大幅降低泄露风险。

（五）第五步：绑定自定义域名（强烈推荐）

默认的*.workers.dev域名在国内部分运营商网络下存在间歇性访问异常，建议绑定自有域名优化稳定性：

1. 将自有域名的 DNS 托管至 Cloudflare；
2. 在 Worker 的「Triggers」设置中添加自定义域名，例如gemini.yourdomain.com；
3. 配置完成后，你的 API 基础地址将变为https://gemini.yourdomain.com/v1beta/...。

（六）第六步：客户端调用适配

完成部署后，客户端仅需修改接口域名即可正常调用，无需大幅改造代码。Python 调用示例如下：

python

运行

import requests

# 替换为你的Worker地址或自定义域名
BASE = "https://gemini.yourdomain.com"  

# 填写账号中可用的模型ID，建议使用官方稳定版本号
model = "gemini-2.5-flash-preview-04-17"
url = f"{BASE}/v1beta/models/{model}:generateContent"

payload = {
  "contents": [
    {"parts": [{"text": "用一句话解释什么是反向代理"}]}
  ]
}

# 密钥已在反代层统一追加，客户端无需重复传入
r = requests.post(url, json=payload, timeout=60)
print(r.json())

需注意：Gemini 模型的命名规则持续更新，早年的gemini-pro等旧名称多已失效，建议先调用/v1beta/models接口查询当前项目可用的模型 ID 列表，避免因模型名称错误导致 404。

四、常见避坑清单

部署与使用过程中，以下高频问题需重点规避：

1. 密钥硬编码风险：严禁将 API 密钥写入源码并上传至公开代码仓库，必须通过环境变量加密配置，否则极易被盗刷。
2. 参数拼接错误：不要手动拼接?key=查询参数，使用searchParams.set方法可避免原参数被覆盖、重复拼接等问题。
3. 重复传密钥：反代层已统一追加鉴权参数，客户端无需再在请求头或 URL 中重复传入密钥，避免造成逻辑混乱。
4. 流式响应中断：长文本流式输出易出现中断，需将客户端超时时间设置为 60 秒以上；Worker 侧不要读取或缓存响应正文，避免破坏流式传输。
5. 免费额度耗尽：频繁在线调试易快速耗尽每日免费请求额度，建议先在本地通过wrangler dev工具测试，再部署至线上环境。
6. 合规认知误区：反向代理仅优化网络连通性，不改变官方服务的地区使用规则与服务条款，需合规使用官方服务。
7. 域名生效验证：绑定自定义域名后，需等待 TLS 证书生效，可先通过 curl 命令验证接口连通性，确认返回鉴权错误而非连接超时后，再替换业务代码中的接口地址。

五、更优选型：兼顾稳定与便捷的商业聚合服务

自建 Workers 反向代理适合具备一定动手能力、追求控制权的个人开发者，但在稳定性、合规性、服务支持等方面仍存在局限，无法满足生产级业务的需求。对于追求低接入门槛、高稳定性的开发者与企业用户，合规的 AI API 聚合服务是更省心的选择。

UseAIAPI 作为专业的全球 AI 大模型服务平台，全面覆盖 Gemini、Claude、GPT 系列、DeepSeek 等全球主流热门大模型，无需用户自行搭建代理、配置跨境环境，注册即可快速调用。平台接口兼容通用调用协议，原有代码仅需修改基础调用地址即可完成适配，接入成本极低。

针对企业级用户，UseAIAPI 可提供定制化企业级服务方案，搭配专属技术支持与稳定专线链路，全方位保障业务稳定运行。成本方面，依托规模化采购优势，平台推出专属优惠政策，资费最低可达官方定价的 50%，能够大幅降低高强度内容生成、大算力消耗场景下的使用成本，让用户无需为 Token 消耗过度顾虑，专注于业务开发与产品创新。

结语

自建 Cloudflare Workers 反向代理，是个人开发者在成本、自由度与可控性之间的均衡选择，它无法突破官方服务的地区规则限制，但能够将 “无法连通” 的痛点转化为 “稳定可用” 的基础能力，适合学习测试、小型项目等非生产场景。

对于生产级业务与追求省心体验的用户，合规成熟的商业聚合服务是更优解，无需投入运维精力，即可获得稳定、低价、有保障的大模型调用服务。用户可根据自身的使用场景与需求，选择最适配的接入方案。