Gemini API 调用代理设置：Python / Node.js 配置方法

为什么调用 Gemini API 需要单独设置代理

Gemini API 的接口地址是 generativelanguage.googleapis.com，它会校验请求来源地区。很多人遇到的情况是：浏览器里 AI Studio 正常，一运行脚本就报 “User location is not supported” 或连接超时。

原因很简单：浏览器会使用系统代理，而 Python、Node.js 程序默认不读取系统代理，请求直接从本地网络发出。解决思路有两种：一是让程序自己走代理（设置环境变量或在代码中指定），二是在代理客户端中开启 TUN 模式，让所有程序的流量都经过代理。本文重点讲第一种，TUN 模式见 Clash Verge TUN 模式设置。

准备工作

项目	要求	说明
API Key	在 AI Studio 中创建	创建受阻时先看 AI Studio 打不开怎么办
代理端口	客户端的本地 HTTP / 混合端口	Clash Verge Rev 默认通常为 7897，以实际设置为准
节点地区	Gemini API 支持地区	避开中国香港节点，以官方可用地区文档为准
运行环境	Python 3 或 Node.js 较新 LTS 版本	版本过旧可能缺少所需功能

分步操作

第一步：设置环境变量

把 API Key 和代理地址放进当前终端的环境变量中，程序从环境变量读取，避免把密钥写进代码。

# Windows PowerShell（仅对当前窗口有效）
$env:GEMINI_API_KEY = "替换为你自己的 API Key"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:HTTP_PROXY  = "http://127.0.0.1:7897"
$env:NO_PROXY    = "localhost,127.0.0.1"

# macOS / Linux（仅对当前终端有效）
export GEMINI_API_KEY="替换为你自己的 API Key"
export HTTPS_PROXY="http://127.0.0.1:7897"
export HTTP_PROXY="http://127.0.0.1:7897"
export NO_PROXY="localhost,127.0.0.1"

注意代理地址写 http://，这是本地代理端口的协议，与目标接口是 HTTPS 并不冲突。

第二步：用命令行验证链路

先不写代码，用命令行确认代理和 API Key 都正常。下面的请求会列出当前 Key 可用的模型：

# Windows PowerShell
curl.exe -x http://127.0.0.1:7897 -s "https://generativelanguage.googleapis.com/v1beta/models" -H "x-goog-api-key: $env:GEMINI_API_KEY"

# macOS / Linux
curl -x http://127.0.0.1:7897 -s "https://generativelanguage.googleapis.com/v1beta/models" -H "x-goog-api-key: $GEMINI_API_KEY"

返回模型列表说明网络与 Key 都没问题；返回地区相关错误说明出口地区不对；超时则先检查代理客户端。

第三步：Python 使用 requests 调用

requests 会自动读取 HTTPS_PROXY 环境变量，也可以像下面这样显式传入代理，便于确认代理确实生效：

import os
import requests

api_key = os.environ["GEMINI_API_KEY"]
proxies = {"http": "http://127.0.0.1:7897", "https": "http://127.0.0.1:7897"}
# 模型名以官方模型列表为准
url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent"
payload = {"contents": [{"parts": [{"text": "用一句话介绍你自己"}]}]}

resp = requests.post(
    url,
    headers={"x-goog-api-key": api_key, "Content-Type": "application/json"},
    json=payload,
    proxies=proxies,
    timeout=60,
)
print(resp.status_code)
print(resp.json())

第四步：Python 使用官方 SDK

Google 提供的 Python SDK 可以从环境变量读取 API Key。安装方式与调用写法以官方 SDK 文档为准，常见写法如下：

# pip install google-genai
from google import genai

client = genai.Client()  # 通常从 GEMINI_API_KEY 环境变量读取密钥
resp = client.models.generate_content(
    model="gemini-2.5-flash",  # 模型名以官方文档为准
    contents="用一句话介绍你自己",
)
print(resp.text)

在第一步设置了 HTTPS_PROXY 的终端中运行即可。SDK 底层的 HTTP 库一般会读取代理环境变量，如果发现没有生效，可以改用 TUN 模式，或查阅 SDK 文档中关于自定义 HTTP 客户端的说明。旧版 SDK 的传输方式可能不同，建议升级到官方当前推荐的版本。

第五步：Node.js 调用

Node.js 内置的 fetch 默认不读取 HTTPS_PROXY，需要额外设置全局代理。一种常见做法是借助 undici 的代理调度器：

// npm install @google/genai undici
import { GoogleGenAI } from "@google/genai";
import { ProxyAgent, setGlobalDispatcher } from "undici";

setGlobalDispatcher(new ProxyAgent(process.env.HTTPS_PROXY || "http://127.0.0.1:7897"));

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const res = await ai.models.generateContent({
  model: "gemini-2.5-flash", // 模型名以官方文档为准
  contents: "用一句话介绍你自己",
});
console.log(res.text);

把文件保存为 .mjs 后用 node 文件名.mjs 运行。较新版本的 Node.js 提供了让内置网络模块读取代理环境变量的选项（如 NODE_USE_ENV_PROXY=1），支持的版本与用法以 Node.js 官方文档为准；SDK 的包名与接口也可能更新，以官方 SDK 文档为准。

验证是否成功

1. 命令行列出模型成功，说明代理与 API Key 正常；
2. Python 或 Node.js 输出了模型回复文本，说明程序已经走代理；
3. 临时清空 HTTPS_PROXY 再运行一次，如果报地区错误或超时，就进一步证明之前是代理在生效；
4. 在代理客户端的连接列表中，能看到 generativelanguage.googleapis.com 的连接记录。

常见错误

报错或现象	原因	解决方法
User location is not supported	程序未走代理，或节点在不支持地区	检查环境变量是否在同一终端设置，换支持地区节点
连接超时、ConnectTimeout	代理端口错误或客户端未运行	核对端口，先用命令行验证
SSL / TLS 相关错误	代理地址写成了 https://	改为 http://127.0.0.1:端口，参考 TLS 握手失败
403 或提示 API Key 无效	Key 错误、被删除或项目未启用	在 AI Studio 中重新创建并复制完整 Key
429 或配额提示	触发频率或配额限制	降低频率并加入退避重试，见 Too Many Requests（429）

排查时还要留意一个容易忽略的细节：在一个终端窗口里设置了环境变量，却在另一个窗口或编辑器里运行脚本，变量并不会跟过去。遇到“明明设置了代理还是报地区错误”时，先在运行脚本的同一个窗口里输出一下 HTTPS_PROXY 的值，确认它确实存在。

让代理设置长期生效

上面的环境变量只对当前终端窗口有效，关闭窗口后就失效了。如果每天都要调用 API，可以把代理写进用户级环境变量或终端配置文件：

# Windows：写入用户级环境变量，重新打开终端后生效
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:7897", "User")
[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://127.0.0.1:7897", "User")

# macOS（zsh）/ Linux（bash 改为 ~/.bashrc）
echo 'export HTTPS_PROXY="http://127.0.0.1:7897"' >> ~/.zshrc
echo 'export HTTP_PROXY="http://127.0.0.1:7897"' >> ~/.zshrc
source ~/.zshrc

需要注意的是，永久设置后，所有读取这些变量的程序都会尝试走代理。代理客户端没有运行时，这些程序会连接失败，所以关闭代理客户端时记得同时想到这一点。如果只想让某个项目走代理，更稳妥的做法是在项目启动脚本里设置变量，或者在代码中显式传入代理地址。

在 VS Code 等编辑器的内置终端中运行脚本时，终端会继承编辑器启动时的环境变量。修改用户级环境变量后，需要完全重启编辑器才能生效，只关闭终端面板是不够的。

长时间批量调用的稳定性建议

1. 设置合理的超时：单次请求超时建议设为 60 秒左右，太短容易在生成长文本时被误判为失败；
2. 加入退避重试：遇到超时或 5xx 错误时，等待几秒后重试，且每次等待时间逐渐加长；
3. 区分错误类型：地区错误和 Key 无效属于配置问题，重试没有意义，应直接停止并检查；
4. 记录日志：保存每次请求的时间、状态码和错误信息，出问题时能快速判断是网络还是配额；
5. 选择低丢包线路：流式输出期间丢包会导致连接中断，思路与 Claude Code 网络环境配置 相同。

注意事项

• API Key 只放环境变量：不要写进代码、不要提交到仓库，泄露后立即删除重建；
• 固定节点：批量调用期间不要让客户端自动切换节点，否则出口地区变化可能导致请求失败；
• 命令行工具同理：Gemini CLI 等工具的代理设置思路相同，见 Gemini CLI 代理设置；
• 关于节点：本站未单独测试各品牌调用 Gemini API 的情况；Gemini 网页版在 2026 年 9 月实测可用的是二猫云、宇宙云、星岛梦，可作为地区条件的参考，长时间批量调用更应关注丢包与稳定性。

请遵守当地法律法规与服务条款，以及 Google 的 API 使用政策。