如果您在尝试登录 Gemini CLI 或使用 VS Code 中的 Gemini Code Assist 扩展时看到类似 FAILED_PRECONDITION: User location is not supported 的错误,这并不是您的帐户或代码的问题。Google AI Studio 和 Gemini API 在各国的推出并不均匀,部分地区被排除在支持列表之外。解决此问题的方法是设置一个来自受允许国家的 IP 地址的代理——接下来我们将讨论如何在终端、VS Code 和环境变量级别正确设置它。
什么是 Gemini CLI 和 Gemini Code Assist
Gemini CLI 是 Google 的控制台工具,允许您直接从终端与 Gemini 模型进行交互:编写代码、生成命令、分析项目文件并执行代理任务,而无需离开工作环境。它通过 generativelanguage.googleapis.com 或通过 Vertex AI 访问 API,具体取决于您使用的授权方式——Google AI Studio 密钥或 Google Cloud 帐户。
Gemini Code Assist 是一个针对 VS Code(以及 JetBrains IDE)的扩展,它将提示、自动补全和与模型的聊天嵌入到代码编辑器中。实际上,这是同一个 API,但通过扩展从 IDE 调用,而不是从命令行调用。两个工具使用相同的后端,因此区域封锁问题在两种情况下表现相同——扩展无法建立会话或在首次请求模型时返回错误。
一个重要的细节:这两个工具不仅向生成 API 发出网络请求,还向 Google 的授权服务(OAuth、Identity Toolkit)发出请求。如果代理仅针对一个端点进行配置,授权可能会成功,而生成可能会失败,反之亦然。因此,代理需要在系统环境变量级别进行配置,而不是在一个地方单独配置。
为什么 Gemini 在您的地区不可用
Google 传统上逐步推出新的 AI 产品:首先是美国和部分欧洲,然后是其他国家。对于 Gemini,这体现在 API 级别的地理限制——服务器检查传入请求的 IP 地址(有时还会检查 Google 帐户的计费地址)并与允许的位置列表进行比较。如果国家不在列表中,请求将以 precondition 错误中断,或者在没有明确解释的情况下超时。
这并不是传统意义上的封锁——您所在国家的提供商并没有切断任何东西,实际上是 Google 方面的地理过滤。因此,使用共享 IP 的 VPN 通常无济于事:这些地址被成千上万的人广泛使用,Google 将其标记为可疑,并要求输入验证码,或者如果 IP 范围在形式上未在该国注册,仍然会根据地理位置进行切断。需要一个看起来像是来自受支持地区的普通家庭或移动 IP 的地址——这正是居民和移动代理所解决的问题。
选择哪个代理来使用 Gemini API
对于像 Gemini CLI 这样的开发工具,代理的关键参数是会话的稳定性(以便在生成长响应时不会中断连接)、速度以及 IP 在 Google 反欺诈系统中看起来有多“干净”。以下是三种类型的比较:
| 代理类型 | 速度 | 地理封锁风险 | 何时使用 |
|---|---|---|---|
| 数据中心代理 | 高 | 中高 | 快速测试,单次 API 请求 |
| 居民代理 | 中高 | 低 | 每天使用 Gemini CLI 和 Code Assist |
| 移动代理 | 中 | 最低 | 当居民 IP 被地理过滤时 |
在实践中,对于开发者的日常工作,最方便的是 居民代理,绑定到特定国家,并且最好具有 10-30 分钟的粘性会话——这足以确保 OAuth 授权不会中断,并且终端会话在生成代码时不会掉线。数据中心代理更便宜、更快,但 Google 已经知道部分范围,并且有时在通过这样的 IP 登录时会要求额外的帐户验证。移动代理可以作为备用——如果居民地址由于某种原因被列入可疑名单,运营商的移动网络通常可以顺利通过地理检查。
在终端中设置代理:Linux、macOS、Windows
Gemini CLI 和大多数基于 Node.js 的控制台工具(它正是用 Node.js 编写的)尊重标准环境变量 HTTP_PROXY 和 HTTPS_PROXY。这足以将所有 CLI 流量通过代理转发,而无需修改应用程序配置。
对于 macOS 和 Linux(bash/zsh),在当前会话中添加:
export HTTP_PROXY="http://login:password@proxy_host:port"
export HTTPS_PROXY="http://login:password@proxy_host:port"
export NO_PROXY="localhost,127.0.0.1"
gemini --version
如果希望代理在终端的每次启动中都能应用,而不仅仅是在当前会话中,请将这些行添加到 ~/.zshrc 或 ~/.bashrc 中,并通过命令 source ~/.zshrc 重新启动终端。
对于 Windows,在 PowerShell 中设置变量如下:
$env:HTTP_PROXY = "http://login:password@proxy_host:port"
$env:HTTPS_PROXY = "http://login:password@proxy_host:port"
gemini --version
如果您希望在 PowerShell 重启后变量仍然保持,请使用 [System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://login:password@proxy_host:port", "User")——该变量将写入 Windows 用户配置文件。
如果您的代理需要单独的授权而不在 URL 中包含登录名(例如,通过 IP 白名单),只需从连接字符串中删除登录名和密码,并将您的服务器或工作机器的 IP 添加到代理提供商面板的白名单中。
在 VS Code 中为 Code Assist 设置代理
VS Code 具有自己的代理设置,这些设置不会自动从系统环境变量中继承,除非启用相应的选项。打开 settings.json(Ctrl+Shift+P → "Preferences: Open User Settings (JSON)")并添加:
{
"http.proxy": "http://login:password@proxy_host:port",
"http.proxyStrictSSL": false,
"http.proxySupport": "override"
}
参数 http.proxySupport: "override" 很重要:没有它,VS Code 可能会继续使用系统代理,或者完全忽略单个扩展的设置。修改设置后,请完全重启 VS Code(而不仅仅是重新加载窗口),因为 Gemini Code Assist 扩展在应用启动时只初始化一次网络客户端。
如果扩展仍然无法识别代理,请检查设置 http.proxyAuthorization——在少数情况下,企业版本的 VS Code 会出于安全原因阻止将登录名和密码传递到代理 URL 中,此时需要通过 Proxy-Authorization 头以 base64 格式传递凭据。
另一个要点是暂时禁用企业 VPN 客户端和流量拦截的防病毒软件等扩展的诊断(SSL 检查)。它们通常会动态替换证书,而 Gemini Code Assist 严格检查 Google 的证书链,将导致连接中断并出现 TLS 错误,这很容易与代理本身的问题混淆。
在 Gemini CLI 中设置代理
除了环境变量,您还可以通过项目配置文件或用户全局设置在 Gemini CLI 中设置代理——如果您希望为不同项目使用不同的代理而不更改系统变量,这非常方便。配置通常存储在 ~/.gemini/settings.json 或项目目录中的 .env 文件中:
# .env 在项目根目录
GEMINI_API_KEY=您的密钥
HTTPS_PROXY=http://login:password@proxy_host:port
HTTP_PROXY=http://login:password@proxy_host:port
如果您通过 Google Cloud 帐户(Vertex AI)进行授权,而不是通过 AI Studio 密钥,则还需要确保代理也被 gcloud 工具使用,因为 OAuth 流程通过它进行。对于它,代理需要单独设置:
gcloud config set proxy/type http
gcloud config set proxy/address proxy_host
gcloud config set proxy/port port
gcloud config set proxy/username login
gcloud config set proxy/password password
如果之后 gcloud auth login 仍然在浏览器中打开真实(非代理)IP 以确认登录,请注意:OAuth 页面直接在您的系统浏览器中打开,如果浏览器未设置为相同的代理,则最终的授权会话可能会获得与您真实 IP 绑定的令牌。为了保持一致性,最好在您确认登录的浏览器中设置代理——例如,通过代理扩展或系统网络设置在授权期间进行设置。
连接测试:curl 和 Python
在弄清楚为什么 Gemini CLI 不工作之前,请确保代理基本上能够将流量传递到 Google API。最快的方法是通过 curl 进行直接请求:
curl -x http://login:password@proxy_host:port \
"https://generativelanguage.googleapis.com/v1beta/models?key=您的_API_KEY"
如果响应返回包含模型列表的 JSON(gemini-1.5-flash、gemini-1.5-pro 等)——代理工作正常且地区受支持。如果您看到 403 或 FAILED_PRECONDITION——则是地理过滤层面的问题,需要更改代理国家。
为了更详细的诊断,使用 Python 显式指定会话的代理是很方便的:
import requests
proxies = {
"http": "http://login:password@proxy_host:port",
"https": "http://login:password@proxy_host:port",
}
url = "https://generativelanguage.googleapis.com/v1beta/models"
params = {"key": "您的_API_KEY"}
response = requests.get(url, params=params, proxies=proxies, timeout=15)
print(response.status_code)
print(response.text[:500])
这样的脚本方便在启动完整的 CLI 或 IDE 会话之前进行快速检查——它在几秒钟内显示网络、密钥或 IP 地区是否有问题。
常见错误及其解决方案
错误 "User location is not supported" 即使在连接代理后通常意味着代理服务器的 IP 要么位于不受支持的国家,要么 Google 将其识别为数据中心并进行了额外检查。解决方案是切换到来自美国或其他完全支持 Gemini 的国家的居民或移动 IP。
生成长响应时的超时 通常与代理会话不稳定有关——IP 在请求中途更改,导致连接中断。需要一个粘性会话,其时间超过典型请求(通常 10-15 分钟的缓冲足以处理大量代码生成)。
SSL/TLS 握手失败错误 几乎总是指向防病毒软件、企业防火墙或 VS Code 中不正确配置的 proxyStrictSSL。请检查计算机上是否有 SSL 检查软件,并在诊断时暂时禁用它。
CLI 工作而 VS Code 中的扩展不工作(或反之亦然) 表示环境变量未传递到 VS Code 进程中。这在 Linux 和 macOS 中是常见情况,如果 VS Code 不是从导出变量的终端启动,而是从系统菜单中的图标启动。在这种情况下,变量需要通过 settings.json 进行设置,如上所述,而不是依赖于从 shell 继承。
将 IP 绑定到 API 密钥的区域和安全性
一个常常被忽视的细节是:如果 API 密钥或 Google Cloud 项目是与特定计费区域绑定创建的,切换代理的 IP 可能会导致预期位置与实际位置不符,Google 有时会要求通过 SMS 或电子邮件进行重新验证。为了减少此类检查的频率,尽量使用来自同一国家的固定(而非每个请求轮换)IP 的代理——这对于 Google 的保护系统看起来就像是一个普通用户的行为,而不是可疑活动。
如果您同时处理多个项目或密钥,并使用像 Dolphin Anty 或 AdsPower 这样的反检测浏览器来隔离配置文件(如果您在不同的浏览器环境中测试 Gemini 集成,这一点尤其重要),请将每个配置文件绑定到具有固定地理位置的单独代理——这样可以减少一个项目因混合 IP 而引发的怀疑。
还应避免将同一个免费或共享代理同时用于 Gemini 和其他高负载任务——来自同一 IP 的大量并行会话增加了被 Google 限制速率或临时封锁的风险,这看起来与地区问题相同,尽管原因完全不同。
结论
Gemini CLI 和 Gemini Code Assist 的区域限制在网络级别上解决:代理需要同时在系统环境变量、VS Code 设置中以及在使用 Google Cloud 时在 gcloud 配置中进行设置——只有这样,所有三个入口点(CLI、IDE 扩展和 OAuth 授权)才能通过同一个 IP 工作而不会不同步。在全面工作之前,总是通过简单的 curl 请求检查连接——这可以节省几个小时的诊断时间,因为问题实际上并不在代码中,而是在代理国家。
对于与 Gemini CLI 的稳定日常工作,最合适的是具有固定地理位置和长时间粘性会话的 居民代理——它们看起来像普通的家庭 IP,且很少引发 Google 的额外检查。如果居民地址仍然受到地理过滤,可以尝试 移动代理,而对于快速的单次 API 测试,没有长时间会话的情况下,使用 数据中心代理 完全足够。