Gemini CLI 安装配置完整指南

本文档详细记录了在不同操作系统上安装和配置 Google Gemini CLI 的完整过程，包括 macOS、WSL2/Linux 环境的具体步骤。

📋 目录

前置要求
macOS 安装配置
WSL2/Linux 安装配置
环境变量配置
网络代理配置
测试和验证
故障排除
参考资源

前置要求

系统要求

Node.js 18 或更高版本
有效的 Google 账户
Google Cloud 项目（可在安装过程中创建）

检查 Node.js 版本

bash

node --version
npm --version

如果未安装 Node.js，请访问 Node.js 官网下载安装。

macOS 安装配置

1. 安装 Google Cloud CLI

使用 Homebrew（推荐）

bash

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Google Cloud SDK
brew install google-cloud-sdk

# 验证安装
gcloud version

手动安装方式

访问 Google Cloud SDK 下载页面
下载适合你系统架构的安装包
按照官方安装向导完成安装

2. 配置 Google Cloud CLI

身份验证

bash

# 登录 Google 账户
gcloud auth login

# 设置应用程序默认凭据
gcloud auth application-default login

项目配置

bash

# 查看现有项目
gcloud projects list

# 创建新项目（如需要）
gcloud projects create YOUR_PROJECT_ID

# 设置默认项目
gcloud config set project YOUR_PROJECT_ID

# 设置配额项目
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

# 设置默认区域
gcloud config set compute/region us-central1

3. 启用必要的 API

bash

# 启用 Gemini for Google Cloud API
gcloud services enable cloudaicompanion.googleapis.com

# 启用其他相关 API（可选）
gcloud services enable aiplatform.googleapis.com
gcloud services enable vertexai.googleapis.com

4. 安装 Gemini CLI

bash

# 全局安装
npm install -g @google/gemini-cli

# 验证安装
npx @google/gemini-cli --version

WSL2/Linux 安装配置

1. 更新系统包

bash

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL/Fedora
sudo yum update -y
# 或者对于较新版本
sudo dnf update -y

2. 安装 Node.js

使用 NodeSource 仓库（推荐）

bash

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL/Fedora
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

验证安装

bash

node --version
npm --version

3. 安装 Google Cloud CLI

使用包管理器安装

bash

# Ubuntu/Debian
# 添加 Google Cloud SDK 发行版 URI 作为包源
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# 导入 Google Cloud 公钥
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# 更新软件包列表并安装 Google Cloud CLI
sudo apt-get update && sudo apt-get install google-cloud-cli

# CentOS/RHEL/Fedora
# 更新 YUM
sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el8-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
       https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

# 安装 Google Cloud CLI
sudo yum install google-cloud-cli

手动安装方式

bash

# 下载安装包
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

# 解压
tar -xf google-cloud-cli-linux-x86_64.tar.gz

# 运行安装脚本
./google-cloud-sdk/install.sh

# 初始化 gcloud
./google-cloud-sdk/bin/gcloud init

# 添加到 PATH（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export PATH=$PATH:$HOME/google-cloud-sdk/bin' >> ~/.bashrc
source ~/.bashrc

4. 配置 Google Cloud CLI

bash

# 身份验证
gcloud auth login
gcloud auth application-default login

# 项目配置
gcloud projects list
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
gcloud config set compute/region us-central1

# 启用 API
gcloud services enable cloudaicompanion.googleapis.com

5. 安装 Gemini CLI

bash

# 全局安装
npm install -g @google/gemini-cli

# 验证安装
npx @google/gemini-cli --version

环境变量配置

1. 设置必要的环境变量

对于 bash 用户

bash

# 添加到 ~/.bashrc 或 ~/.bash_profile
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bash_profile
echo 'export GOOGLE_CLOUD_REGION="us-central1"' >> ~/.bash_profile

# 重新加载配置
source ~/.bash_profile

对于 zsh 用户

bash

# 添加到 ~/.zshrc
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.zshrc
echo 'export GOOGLE_CLOUD_REGION="us-central1"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

对于项目级配置

bash

# 在项目根目录创建 .env 文件
cat > .env << EOF
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_REGION="us-central1"
EOF

# 使用时加载
source .env && npx @google/gemini-cli -p "你的问题"

2. 验证环境变量

bash

echo $GOOGLE_CLOUD_PROJECT
echo $GOOGLE_CLOUD_REGION

网络代理配置

配置代理别名（解决网络连接问题）

方法一：创建 shell 别名

bash

# 添加到 ~/.bashrc、~/.bash_profile 或 ~/.zshrc
echo 'alias gemini="export all_proxy=socks5://127.0.0.1:7890 && npx @google/gemini-cli --telemetry false"' >> ~/.bash_profile

# 重新加载配置
source ~/.bash_profile

# 使用别名
gemini -p "你的问题"

方法二：创建包装脚本

bash

# 创建可执行脚本
cat > ~/.local/bin/gemini << 'EOF'
#!/bin/bash
export all_proxy=socks5://127.0.0.1:7890
npx @google/gemini-cli --telemetry false "$@"
EOF

# 添加执行权限
chmod +x ~/.local/bin/gemini

# 确保 ~/.local/bin 在 PATH 中
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

# 使用脚本
gemini -p "你的问题"

代理服务器配置说明

all_proxy=socks5://127.0.0.1:7890：适用于使用 SOCKS5 代理的情况
端口 7890 是常见的代理端口，请根据你的实际代理配置调整
--telemetry false：禁用遥测数据收集

其他代理配置选项

bash

# HTTP 代理
export http_proxy=http://127.0.0.1:8080
export https_proxy=http://127.0.0.1:8080

# SOCKS5 代理
export all_proxy=socks5://127.0.0.1:1080

# 不使用代理的地址
export no_proxy=localhost,127.0.0.1,*.local

测试和验证

1. 基础功能测试

bash

# 显示帮助信息
npx @google/gemini-cli --help

# 检查版本
npx @google/gemini-cli --version

# 基础对话测试
npx @google/gemini-cli -p "Hello, please confirm that this CLI is working correctly."

2. 带代理的测试

bash

# 使用别名测试
gemini -p "请简短回复确认CLI工作正常"

# 直接使用代理命令测试
export all_proxy=socks5://127.0.0.1:7890 && npx @google/gemini-cli --telemetry false -p "测试网络连接"

3. 高级功能测试

bash

# 使用不同模型
gemini -m "gemini-2.5-pro" -p "解释一下人工智能"

# 调试模式
gemini -d -p "调试测试"

# 包含项目文件（在项目目录中运行）
gemini -a -p "分析这个项目的结构"

故障排除

常见错误及解决方案

1. API 未启用错误

Error: Gemini for Google Cloud API has not been used in project

解决方案：

bash

gcloud services enable cloudaicompanion.googleapis.com
# 等待几分钟让API激活生效

2. 环境变量缺失错误

Error: This account requires setting the GOOGLE_CLOUD_PROJECT env var

解决方案：

bash

echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bash_profile
source ~/.bash_profile

3. 权限被拒绝错误

Error: permission denied for service

解决方案：

bash

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

4. 网络连接错误

Error: connect ECONNREFUSED

解决方案：

bash

# 使用代理
export all_proxy=socks5://127.0.0.1:7890
# 或者使用已配置的别名
gemini -p "你的问题"

5. Node.js 版本过低

Error: Node.js version X.X.X is not supported

解决方案：

bash

# 升级 Node.js 到 18+ 版本
# 使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

验证步骤清单

完成安装后，请确认以下项目：

[ ] Google Cloud CLI 已安装并可运行 (gcloud version)
[ ] 已成功登录 Google 账户 (gcloud auth list)
[ ] 项目 ID 已正确设置 (gcloud config get-value project)
[ ] Gemini API 已启用 (gcloud services list --enabled | grep cloudaicompanion)
[ ] 环境变量已正确配置 (echo $GOOGLE_CLOUD_PROJECT)
[ ] Gemini CLI 可以正常响应 (npx @google/gemini-cli --version)
[ ] 代理配置正常（如需要）(gemini -p "测试")

常用命令参考

Gemini CLI 选项

bash

# 基础选项
-m, --model              # 指定模型（默认：gemini-2.5-pro）
-p, --prompt             # 提示词
-d, --debug              # 调试模式
-a, --all_files          # 包含所有文件在上下文中
-s, --sandbox            # 在沙箱中运行
-y, --yolo               # 自动接受所有操作
--telemetry false        # 禁用遥测
-h, --help               # 显示帮助

# 使用示例
gemini -p "你的问题"
gemini -m "gemini-2.5-pro" -p "复杂问题"
gemini -d -a -p "分析项目"

gcloud 常用命令

bash

# 配置管理
gcloud config list                    # 查看当前配置
gcloud config set project PROJECT_ID # 设置项目
gcloud config set compute/region REGION # 设置区域

# 认证管理
gcloud auth login                     # 用户认证
gcloud auth list                      # 查看已认证账户
gcloud auth application-default login # 应用默认凭据

# 服务管理
gcloud services list --enabled        # 查看已启用服务
gcloud services enable SERVICE_NAME   # 启用服务

# 项目管理
gcloud projects list                  # 列出项目
gcloud projects create PROJECT_ID     # 创建项目

参考资源

官方文档

npm 包

@google/gemini-cli - Gemini CLI 包
@google/genai - Google AI SDK

API 管理链接

系统特定资源

重要提醒：

请将文档中的 YOUR_PROJECT_ID 替换为你的实际 Google Cloud 项目 ID
代理端口 7890 请根据你的实际代理配置调整
确保不要在公共文档中暴露敏感信息如项目 ID、API 密钥等
定期检查 API 使用情况和费用，避免意外产生高额费用

本文档将随着 Gemini CLI 和相关工具的更新而持续维护更新。

Gemini CLI 安装配置完整指南 ​

📋 目录 ​

前置要求 ​

系统要求 ​

检查 Node.js 版本 ​

macOS 安装配置 ​

1. 安装 Google Cloud CLI ​

使用 Homebrew（推荐） ​

手动安装方式 ​

2. 配置 Google Cloud CLI ​

身份验证 ​

项目配置 ​

3. 启用必要的 API ​

4. 安装 Gemini CLI ​

WSL2/Linux 安装配置 ​

1. 更新系统包 ​

2. 安装 Node.js ​

使用 NodeSource 仓库（推荐） ​

验证安装 ​

3. 安装 Google Cloud CLI ​

使用包管理器安装 ​

手动安装方式 ​

4. 配置 Google Cloud CLI ​

5. 安装 Gemini CLI ​

环境变量配置 ​

1. 设置必要的环境变量 ​

对于 bash 用户 ​

对于 zsh 用户 ​

对于项目级配置 ​

2. 验证环境变量 ​

网络代理配置 ​

配置代理别名（解决网络连接问题） ​

方法一：创建 shell 别名 ​

方法二：创建包装脚本 ​

代理服务器配置说明 ​

其他代理配置选项 ​

测试和验证 ​

1. 基础功能测试 ​

2. 带代理的测试 ​

3. 高级功能测试 ​

故障排除 ​

常见错误及解决方案 ​

1. API 未启用错误 ​

2. 环境变量缺失错误 ​

3. 权限被拒绝错误 ​

4. 网络连接错误 ​

5. Node.js 版本过低 ​

验证步骤清单 ​

常用命令参考 ​

Gemini CLI 选项 ​

gcloud 常用命令 ​

参考资源 ​

官方文档 ​

npm 包 ​

API 管理链接 ​

系统特定资源 ​

Gemini CLI 安装配置完整指南

📋 目录

前置要求

系统要求

检查 Node.js 版本

macOS 安装配置

1. 安装 Google Cloud CLI

使用 Homebrew（推荐）

手动安装方式

2. 配置 Google Cloud CLI

身份验证

项目配置

3. 启用必要的 API

4. 安装 Gemini CLI

WSL2/Linux 安装配置

1. 更新系统包

2. 安装 Node.js

使用 NodeSource 仓库（推荐）

验证安装

3. 安装 Google Cloud CLI

使用包管理器安装

手动安装方式

4. 配置 Google Cloud CLI

5. 安装 Gemini CLI

环境变量配置

1. 设置必要的环境变量

对于 bash 用户

对于 zsh 用户

对于项目级配置

2. 验证环境变量

网络代理配置

配置代理别名（解决网络连接问题）

方法一：创建 shell 别名

方法二：创建包装脚本

代理服务器配置说明

其他代理配置选项

测试和验证

1. 基础功能测试

2. 带代理的测试

3. 高级功能测试

故障排除

常见错误及解决方案

1. API 未启用错误

2. 环境变量缺失错误

3. 权限被拒绝错误

4. 网络连接错误

5. Node.js 版本过低

验证步骤清单

常用命令参考

Gemini CLI 选项

gcloud 常用命令

参考资源

官方文档

npm 包

API 管理链接

系统特定资源