Windows上装命令行工具，很多场景是敲一条npm命令就完事，但Gemini CLI算是个例外——我帮人排查过好几次安装失败，最后发现坑都不在工具本身，而在Node版本、终端执行策略和Path环境变量这三件事上。这篇我把从零到能用的完整过程写下来，覆盖安装命令、登录授权、Windows专属报错排查、装完之后的进阶配置，希望它能在你往Windows里装Gemini CLI时，成为一份能直接照着做的操作手册。
适合刚接触命令行的新手，也适合那些在别的平台已经用过、但一到Windows就被各种环境问题卡住的老手。安装本身不复杂，真正耗费时间的往往是环境不一致导致的奇奇怪怪的报错，而这篇文章重点要解决的就是这类问题。
1. 装之前必须确认的三件事：Node版本、终端类型与Git依赖
1.1 Node.js版本是第一个拦路虎
Gemini CLI是构建在Node.js生态上的命令行工具，通过npm分发和安装。安装命令本身很简单，但大部分安装失败的根源集中在环境准备阶段，而不是命令本身。
打开终端，先执行两条命令看看底子：
node -v npm -v如果提示“不是内部或外部命令”，说明Node.js还没装；如果有版本号，注意查看Node主版本。目前建议使用20或22的LTS版本，最低也建议满足工具对Node版本的要求。版本太旧会在运行时直接报引擎不兼容，这类错误解释起来非常绕，不如一开始就装对。
Windows上管理Node版本，我建议用nvm-windows这类版本管理工具。它能让你在多个Node版本之间一键切换，不用每次重装系统级环境。为什么要折腾版本管理？因为很多前端工具链依赖特定Node大版本，今天为Gemini CLI装一个Node 22，明天其他项目要求Node 18，全局覆盖安装很容易“装一个坏一个”。用版本管理工具把不同版本隔离开，通过简单的切换命令来用，干净得多。
安装Node时还要注意勾选“Add to PATH”，或者确认安装器已经把npm路径写进系统环境变量。这一步漏掉的话，后面执行npm命令时会绕回环境变量问题，平白多花时间。
1.2 Windows下的终端：CMD并不是首选
Gemini CLI有一个交互式对话界面，支持彩色输出、多行输入。Windows上常见的终端有三种：老牌CMD、PowerShell、Windows Terminal。
CMD对ANSI颜色支持比较差，Gemini CLI在这种终端里输出时可能出现乱码或颜色丢失，交互体验打折扣；PowerShell功能更强，但默认执行策略会拦截某些脚本；Windows Terminal本质上是终端容器，可以承载PowerShell或CMD，显示效果和字体渲染都更好。
我的建议是统一用Windows Terminal跑Gemini CLI，底层用PowerShell。另外，中文Windows上如果出现输出乱码，可以在当前终端执行：
chcp 65001把代码页切到UTF-8，或者在Windows Terminal的设置里把默认代码页改成UTF-8。这一步不是安装的必需步骤，却能帮你省掉第一次看到乱码时的困惑。
1.3 Git到底装不装
Gemini CLI本身是纯Node工具，不装Git也能安装和运行。但如果你后续要用它来分析代码仓库、生成提交信息、或者在某个基于Git的目录里做代码审查，它会调用本地的Git命令。
所以我的标准是：平时写代码的人，先把Git装好，顺便得到Git Bash这个类Linux终端；如果只是拿它当普通问答工具，Git可以先不装，遇到相关提示再补。
装Git时有个隐藏点需要留意：安装向导里“Adjusting your PATH environment”那一项，要选第二项或第三项，确保终端里可以直接调用git命令，否则后续Gemini CLI调用Git时会提示找不到命令。
2. 安装全流程：从npm命令到第一次对话
2.1 一条npm命令完成安装
确认环境没问题后，在终端里执行：
npm install -g @google/gemini-cli解释一下-g参数：它表示全局安装。不加-g会把包装进当前目录，命令行也无法在任何位置调用，装完等于没装。
安装过程中会看到进度条和输出，出现added或changed这类字样，表示安装成功。安装完成后先验证包确实被npm纳管：
npm ls -g --depth=0列表里能看到gemini-cli，同时执行：
gemini --version能打印版本号，说明可执行入口没问题。如果npm本身版本太旧，安装前可以先升级一下npm：
npm install -g npm@latest这一步不是必须的，但如果安装时频繁出现依赖解析错误，可以考虑先把npm升到较新版本再重试。
2.2 登录与API Key：两种授权方式的取舍
直接执行gemini会进入首次运行引导。这里通常有两条路：
- 账号授权：终端会打印一个授权地址，在浏览器里打开后完成账号登录并联调授权，随后工具会把凭证写回本地。
- API Key方式：去Gemini API的官方后台创建Key，粘贴到终端完成绑定。
个人日常使用建议选账号授权，刷新凭证就存在本地，过期后重新授权一下就行；脚本、自动化任务、无头服务器环境则用API Key，它不依赖浏览器流程，可以写进环境变量，可复现性更好。
不管哪种方式，授权信息都会写到当前用户目录下以点开头的配置文件里。之后每次运行gemini就不再要求重复登录。
如果首次运行卡在授权后没有反应，大概率是终端到回调地址的端口被防火墙拦截，或者输入法/终端编码问题导致粘贴内容出现乱码。可以先手动复制完整授权码，而不是依赖自动跳转回填。
2.3 验证安装是否成功的三个参考指标
只看到版本号不等于能用，我一般按三个指标验证：
gemini --version能输出，验证可执行文件存在；- 执行初始化命令能进入交互配置流程，验证配置目录可写；
- 在对话界面随便问一句“你好”，能收到模型回复，验证认证、网络、模型接口全链路都通。
三个步骤全过，安装才算闭环。卡在第二步，多半是配置文件目录权限问题；卡在第三步，优先检查网络连通性和账号凭证是否还有效。
3. Windows专属踩坑实录：四个高频报错的完整排查链路
3.1 “不是内部或外部命令”：Path环境变量给我上了一课
报错现象是：
'gemini' 不是内部或外部命令，也不是可运行的程序很多人看到报错以为是安装失败，其实包装好了，是命令行找不到可执行文件。
Windows下npm全局可执行文件默认放在%APPDATA%\npm这个目录，比如C:\Users\你的用户名\AppData\Roaming\npm。系统PATH里如果没有这个目录，任何全局CLI都调不起来。
排查链路如下：
- 执行
npm prefix -g查看全局前缀目录； - 执行
echo %PATH%（CMD）或$env:PATH（PowerShell）确认PATH中是否包含该目录； - 如果没有，手动把目录追加到用户环境变量Path里；
- 关键一步：重开终端，再执行
gemini。
环境变量在进程启动时读取一次，不重开终端，改了也白改。
另外，Windows用户名如果含空格，比如C:\Users\Zhang San\，npm全局路径本身不会显示异常，但一些基于shell的配置脚本可能出问题。遇到奇怪的失败，先检查路径里有没有空格，这种问题定位起来最费时间。
3.2 PowerShell执行策略拦截：脚本无法运行的处理思路
在PowerShell里运行Gemini CLI相关初始化脚本时，可能遇到：
因为在此系统上禁止运行脚本...这是PowerShell的默认执行策略Restricted在拦截，和安全无关，纯粹是Windows的脚本策略。单独给当前用户放开即可：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的含义是：本地创建的脚本可以运行，从网上下载的脚本必须带可信签名。这个级别对普通开发者足够安全，不建议改成Unrestricted。
如果电脑上有组策略锁定，Set-ExecutionPolicy命令本身也会被拦。这时不要试图在本地硬改，直接用CMD跑，CMD不依赖PowerShell执行策略，或者用Windows Terminal里新建非PowerShell的终端配置，绕开限制但不破坏安全策略。
3.3 npm安装卡住不动：先分清网络问题还是缓存问题
npm install长时间停住不动，是Windows上最常见的安装失败场景。先别急着一遍遍重跑，按下面的链路判断：
第一步，执行npm config get registry看当前源。如果默认源距离很远，下载速度会非常慢，可以临时给这次安装指定一个离你网络更近的公共npm镜像源：
npm install -g @google/gemini-cli --registry=https://某个公共npm镜像地址第二步，验证网络连通性。用系统自带的网络工具访问源地址，能通再谈npm本身。
第三步，怀疑本地缓存损坏时执行npm cache clean --force，然后重试。
第四步，公司内网环境常见的是出站规则限制访问外网源，或者DNS解析异常。可以先试试能否把源换成内网已有的镜像，或者找管理员确认出站策略。
这里有个经验：npm装包时没有进度条，不代表进程死了，有些依赖解析阶段npm不做输出刷新。先给它几分钟，再决定要不要中断。
3.4 升级与重装时的隐形坑：C盘空间和版本切换
要升级Gemini CLI时执行：
npm update -g @google/gemini-cli升级本身不难，但Windows上有一个容易忽视的问题：npm全局包默认全部装在系统盘用户目录，装了几十个全局工具后会占好几个GB空间。查看已安装的全局包：
npm ls -g --depth=0清理缓存：
npm cache clean --force有人想通过npm config set prefix D:\npm-global把全局目录换到其他盘。这个操作可行，但所有全局包路径都会变化，后续用Node版本管理工具切换版本时可能找不到之前的全局包，需要重新安装一遍。
另一个常见场景：用版本管理工具切换Node版本后，gemini命令突然失效。这是正常的，因为全局包装在旧版本对应的目录里，切版本相当于换了个环境。在新版本下重新执行一次全局安装就可以解决。
4. 安装完成后的进阶配置：让Gemini CLI更顺手
4.1 模型与运行参数的调整
在交互界面里输入/help可以查看内置命令。从默认模型切换到其他可用模型、调整生成参数等操作，一般通过配置命令来完成。比如：
gemini config get gemini config set model 具体模型名配置会保存到用户目录下的配置文件里。参数调整的原则是按需来：创意类任务可以把temperature调高，让输出更有随机性；代码生成、事实问答则调低一些，减少“一本正经地胡说八道”的概率。
这部分我个人的体会是：不要一开始就追求复杂参数组合，先跑通默认配置，再根据回复质量一点点调整，效果更可控。
4.2 多身份与多项目的配置管理
实际使用中，代码项目用一套凭证、日常问答用另一套凭证，是很有必要的。
做法上，除了在CLI里注册凭证外，还可以通过环境变量在调用时指定身份，这样同一个终端配合不同环境变量，就是不同身份。如果配置文件支持分层覆盖，也就是用户级全局配置加当前目录本地配置，可以在项目根目录放一份本地配置，只在该项目下生效。这个思路和Git的全局配置、仓库配置两级结构很像。
分层配置最大的价值不只是省事，更是防止把A项目的凭证带到B项目里产生误用。
4.3 卸载、重装与凭证清理
卸载命令：
npm uninstall -g @google/gemini-cli但卸载不等于干净。用户目录下的配置文件默认不会自动删除，里面可能存着登录凭证、API Key等敏感信息。彻底清理我会做三步：
- 卸载npm全局包；
- 删除用户目录下的配置目录；
- 如果要重装，先重开终端再安装。
重装后如果报一些陈旧配置相关的错误，先看是不是上一步没清理干净。凭证失效也一样，重新登录或重新生成Key即可。
最后聊点个人的操作习惯。第一次装这类命令行工具时最容易犯的错是：不看环境，直接抄一条npm命令就开跑，然后被各种环境变量报错消耗时间。Windows和macOS、Linux最大的差异就在PATH、执行策略、代码页这些东西，它们本身不难解决，但问题出现时要能联想到是环境问题而不是工具问题。
一个小技巧：把node -v、npm -v、npm prefix -g三条命令的输出截一张图，遇到任何安装问题发给社区或同事，对方能在几秒钟内判断出你的PATH是否正常。这个习惯帮我省掉了大量来回确认版本的沟通成本。
按这套流程走下来，从零到能用最快往往只需要十几分钟，卡住的时间几乎都花在环境排查上。希望这篇教程能让你少走一点弯路。
