文章 · 2026-10-16

Gemini CLI 怎么走代理？报地区不支持时先查哪条出口

先说结论：Gemini CLI 0.46.0 不会因为浏览器能打开 Gemini 就自动走同一条线路；它按 HTTPS_PROXY、https_proxy、HTTP_PROXY、http_proxy 的顺序读取第一个有值的代理变量。遇到地区不支持时，先在运行 Gemini CLI 的同一个终端确认 IPv4、IPv6 出口，再对照 Gemini API / Google AI Studio 的官方地区名单；代理设置只能修正终端的网络路径，不能改变服务的地区资格。

本文于 2026 年 10 月 16 日核对 Gemini CLI v0.46.0 官方源码、配置文档、认证文档，以及 Google AI for Developers 的可用地区页。下文的地区错误原文来自 2025 年 6 月 26 日用户在官方仓库提交的问题报告，不是 Google 对个案原因的确认。

Gemini CLI 到底读哪个代理设置？

答案是终端环境变量，不是浏览器设置。v0.46.0 的官方源码按下面顺序取第一个有值的变量：

1. HTTPS_PROXY
2. https_proxy
3. HTTP_PROXY
4. http_proxy

因此大小写变量同时存在且内容不同时，排在前面的值会生效。当前版本的帮助信息与官方源码都没有 --proxy 启动参数；看到 Unknown argument: proxy 时，应改用环境变量。

macOS 和 Linux 怎么设置？

建议使用代理软件提供的 HTTP 或混合端口。只对本次启动生效：

HTTPS_PROXY=http://127.0.0.1:7890 \
HTTP_PROXY=http://127.0.0.1:7890 gemini

要让之后打开的终端也使用，可写进 ~/.zshrc 或 ~/.bashrc：

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

改完要新开终端再启动 Gemini CLI。不要在截图、日志或文章里公开带用户名、密码的代理网址。

Windows PowerShell 怎么设置？

当前窗口可用下面两行，端口换成代理软件显示的 HTTP 或混合端口：

$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
gemini

只在 PowerShell 里设置不会自动影响已打开的其他终端或桌面程序；要测试时，应从这个窗口直接启动 Gemini CLI。

可以写进 .gemini/.env 吗？

可以。官方认证文档写明，Gemini CLI 会加载项目里的 .gemini/.env，也可以使用用户级的 ~/.gemini/.env。例如：

HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890

文档同时提醒：它只加载找到的第一份环境文件，不会把多份文件合并。某个项目正常、另一个项目直连时，要检查当前目录往上的环境文件是否更早被找到；API key 也是敏感信息，不要提交到 Git。

报“User location is not supported”先查什么？

先查发出请求的终端出口。2025 年 6 月 26 日有用户在官方仓库报告以下原文；截至核对日，官方文档和该报告只见到英文提示，未核实到独立的中文报错原文：

✕ [API Error: User location is not supported for the API use. (Status: FAILED_PRECONDITION)]

在运行 Gemini CLI 的同一个终端执行：

curl ipjudge.org
curl -6 ipjudge.org

第一条看 IPv4 出口与「Gemini API」一行；第二条在设备有 IPv6 时确认 IPv6 有没有走到另一地区。Google 的可用地区页写明，地区限制按实际运行请求的环境判断：例如 Colab 按实例地区，不按用户本人地区。

截至 2026 年 10 月 16 日，Google 的 Gemini API / AI Studio 名单包含台湾、新加坡、日本、美国等地区，不含中国大陆、香港、澳门。若请求出口不在名单内，官方页面指向 Gemini Enterprise Agent Platform；本文不提供绕过地区限制的方法。

连接错误、地区错误、认证错误怎么分开？

先保留完整原文，再处理对应层级：

怎么确认代理变量已经被 Gemini CLI 读到？

先看版本，再只检查变量是否存在，避免把带凭证的网址打印到日志：

gemini --version
test -n "$HTTPS_PROXY" && echo HTTPS_PROXY=set || echo HTTPS_PROXY=unset
test -n "$HTTP_PROXY" && echo HTTP_PROXY=set || echo HTTP_PROXY=unset

然后从同一个终端运行出口检测并启动 gemini。如果浏览器检测与终端检测不同，以终端结果为 Gemini CLI 这条路径的依据；本站只能核对出口与公开名单，不能读取 Google 内部的定位或账号判断。

常见问题

浏览器能用 Gemini，为什么 Gemini CLI 仍报地区不支持？

浏览器和终端可能走不同出口。应在启动 Gemini CLI 的同一终端检查 IPv4、IPv6，而不是只看浏览器。

只设置 HTTP_PROXY 可以吗？

源码会读取，但它排在 HTTPS_PROXY 与 https_proxy 后面。为避免不同工具取值不一致，建议同时设置 HTTPS_PROXY 和 HTTP_PROXY，并保持内容相同。

为什么写进 .gemini/.env 后另一个项目没生效？

Gemini CLI 只加载找到的第一份环境文件，不会合并多份；检查当前项目与父目录里是否已有更靠前的文件。

地区在官方名单内，仍然报同一句怎么办？

先确认 IPv4、IPv6 都在名单内，再保留版本、完整错误和不含凭证的出口信息向 Gemini CLI 官方仓库反馈。IP 定位结果可能不同，本站不能替 Google确认。

换代理就一定会恢复吗？

不能。代理变量只决定终端请求路径；账号、认证方式、组织策略、服务地区资格仍由 Google 判断。

相关检测与说明：Gemini 地区检测 · CLI 出口检测 · Gemini API 地区错误 · Gemini 国内与香港可用性 · 浏览器与终端看到哪个 IP