最近后台收到不少留言，都在问同一个话题：命令行里怎么用上Gemini。其实这类需求我特别理解，习惯了终端工作流的人，写脚本、处理文本、批量生成内容的时候，切到浏览器去点界面，效率一下就掉下来了。我自己也是重度终端用户，折腾过不少类似的CLI工具，所以这篇就来完整走一遍macOS和Linux下的Gemini CLI安装流程。这不是简单的命令搬运，我会把安装前后的环境准备、方式取舍、配置细节和常见坑都梳理清楚，照着做基本能一次跑通。
1 安装前的准备：先确认环境与工具链
很多人装CLI工具的习惯是拿到命令就粘贴执行，结果报错一堆，然后才开始排查环境问题。其实提前花两分钟确认三件事，能省下后面大量的折腾时间。
第一件事是运行时版本。Gemini CLI基于Node.js开发，需要JavaScript运行时环境。绝大多数的安装失败、启动报错，最后追根溯源都是Node版本太老。我的建议是Node版本至少16以上，如果用的是20或更高版本，那基本不用担心兼容性。检查方法很简单：
node -v npm -v如果node命令不存在，或者版本低于16，就先装Node。macOS上我推荐用nvm做版本管理，因为nvm可以随时切换Node版本，比如同时跑着不同项目、不同Node版本需求的情况，nvm用起来非常顺手。安装nvm的方式：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重启终端，或者执行source ~/.zshrc（macOS默认shell是zsh，Linux如果用的是bash就source~/.bashrc），然后：
nvm install 20 nvm use 20Linux上除了nvm，用系统的包管理器直接装Node也行。Debian系和Ubuntu可以用sudo apt install nodejs npm，但要注意系统源里的Node版本通常偏旧，如果后面安装时提示引擎不兼容，还是要回到nvm方案装新版本。个人经验：碰到这类开发工具，nvm永远是优先级最高的选择。
第二件事是包管理器。npm会随Node一起装上，绝大多数情况用npm就够了。但如果你用的是pnpm或者yarn，Gemini CLI也支持，只是后面有的命令写法略有差异，我会在对应步骤里标注出来。新手我建议直接npm，少一层变量，踩坑概率低。
第三件事是网络环境。npm默认走官方源，国内用户有时候会遇到下载速度慢或者超时的情况。遇到这类问题，处理办法很简单，就是换成镜像源。比如用npmmirror（原来叫cnpm）的源：
npm config set registry https://registry.npmmirror.com提示：切换镜像源只影响npm拉包的速度，不影响工具本身的功能和后续的API调用。如果在访问Google相关服务本身有问题，那属于另外一类问题，不在本文讨论范围内。
这三件事确认完之后，环境就算准备好了。这里顺便说一句自己踩过的坑：我曾经在一台老旧的Linux服务器上直接npm install，结果编译原生模块时报了python版本过低的问题——Gemini CLI依赖的某些模块在安装时会触发node-gyp编译，而这个编译过程需要python环境。所以如果安装过程中出现gyp相关的报错，检查一下python是不是2.x的老版本，或者系统里压根没装python，装个python3就能解决。
2 安装方式选择：一条命令安装与源码构建的取舍
Gemini CLI的安装有两条主流路线。一条是直接用npm全局安装，一条是从源码仓库构建安装。两条路线各有适用场景，我的建议是：绝大多数人用前者，想改源码或者想跟踪最新开发版的人用后者。
npm全局安装的优势是省事、命令短、依赖管理清晰。命令行执行：
npm install -g @google/gemini-cli装完之后gemini命令就全局可用了。-g参数是关键，表示全局安装，如果漏掉这个参数，命令只会装到当前目录下，shell里找不到。全局安装的包一般在系统级的node_modules目录下，macOS上如果用了nvm，路径会被nvm托管，不会出现权限问题；如果用系统自带的node，有时候会遇到EACCES权限错误，这时候用sudo执行或者修复npm全局目录权限，优先推荐后者，因为sudo会带来文件归属混乱的问题。
源码构建安装适合两类人：一类是想研究内部实现、想给项目做贡献的开发者，另一类是想要最新特性但npm包还没发布的尝鲜者。具体步骤是先克隆仓库：
git clone https://github.com/google-gemini/gemini-cli.git cd gemini-cli npm install npm run build npm linknpm link会把当前目录下的命令链接到全局，这样修改源码后，运行的就是本地版本。这个方式的代价是要处理构建过程中的依赖编译，同时仓库更新后本地要手动拉代码、重新build，维护成本更高。
从实际使用的角度，两条路线的效果没有本质差别。npm安装的版本经过了发布流程的验证，稳定性有保障；源码构建的版本可能会提前用上几天的新功能，但也可能遇到没被发现的bug。个人建议：日常使用选npm全局安装，除非你已经有明确的开发需求，否则不要为了“最新”两个字给自己增加维护负担。
还有一个细节值得单独说。安装之后务必确认一下npm的bin目录是否在PATH环境变量里。npm全局安装的命令都会放在一个bin目录下，macOS和Linux上这个目录通常是：
$(npm prefix -g)/bin查看npm的全局bin路径，可以执行：
npm bin -g如果gemini命令报“command not found”，大概率就是bin目录不在PATH里。解决办法是把它加到shell配置文件的PATH里。macOS的zsh配置文件是~/.zshrc，Linux常见的是~/.bashrc，添加一行：
export PATH="$(npm prefix -g)/bin:$PATH"然后source一下配置文件，命令就认识了。
3 macOS与Linux的安装实操记录
光讲理论不落地不行，这一节我们把macOS和Linux分开来看，把实际执行过程中容易忽略的操作细节掰开揉碎讲清楚。
3.1 macOS上的完整流程
macOS的终端默认是zsh，这点和Linux上常见的bash不同，但不要紧张，大部分命令在两个shell下通用。我的整洁操作序列是：先确认基础环境，再切换Node版本，最后安装Gemini CLI。实际执行如下：
node -v echo $SHELL确认SHELL是/bin/zsh后，确保nvm已经加载到当前终端。新开的终端窗口里，nvm可能没有自动加载。如果执行nvm提示command not found，先执行：
source ~/.zshrcnvm就位后：
nvm install 20 nvm use 20 npm install -g @google/gemini-cli这里补充一个细节：macOS从Catalina开始引入了notarization机制，从网络下载的未签名工具有时候会被Gatekeeper拦一道。如果是通过npm安装的包，一般不会触发这个限制，因为npm是在用户目录下操作的；但如果是下载的独立二进制文件，可能需要手工放行。npm方式基本遇不到这个问题。
安装完成后验证：
gemini --version如果能输出版本号，说明安装成功。Apple Silicon芯片的Mac（M1/M2/M3）上，因为Node.js已经有arm64原生版本，不需要Rosetta转译，安装过程很流畅。我在M2的MacBook上实测，整个安装流程不到一分钟就能完成。
3.2 Linux上的完整流程
Linux发行版之间差别较大，这里以Debian系和Ubuntu作为典型来演示，因为它们的使用面最广。如果你的系统是RHEL系（比如CentOS、Fedora），用dnf或yum装Node，思路完全一致。
Linux上我更推荐先装nvm再装Node的方式，因为很多系统的软件源更新不及时，官方源里的Node版本往往落后好几个大版本。比如某些LTS版的Ubuntu默认源还停留在Node 12或14，这在今天已经太过时了。用nvm可以绕开系统源的限制：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 npm install -g @google/gemini-cli如果你是Linux新手，完全没有Node环境，也没有nvm，直接让系统包管理器来装也不是不行：
sudo apt update sudo apt install nodejs npm gemini --version这样装完就能识别命令。不过要提醒一句，系统包的global安装路径是/usr/lib/node_modules，后面用npm install -g装别的包或者升级版本时，常常需要sudo权限。Linux上sudo操作多了之后，文件归属会变得混乱——根用户装了一部分包，普通用户又装了一部分，排查问题时容易头大。所以这里的个人建议和前面保持一致：优先nvm，别跟系统包管理员混着玩。
Linux还有一个特殊情况是服务器场景。很多人的Linux服务器是无图形界面的纯净环境，没有显示器没有桌面。Gemini CLI本身是纯命令行工具，天然适配这种环境，不需要显示器。但要注意的是，服务器上缺少一些共享库时，Node的某些原生依赖可能装不上。常见的比如build-essential（包含gcc、make等编译工具链），在最小化安装的服务器上要先装上：
sudo apt install build-essential装好之后再执行npm install -g @google/gemini-cli，就不会因为缺编译器而卡在node-gyp的步骤上了。
3.3 两种平台安装后的通病：PATH问题
macOS和Linux在安装完命令行工具后，最常见的通用问题就是PATH。前面我提到过用npm bin -g查看bin目录，这一步值得单独强调。不同的Node安装方式，bin目录的差异很大：
| Node安装方式 | 全局bin目录 | PATH自动配置 |
|---|---|---|
| nvm | ~/.nvm/versions/node/vX.Y.Z/bin | 自动 |
| 系统包管理器（Linux） | /usr/bin 或 /usr/local/bin | 自动 |
| 官方pkg安装包（macOS） | /usr/local/bin（Intel）或/opt/homebrew/bin（M系列） | 部分自动 |
| Homebrew Node（macOS） | /opt/homebrew/bin（M系列）或/usr/local/bin（Intel） | 自动 |
注意第三行：官方pkg安装包在Apple Silicon上默认装到/opt/homebrew/bin，如果你同时还装了Homebrew，这个路径已经在PATH里；如果你没有装Homebrew，就要手动加。这个场景我遇到过不止一次，确认PATH配置是否正确的方法是执行：
which gemini这个命令会显示gemini命令的真实路径。如果返回not found，就按上一节的方法把bin目录加进PATH。
4 配置API密钥与初始化设置
安装完成之后，不是直接就能用，Gemini CLI需要配置API密钥才能调用模型接口。这一步坑也不少，单独开一节来讲。
Gemini CLI的API密钥需要从Google AI Studio获取。具体流程是：打开AI Studio页面，找到API Key的创建入口，创建一个新密钥，复制保存。密钥是一长串字符，形如AIzaSy...这样的格式。获取过程这里不展开，如果这一步有障碍，说明你的网络环境不适合使用该服务，也建议先解决网络问题（如果有）再继续后续步骤。
拿到密钥之后，Gemini CLI提供了两种配置方式。
第一种是交互式配置，直接终端里运行：
gemini setup它会引导你选择用哪个模型、是否开启输入历史、是否反馈使用数据等选项。走到API密钥那一步时，把密钥粘贴进去就行。这种方式的优点是全自动写入配置文件，不用关心配置文件在哪，适合第一次使用的人。
第二种是手动设置环境变量。Gemini CLI支持通过环境变量传递API密钥，适合在CI/CD或脚本场景中使用：
export GEMINI_API_KEY="你的密钥"环境变量方式的好处是灵活性高，可以在不同项目间切换不同密钥，不需要每次去改配置文件。但注意环境变量只在当前终端会话里生效，关闭终端就没了。如果想永久生效，把它写进shell配置文件：
echo 'export GEMINI_API_KEY="你的密钥"' >> ~/.zshrc source ~/.zshrcLinux同理，只是配置文件换成~/.bashrc。
关于配置文件的存放位置：Gemini CLI的配置文件在用户主目录下的.gemini文件夹里。可以使用：
ls ~/.gemini来查看配置内容。如果你换了电脑或者想备份配置，把这个目录打包带走即可。安全性方面，妥善保管这个文件夹，因为里面包含了API密钥的明文。API密钥是带计费功能的，泄露了可能被别人盗刷额度。
这里有一个非常实用的配置技巧：不需要只依赖一个全局密钥。Gemini CLI支持在配置里指定多个模型，不同模型可以绑定不同密钥。比如在日常使用中用默认模型，在批处理任务中用另一个模型。配置文件的models字段可以定制这些映射关系。不过新手入门阶段，一个默认密钥就够了，进阶玩法后面再研究。
验证API密钥是否配置成功，最简单的办法是运行一个最简单的请求：
gemini "写一句简短的问候语"如果终端返回了模型的回复，说明从安装到配置的整条链路已经全部打通。如果提示401或无效密钥，大部分原因是密钥复制的时候多了空格，或者密钥本身过期。重新拿密钥，再保证复制时没有多余字符，基本就能解决。
5 验证安装与常用操作梳理
配置完成之后，日常的使用方式决定了这个工具体验好不好。这一节先做一个安装健康检查，再梳理一下日常使用频率最高的几个操作模式。
5.1 安装后的功能自检清单
建议安装后依次执行以下命令，确认每一项功能都正常：
gemini --help这条命令会列出所有可用的子命令和参数。看到输出内容代表gemini命令本身没问题。接着测试模型调用：
gemini "解释一下什么是TCP三次握手"能正常回答，代表API链路通畅。再测试文件交互：
gemini --input README.md "总结这份文档的要点"这个命令会把README.md的内容作为上下文交给模型，让它做总结。这个功能在日常处理文档时极其常用，如果这个命令报错，多半是文件路径写错了，或者当前目录下没有这个文件。
最后测试流式输出是否正常。流式输出就是模型像打字机一样逐字显示回复内容，体验上更接近聊天。Gemini CLI默认是流式输出的，如果你发现输出是一次性打印出来的，可能是终端模拟器兼容性的问题，一般换个终端（比如macOS的Terminal.app换成iTerm2）就能恢复正常。
5.2 四种高频使用模式
我平时用Gemini CLI，基本集中在这四种模式上。
一种是问答模式。直接把问题作为参数传给命令：
gemini "如何用awk提取日志里第3列的数据"这种模式最适合一次性疑问，不用打开聊天窗口，终端里顺手就问了。
一种是管道模式。把前面的命令输出通过管道喂给模型：
cat error.log | gemini "分析这个日志文件的报错原因"这个用法我觉得是CLI工具的杀手级功能。以前遇到线上日志报错，得把日志复制到聊天框里再粘贴，日志长了还截断，现在一条命令搞定，而且处理的是完整日志，不会遗漏关键上下文。类似的玩法还有：
ifconfig | gemini "帮我检查这台机器的网络配置有什么问题"第二种是文件处理模式。用--input参数指定文件，让模型读取文件内容再处理：
gemini --input 代码文件.py "解释这段代码的逻辑" gemini --input 论文.pdf "提取这篇文章的核心论点"这里补充一个细节：Gemini CLI对文本类文件的处理效果很好，但对PDF这类格式的解析是通过内置的文档处理能力实现的。如果遇到复杂的扫描版PDF，建议先转成文本再传给模型，准确率会更高。
第四种是交互模式。直接运行gemini不带任何参数，就进入交互式对话。这时候可以连续多轮对话，模型会记住上下文。适合需要来回讨论的场景，比如调试一个复杂问题、梳理一个设计方案的思路。退出交互模式按Ctrl+C或者输入exit。
5.3 参数定制的几个常用选项
Gemini CLI的命令参数有不少可调项，我觉得日常最值得记忆的有这几个。
--model指定模型。不同模型的能力和计费不同，比如默认模型适合日常问答，更强的模型适合复杂推理任务。想切换模型时：
gemini --model gemini-2.5-pro "解释一下量子纠缠"具体有哪些模型可选，运行gemini --help看完整列表。
--output指定输出文件。默认情况下回复打印在终端里，如果想保存到文件：
gemini "写一份周六团建活动的文案" --output 团建文案.md这样生成的内容会写入文件，方便后续编辑处理。我经常用来批量生成一些结构化内容——让模型生成markdown格式文档，直接落地成文件再用编辑器微调，效率很高。
还有一个值得提的--verbose参数，它会显示请求的调试信息，包括耗时、token使用量等。排查问题或者想统计API消耗的时候很有用。
6 常见问题排查与避坑实录
这一节总结我在使用过程中遇到的和从朋友那里收集到的问题。Gemini CLI整体上安装简单，但环境差异会带来各种奇怪问题。下面整理成速查表，按错误现象、可能原因、解决办法的组织方式呈现，方便直接查阅。
6.1 问题速查表
| 错误现象 | 可能原因 | 解决办法 |
|---|---|---|
command not found: gemini | 全局bin目录不在PATH中 | 执行npm bin -g，把输出目录加入PATH |
EACCES: permission denied | npm全局目录权限不足 | 用nvm管理Node；或修复npm目录权限，避免直接用sudo |
engine node >=16警告 | Node版本太旧 | 安装Node 20或更高版本，推荐用nvm管理 |
GEMINI_API_KEY is not set | 环境变量未配置或拼写错误 | 配置环境变量或运行gemini setup，确保变量名全大写 |
401 Unauthorized | API密钥无效 | 检查密钥是否完整，是否含有空格，是否过期 |
gyp ERR!编译报错 | 缺少python或编译工具链 | Linux安装build-essential；检查python3已安装 |
| 输出乱码或终端卡顿 | 终端编码或模拟器兼容问题 | 确认终端UTF-8编码；尝试更换终端模拟器 |
| 加载缓慢或超时 | 网络请求延迟 | 启用环境变量代理等，但这超出本安装指南的讨论范围 |
6.2 三个容易被忽略的隐性问题
除了上表列出的显性问题，还有三个比较隐蔽的情况，平时不一定会遇到，遇到了一时半会儿还真查不出来。
第一个是nvm切换Node版本后，全局包“丢失”的问题。nvm的全局包是按Node版本分别安装的——你用Node 18装的Gemini CLI，切换到Node 20之后就找不到了，这不是没装好，而是版本切换后全局包路径变了。解决办法是切到对应Node版本后，重新npm install -g @google/gemini-cli。如果希望所有版本都能用同一个全局包，可以开启nvm的symlink功能，把全局包目录链接到公共位置，但这操作相对进阶，日常使用我建议还是切完版本再装一遍全局包，十几秒的事。
第二个是shell初始化文件里重复source nvm导致的环境变量覆盖。有些人的~/.zshrc里既写了nvm的初始化脚本，又写了其他环境管理工具的初始化脚本，同时系统aliases又对node做了包装，这些叠加在一起，可能让npm的PATH解析出现偏差。症状表现为which node和which npm指向了不同的目录，gemini安装后找不到Node。排查方式很直接：
which node which npm which nvm如果三个路径不在同一个体系下，就检查shell配置文件里相关的初始化语句，清理掉重复的部分。
第三个是终端代理配置影响API访问的问题（如有）。虽然这超出了安装指南本身的范畴，但由于命令行工具经常在服务器上使用，如果机器的网络环境特殊，可能会遇到网络连接类的错误。这类问题需要结合具体的网络环境与工具本身的使用文档来判断，谨记遵守相关法规与平台服务的条款。
6.3 卸载与重装的正确姿势
如果遇到版本冲突或者想彻底重装，有一个干净的卸载流程值得记住。直接npm uninstall -g @google/gemini-cli能移除命令本身，但不会删除配置文件。如果还想把配置也清掉：
rm -rf ~/.gemini配置文件删除后，下次运行gemini setup就是完全干净的状态。这个技巧在排查问题时很实用——有时候改配置改坏了，与其找原因，不如直接重置来得快。
另外值得一提：如果怀疑是npm缓存导致安装异常，执行：
npm cache clean --force这会把npm的本地缓存全部清空，下一次安装会重新拉取所有包。这个操作不影响到已经装好的包，但会重新构建缓存，所以首次安装速度会略慢。不要一出现问题就清缓存，它更适合用在国内源切换后安装异常、或者明明远程有新版本地却安装旧版这类情况。
7 写在最后的经验心得
Gemini CLI让我真正感到舒服的一点，是它把AI能力无缝嵌进了终端工作流。以前写脚本遇到不会的函数，切到浏览器去搜，之后还得切回来，来回几次思路全断了；现在直接在终端把问题抛给模型，看到答案就地实验，整个思维链路保持连续，效率提升是实打实的。
在安装这件事上，最关键的体会是：不要被一条命令搞定一切的说法迷惑。虽然npm install -g @google/gemini-cli确实能完成安装，但前面几步的环境检查和对PATH的确认，才是决定体验好坏的隐藏变量。我自己的流程固定下来之后，新机器装Gemini CLI的耗时基本上在三分钟以内，而且装完就能直接进入干活状态，不需要反复排查报错。这个流程各位可以直接当成模板用。
最后再分享一个小技巧：Gemini CLI配合alias可以玩出很多花样。我在shell配置里加了几行自定义alias，比如让ai直接进入交互模式，让ai-do用更详细的模式输出结果，这些不仅缩短了敲命令的时间，也让工具更贴合自己的使用习惯。等你把基础安装和配置跑通之后，不妨也往这个方向琢磨琢磨，工具才能真正长成你自己的样子。
