环境文件、路径与服务端点

环境变量既可由 shell 继承，也可来自 CLI 选中的 .env。排障先查认证方式、当前目录和选中文件，再检查是否有更早导出的同名值。

文件选择的版本差异

认证指南偏重 .gemini/.env；配置参考正文描述普通 .env 并称搜索在项目根或主目录停止。核验日期读取的官方固定 revision 中，findEnvFile 实际从当前目录逐级上行至文件系统根，每层在受信任时先找 .gemini/.env，再找普通 .env；最后回退用户目录，仍优先 .gemini/.env。

采用第一个文件，不合并所有文件。这个实现没有以 .git 为停止条件，不能根据参考正文假定项目根之外一定不会被搜索。安装版可能与 main 不同，应按对应版本核对。

已导出值与排除规则

普通加载仅补充进程环境中不存在的键，不覆盖 shell 已有值。advanced.excludedEnvVars 默认是 ["DEBUG", "DEBUG_MODE"]；Gemini 专用 .gemini/.env 不受这一项目变量排除规则影响。

advanced.ignoreLocalEnv 默认 false，开启可忽略项目中的通用 .env，不是禁用所有认证变量。当前源码还对不受信任来源仅保留认证白名单并清理值，与信任专页“完全忽略项目 .env”的概述有差异；不要把文件夹信任当成阻止任何环境值载入的保证。

Cloud Shell 特例

配置正文称 Cloud Shell 会把全局项目变量换成分配的默认项目，.env 中的 GOOGLE_CLOUD_PROJECT 可覆盖。固定 revision 的实现另对显式 Vertex AI 认证保留或恢复用户项目。切换认证后应检查实际项目，不能一概断言 Cloud Shell 总会覆盖 Vertex 项目。

用户目录与标识

GEMINI_CLI_HOME 指定用户配置和存储的根目录，CLI 在它下面创建 .gemini，不是直接把值当成 .gemini 目录。GEMINI_CLI_SURFACE 为 API User-Agent 增加自定义标签，可用于内部渠道标识。

API 端点

变量	作用
GOOGLE_GENAI_API_VERSION	覆盖 SDK 默认 API 版本
GOOGLE_GEMINI_BASE_URL	gemini-api-key 认证的 Gemini API 地址
GOOGLE_VERTEX_BASE_URL	vertex-ai 认证的 Vertex AI 地址

自定义地址必须有效且使用 HTTPS；localhost、127.0.0.1 和 [::1] 可用本地 HTTP。改变地址不代替认证配置，也不保证代理实现了全部 API。