AG
Gemini & Antigravity v2.6 GenAI 智能体工程指南
Gemini 4 矩阵 装机必备 实机验证: 2026-10

Gemini CLI 全平台终端极速安装与配置实战 (macOS / Linux / Windows)

官方与社区主流 Gemini CLI 工具链全平台零报错安装指南:涵盖 macOS Homebrew、Linux 一键脚本、Windows Winget 与 API Key 环境变量持久化最佳实践。

维护团队: Google GenAI 布道师团队 • Google GenAI & Antigravity 2.6 平台工程规范

跨平台一键安装并初始化 Gemini CLI 脚本

scripts/install-gemini-cli.sh

#!/usr/bin/env bash
set -e

echo "==> 正在检测操作系统与架构环境..."
OS="$(uname -s)"
ARCH="$(uname -m)"

case "$OS" in
  Darwin)
    echo "==> 检测到 macOS,优先使用 Homebrew 安装..."
    if command -v brew >/dev/null 2>&1; then
      brew install gemini-cli
    else
      npm install -g @google/gemini-cli
    fi
    ;;
  Linux)
    echo "==> 检测到 Linux,正在使用 npm 全局安装..."
    npm install -g @google/gemini-cli
    ;;
  *)
    echo "==> 未知系统,请参考文档通过 Node.js npm 安装: npm install -g @google/gemini-cli"
    exit 1
    ;;
esac

echo "==> 安装完成!运行 'gemini --version' 验证安装结果。"

为什么需要在终端中使用 Gemini CLI?

通过命令行终端(Terminal)直接与 Google 最新 Gemini 4 旗舰进行交互,是现代 AI 工程师提升生产力的利器。借助 CLI,你可以:

  1. 管道数据流式处理:通过 cat error.log | gemini -m gemini-4-argon "解析堆栈报错根因" 实现秒级诊断;
  2. 免切屏代码生成:直接在终端调用全球第一的 Gemini 4 Carbon 生成复杂脚本或加固补丁,并通过标准输出重定向写入目标文件;
  3. 多模态图文直连:终端直接挂载截图或录像帧进行前端 UI 与报错排查;
  4. 结合自动化 CI/CD:在持续集成构建过程中无缝注入多模态审查或自动化文档生成。

全平台安装指南

1. macOS (推荐 Homebrew 或 npm)

macOS 用户推荐使用官方 Homebrew 存储库:

# 使用 Homebrew 安装(保持自动更新)
brew install gemini-cli

# 或者使用 Node.js 全局安装
npm install -g @google/gemini-cli

2. Linux (Ubuntu / Debian / CentOS / Arch)

在 Linux 服务器或开发机上,确保已具备 Node.js 18+ 环境:

# Ubuntu / Debian 前置准备
sudo apt update && sudo apt install -y nodejs npm curl

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

# 验证安装版本
gemini --version

3. Windows 11 / 10 (Winget 或 PowerShell)

对于 Windows 开发者,推荐使用 Windows Terminal 搭配 Winget:

# 使用 Windows 软件包管理器 Winget 安装
winget install Google.GeminiCLI

# 或者使用 PowerShell 运行 npm 全局安装
npm install -g @google/gemini-cli

环境变量与 API 密钥持久化配置

安装完成后,你必须为 CLI 配置来自 Google AI Studio 的 API 密钥。

macOS / Linux (zsh 或 bash)

编辑你的 shell 配置文件(~/.zshrc 或 ~/.bashrc):

# 追加环境变量到 shell 配置中
echo 'export GEMINI_API_KEY="AIzaSyYourGeneratedSecretKey"' >> ~/.zshrc

# 立即刷新当前终端环境
source ~/.zshrc

Windows (PowerShell)

# 永久设置当前用户环境变量
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'AIzaSyYourGeneratedSecretKey', 'User')

CLI 参数矩阵与高级选项

Gemini CLI 提供了丰富的运行标志,满足各种自动化流水线需求:

运行参数 (Flag)说明与取值范围典型使用场景示例
--model, -m指定底层模型:gemini-4-carbon、gemini-4-argon、gemini-3-flashgemini -m gemini-4-carbon "全仓漏洞扫描"
--stream是否开启打字机流式输出(默认开启)gemini --no-stream "输出大文本"
--format结果渲染格式:markdown (默认), json, plaingemini --format json "提取实体" > res.json
--system注入系统级角色设定指令gemini --system "你是一名资深 SRE" "分析宕机日志"
--image, -i传入本地图片文件路径(支持 PNG, JPG, WebP)gemini -i screenshot.png "指出 UI 样式错位原因"
--temperature采样温度 (0.0 ~ 2.0),默认 0.7gemini --temperature 0.0 "精确输出 SQL"

多模态命令行调用:本地图片与音视频分析

Gemini 4 CLI 原生支持跨模态文件投递,无需预先上传云端:

# 1. 投递本地屏幕截图排查前端排版缺陷
gemini --image ./assets/dashboard-overflow.png "分析该看板在移动端发生横向溢出的 CSS 根因"

# 2. 结合代码库生成 Mermaid 架构拓扑
gemini --image ./diagrams/legacy-arch.jpg "将此架构白板草图转换为标准的 mermaid flowchart 语法"

# 3. 传入录音音频文件提取待办要点
gemini --audio ./meeting-notes.mp3 "总结本次架构评审的核心决策与 Action Items"

常用单行命令与管道协作

# 1. 基础问答与极速推导
gemini "用 3 句话解释量子纠缠的核心原理"

# 2. 结合 Git 提交管道自动草拟 Release Note
git log -n 10 --oneline | gemini "根据这 10 次提交记录撰写一份精简且带有分类的 Release Note"

# 3. 实时分析系统 dmesg 崩溃日志
dmesg | tail -n 50 | gemini -m gemini-3-flash "快速排查是否存在内核 OOM 或硬件 I/O 故障"

# 4. 进入交互式多轮对话会话 (REPL 模式)
gemini chat

生产排错与常见问题解决

1. 代理环境下的网络连接超时

如果你处于公司内网或需要通过代理访问,需在当前会话中显式声明代理环境变量:

# 针对 HTTP / HTTPS 代理
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

# 针对 Socks5 代理
export ALL_PROXY="socks5://127.0.0.1:7890"

2. 报错 403 Forbidden: API key not valid

  • 检查 echo $GEMINI_API_KEY 是否非空;
  • 前往 Google AI Studio 控制台 验证 Key 的有效性,并确认是否启用了 Gemini 4 / 3 API 权限。

3. Node.js 版本兼容性报错 (SyntaxError: Unexpected token '?')

Gemini CLI 深度利用现代 ES 特性,运行环境必须为 Node.js 18.0.0 或更高版本。使用 nvm 切换至现代 LTS 版本:

nvm install --lts && nvm use --lts