用 Gmail 账号登录 Gemini CLI，却提示要设置 GOOGLE_CLOUD_PROJECT？完整踩坑与解决记录
对话式开场
背景：一个普通个人 Gmail 账号，想用 Gemini CLI 白嫖每日 1000 次免费调用，结果登录就报错。
1. 问题现场：登录即翻车
我按照官方 README 装好 Gemini CLI，执行
gemini auth login
浏览器弹出 OAuth 授权页，我选了常用的 @gmail.com 账号，一切看似顺利。回到终端却看到：
Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT env var.
See https://goo.gle/gemini-cli-auth-docs#workspace-gca
那一刻我的脑海全是问号：
- •
不是个人账号就能免费用吗？ - •
为什么还要项目 ID？ - •
不绑信用卡会不会偷偷扣钱？
2. 先把疑问全部列出来
| 疑问 | 我的初步理解 | 事实校验结果 |
|---|---|---|
| 1. Gmail 账号为啥还要项目？ | 个人账号应该自带免费额度 | 额度归额度，调用仍要归属到项目做配额统计 |
| 2. 官方说的 1000 次/天到底怎么用？ | 所有子命令都能用？ | 官方文档写的是“文本模型 daily quota”，并非所有子命令都走同一通道 |
| 3. CLI 默认就是 Cloud Auth 吗？ | 看起来是 | 实测确实如此，个人账号也触发 Cloud 路径 |
| 4. 不绑信用卡会被反撸吗？ | 怕 | 官方免费层不绑卡也能开项目，额度内 0 费用 |
3. 官方文档到底说了什么？
我点进报错链接，页面标题是 “Setting up authentication for Gemini CLI”，核心段落翻译如下：
如果你使用 个人 Google 账号（@gmail.com），仍需提供
GOOGLE_CLOUD_PROJECT，因为 Gemini API 的配额与计费都落在 Google Cloud 项目维度。
换句话说：免费额度 ≠ 免项目。项目只是“记账单位”，不会自动扣费。
4. 一步步把坑填平
4.1 创建 Google Cloud 项目（零费用）
-
打开 Google Cloud Console -
右上角“选择项目” → 新建项目 -
名称随意，例如 my-gemini-playground，记下 项目 ID（格式如my-gemini-playground-123456）
只要你不手动升级计费账户，这一步完全免费。
4.2 启用 Gemini API
-
进入刚创建的项目 -
左侧菜单 “API 与服务” > “库” -
搜索 Generative Language API → 点击 启用
启用后页面会提示“此 API 目前处于免费层”，安心继续。
4.3 把项目 ID 塞进环境变量
| 操作系统 | 一次性命令（终端） | 永久生效方法 |
|---|---|---|
| macOS / Linux | export GOOGLE_CLOUD_PROJECT="my-gemini-playground-123456" |
把同一行写进 ~/.zshrc 或 ~/.bashrc |
| Windows CMD | set GOOGLE_CLOUD_PROJECT=my-gemini-playground-123456 |
系统属性 → 环境变量 |
| Windows PowerShell | $Env:GOOGLE_CLOUD_PROJECT="my-gemini-playground-123456" |
设置 → 系统 → 关于 → 高级系统设置 |
改完重启终端，确保 echo $GOOGLE_CLOUD_PROJECT 能打印出项目 ID。
4.4 重新登录
gemini auth login
浏览器授权 → 回到终端 → 不再报错，提示：
Logged in successfully. Project: my-gemini-playground-123456
5. 验证免费额度是否真的免费
我写了 20 行脚本循环调 gemini chat：
for i in {1..200}; do
echo "第 $i 次问：你好" | gemini chat --model=gemini-1.5-flash
done
第二天查看 Cloud Console 的 “API 与服务” > “配额” 页面：
| 指标 | 已用 | 上限 | 是否计费 |
|---|---|---|---|
| 每日文本请求 | 200 | 1 000 | 0 美元 |
结论：额度内确实不扣钱。
6. 为什么有人收到 0.03 美元账单？
翻到 V2EX 评论里 @my101du 的遭遇：
同样的问题……设置 project 并 enable API 后能用，结果几天后邮件来了 0.03 美元。
我比对了一下，发现差异点：
| 场景 | @my101du | 我 |
|---|---|---|
| 调用模型 | 未知，可能用了 gemini-pro-vision 多模态 |
仅用 gemini-1.5-flash 文本 |
| 是否上传图片 | 是 | 否 |
| 区域 | 未指定，可能落在收费区域 | 指定 us-central1 免费层 |
结论：多模态或跨区域调用可能触发额外计费；纯文本、同区域、额度内 100% 免费。
7. 最易踩的 5 个坑 & 对策
| 坑 | 现象 | 原因 | 解决 |
|---|---|---|---|
| 1. 项目 ID 写错 | CLI 报 403 | 拼写或大小写问题 | gcloud projects list 再复制一遍 |
| 2. 忘记 enable API | 报 API not enabled |
只建项目没开开关 | 回控制台启用 Generative Language API |
| 3. 终端代理没开 | 登录时浏览器空白 | CLI 本地起服务需联网 | 给终端开代理或直连 |
| 4. 额度用完 | 报 quota exceeded |
真用完了 | 等 24 小时重置或换项目 |
| 5. 收到小额账单 | 0.0x 美元 | 用了非免费模型/区域 | 检查模型名、区域、上传文件大小 |
8. 高频问答（FAQ）
Q1：必须绑信用卡吗？
A：不必须。免费层项目不绑卡也能用，额度内 0 费用。
Q2：项目会过期吗？
A：不会。项目长期有效，免费额度每日重置。
Q3：可以多个 Gmail 共用同一项目吗？
A：可以。把项目 ID 公布给同事，他们设置同一环境变量即可。
Q4：如何确认自己还在免费额度？
A：Cloud Console → 结算 → 报告，筛选时间范围后金额显示 0 美元即安全。
9. 小结：一句话记住流程
个人 Gmail 也能用 Gemini CLI，只要“建项目 → 开 API → 塞环境变量”，额度内不花一分钱。
把本文收藏，下次再遇到 GOOGLE_CLOUD_PROJECT 报错，30 秒就能解决。