2025年7月13日

使用命令行工具管理 Gemini：绕不过的 Node.js

为什么会误以为是 Node.js 应用

最初配置 Gemini CLI 时，我也以为它是 npm 包——看到命令行工具就条件反射 npm install -g。结果发现官方根本没有 npm 版本，用的是 Go 编译的二进制。后来才意识到，这个认知偏差挺普遍的：毕竟大部分 CLI 工具确实走的是 Node.js 生态。

这篇文章整理了实际能用的安装流程，主要是给和我一样先入为主的人省点时间。

环境准备

官方的 Gemini CLI 是用 Go 语言写的，并依赖 Google Cloud SDK 进行认证和配置。所以，准备工作是安装这两个核心依赖。

安装 Go (1.21+)

需要 Go 的编译器和工具链来安装 CLI。

  • Linux (Debian/Ubuntu):
    bash sudo apt update sudo apt install golang-go

  • macOS (Homebrew):
    bash brew install go

  • 其他系统: 参考 Go 官网下载页面。

安装后，通过 go version 确认版本不低于 1.21。

安装与初始化 gcloud

Google Cloud SDK (gcloud) 是与 Google Cloud 交互的基础，负责身份认证和项目配置。

  • 安装: 访问 Google Cloud SDK 官方文档，按照指引安装。通常是一个安装脚本。

  • 初始化: 安装后，运行 gcloud init，根据提示登录你的 Google 账号并选择一个默认项目。

安装与配置

依赖装好之后，接下来是四个连贯的配置步骤。我第一次配置时在第四步卡了很久，后面会专门说明。

安装 CLI

官方推荐使用 go install 命令。它会自动下载源码、编译并把可执行文件放到 Go 的二进制路径下 ($GOPATH/bin)。

go install github.com/google-gemini/gemini-cli/cmd/gemini@latest

安装后，确保你的 $GOPATH/bin 路径（通常是 $HOME/go/bin）已经添加到了系统的 PATH 环境变量中。

本地认证

Gemini CLI 使用 gcloud 的应用默认凭据 (Application Default Credentials, ADC) 进行认证。运行以下命令，浏览器会自动打开登录页面，完成授权即可。

gcloud auth application-default login

关联云端项目

你需要告诉 gcloud 当前工作的项目是哪一个。Gemini CLI 会自动使用这个配置。

gcloud config set project YOUR_PROJECT_ID

将 YOUR_PROJECT_ID 替换为你的项目 ID。

启用 API

这是我第一次配置时卡最久的地方。直接运行 gemini 命令会报 API has not been used... or it is disabled，原因是项目里没有启用 cloudaicompanion.googleapis.com 这个 API。

解决方法是手动启用：访问下面这个链接（把 YOUR_PROJECT_ID 换成你的项目 ID），在页面里点启用按钮，然后等 5-8 分钟让配置生效。我当时以为是即时的，结果一直报错，后来发现需要点耐心。

https://console.developers.google.com/apis/api/cloudaicompanion.googleapis.com/overview?project=YOUR_PROJECT_ID

使用与进阶

完成以上所有步骤后，就可以正常使用 Gemini CLI 了。

基本用法

  • 文本提问:
    bash gemini "写一个 Golang 的 Hello World 程序"

  • 多模态提问 (带图片):
    bash gemini "这张图里有什么？" -m path/to/your/image.jpg

多项目管理

gcloud 的配置是按用户隔离的，切换项目只需要再运行一次 gcloud config set project ANOTHER_PROJECT_ID。我觉得这比手动改环境变量或配置文件要方便，尤其是管理多个 Google Cloud 项目的时候。

总结与排错建议

整个流程核心就是三件事：装 Go 和 gcloud、用 gcloud 完成认证和项目关联、手动启用 API。第三步最容易被忽略，我第一次就是因为没启用 API，调试了半天才发现问题。

如果配置完还是报连接或权限错误，可以先跑一下 gemini check，它会直接告诉你哪里没配对。我测试下来，大部分问题都是 API 没启用或者项目 ID 写错了。