安装 Gemini CLI

Gemini CLI 安装不应该从"把所有命令都试一遍"开始。先选一个与你的使用场景匹配的入口：长期本机使用装 npm 或 Homebrew，只试一次用 npx，隔离执行用 sandbox，开发 Gemini CLI 本身才从源码跑。

1. 先选安装路径

flowchart TD
    Start["准备安装"] --> LongTerm{"长期本机使用?"}
    LongTerm -->|是| Npm["npm global 或 Homebrew"]
    LongTerm -->|否| Try{"只是临时试用?"}
    Try -->|是| Npx["npx @google/gemini-cli"]
    Try -->|否| Isolate{"需要隔离工具执行?"}
    Isolate -->|是| Sandbox["Docker / Podman sandbox"]
    Isolate -->|否| Source{"要开发 Gemini CLI 本身?"}
    Source -->|是| Dev["源码运行"]
    Source -->|否| Npm

    style Npm fill:#dcfce7,stroke:#22c55e
    style Sandbox fill:#fef3c7,stroke:#f59e0b
    style Dev fill:#fee2e2,stroke:#ef4444

2. 官方推荐环境

按官方 installation.mdx 当前列出的具体要求：

3. npm 全局安装

npm install -g @google/gemini-cli
gemini

这是官方 get started 和 deployment 文档里的标准路径。适合日常本机使用。

安装后先验证命令是否真的在 PATH 里：

gemini --version
which gemini

如果 gemini 找不到，优先查 npm global bin 路径、shell PATH 和 Node 版本，不要马上切到另一种安装方式。

4. npx 临时运行

npx @google/gemini-cli

适合第一次试用或不想全局安装。缺点是每次启动的可控性和速度不如固定安装。

官方首页也给了从 GitHub 直接运行最新代码的方式：

npx https://github.com/google-gemini/gemini-cli

这个入口适合测试最新主分支，不适合作为团队默认安装方式。团队教程应该优先写稳定 npm 或 Homebrew 路径。

5. Homebrew

brew install gemini-cli
gemini

macOS / Linux 用户如果习惯用 Homebrew 管 CLI，可以选这个。

MacPorts 备选（同样靠系统包管理）：

sudo port install gemini-cli

Anaconda 备选（适合受限环境，把 Node 装在 conda 环境里）：

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

6. Docker / Podman sandbox

官方安装页提供两种 sandbox 思路（具体镜像版本号请以 官方 installation 页 当前版本为准）：

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

或者本机已安装 CLI 后：

gemini --sandbox -y -p "your prompt here"

7. 源码运行

如果你要参与 Gemini CLI 本身开发，才需要从源码运行：

npm run start
npm link packages/cli
gemini

普通用户不需要走源码路径。源码运行会引入仓库依赖、构建状态、分支变化和本地 link 问题；这不是学习 Gemini CLI 的必要成本。

8. 安装后验收

安装验收只看四件事：

1. gemini --version 能输出版本。
2. gemini 能启动交互式界面。
3. 当前 shell 能找到同一个 gemini 路径。
4. 你知道自己下一步要用哪种认证方式。

不要在认证之前进入真实仓库大改。安装只是把 CLI 放到机器上，真正决定能不能用的是账号、项目、权限、quota、隐私和工具确认策略。

9. 接下来去哪

官方来源

• Gemini CLI Get Started
• Gemini CLI Execution and Deployment
• Gemini CLI GitHub