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,你可以:
- 管道数据流式处理:通过
cat error.log | gemini -m gemini-4-argon "解析堆栈报错根因"实现秒级诊断; - 免切屏代码生成:直接在终端调用全球第一的 Gemini 4 Carbon 生成复杂脚本或加固补丁,并通过标准输出重定向写入目标文件;
- 多模态图文直连:终端直接挂载截图或录像帧进行前端 UI 与报错排查;
- 结合自动化 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-flash | gemini -m gemini-4-carbon "全仓漏洞扫描" |
--stream | 是否开启打字机流式输出(默认开启) | gemini --no-stream "输出大文本" |
--format | 结果渲染格式:markdown (默认), json, plain | gemini --format json "提取实体" > res.json |
--system | 注入系统级角色设定指令 | gemini --system "你是一名资深 SRE" "分析宕机日志" |
--image, -i | 传入本地图片文件路径(支持 PNG, JPG, WebP) | gemini -i screenshot.png "指出 UI 样式错位原因" |
--temperature | 采样温度 (0.0 ~ 2.0),默认 0.7 | gemini --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