1. 先把话说清楚Gemini CLI 在 Windows 上到底能干什么我打开终端敲一行命令就能让一个 AI 直接落在命令行里帮我干活。这不再是网页对话框里一问一答的小打小闹Gemini CLI 是把 Gemini 的能力打包成了一个你可以在任何目录下直接执行的程序。简单说它就住在你的终端里你说“帮我看下这个日志为什么报错”它会读日志、分析异常再给你一段可以直接抄走的排查方案而不是只回一句“这个错误通常是因为 XX”。Windows 用户安装这个工具有点特殊。原因不复杂Gemini CLI 本身的官方安装流程虽然标注了三个平台但默认的文档逻辑基本是 macOS 和 Linux 的视角。到了 Windows 上会冒出一堆平时没人提的岔路PowerShell 的执行策略拦路、npm 全局目录权限不足、终端字体不支持彩色输出、环境变量的配置位置跟 Linux 完全不是一回事。这些东西单看都不是大问题但堆在一起会让第一次装的人很烦躁。我见过不少人折腾半小时还在第一步打转。这篇文章的目标就是让你照着走一遍十分钟内把 Gemini CLI 跑起来。我会从环境准备开始把三种安装方式全部过一遍再讲认证配置、日常使用和 Windows 上的常见坑。不管你是第一次接触命令行的新手还是已经装了但在排查问题应该都能在这篇里找到对应的段落。2. 安装前的三件套准备2.1 先确认 Windows 系统和终端环境Gemini CLI 对系统没有太离谱的要求Windows 10 的 64 位版本和 Windows 11 都可以。不过有一点我得说在前面请优先使用 Windows Terminal而不是老式的 conhost 窗口。虽然命令行工具本身不挑宿主但 Gemini CLI 在交互界面里用了不少 ANSI 彩色字符和表格渲染旧的终端窗口对这部分支持很糟糕字体会挤在一起显示效果基本没法看。Windows Terminal 不需要额外购买或破解直接在微软商店里搜“Windows Terminal”就能装。装完之后建议把它固定到任务栏后面所有命令都在这里面执行。顺手把默认终端改成 Windows Terminal打开软件按Ctrl ,进入设置在“启动”里把“默认终端应用程序”改成“Windows Terminal”。这个小动作后面会节省很多烦躁的时间。另外要留个心如果你用的是 Windows 11 的“终端预览”版本界面会有些变化但功能大差不差不影响。2.2 安装 Node.jsGemini CLI 的运行底座Gemini CLI 是用 Node.js 写成的工具所以环境里必须有一个可用的 Node.js 运行时。版本方面官方建议 Node.js 18 以上。我实际用下来Node 18 和 20 都跑得很稳但如果你机器上还是十几甚至更老的版本建议先升级因为新版 CLI 的依赖会明确要求更高的 Node 特性版本太老会在运行时报一类特别难查的语法错误。安装步骤其实没什么悬念去 Node.js 官网下载页找 LTS 版本Windows 安装包是.msi双击一路下一步。关键点是安装到“选择安装功能”那一步时确认勾选了“Add to PATH”。如果不勾后面在执行node、npm命令时会直接提示“不是内部或外部命令”虽然也能通过手动改环境变量补救但没必要给自己挖这个坑。装完以后把终端关掉重新打开执行node -v npm -v能正常打印出版本号就说明这一步已经完成。这里有一个很常见但容易被忽略的细节如果你在装 Node 之前就开着终端装完后那个终端里的 PATH 没有刷新直接执行上面两条命令照样会报错。解决办法就是彻底关闭终端窗口重新开一个。2.3 准备一个 Gemini API Key 或者备用登录账号安装本身是不需要登录的但真正启动 CLI 的时候它需要知道你是谁。Gemini CLI 支持两种认证方式一种是浏览器 OAuth 登录打开授权页面后登录你的 Gemini 账号另一种是用 API Key。对于后一种方式你需要到 Gemini 的 API 管理后台申请一个 Key。申请入口一般在你 Gemini 账号下的 API Keys 页面点“Create API key”会生成一串以AIza开头的内容。注意这个 Key 生成的时候就要复制保存好因为页面不会二次展示完整 Key丢了只能重新生成。那两种方式怎么选我个人的习惯是如果只是自己电脑上玩玩用浏览器 OAuth 最简单扫码或者点一下鼠标就完事不需要管理 Key但如果你要在多台机器、或者 CI/CD 这类自动化环境里用API Key 是必须的。而且后面我会讲API Key 模式可以通过环境变量让 CLI 自动读取运行起来更省事不用每次手动输。3. 三种安装方式逐个对比Gemini CLI 的安装方式不止一种每种适合的场景完全不同。我在这里把三种方式全部写清楚你可以按自己的实际情况选也可以把前两种当候补方案哪个顺手用哪个。3.1 全局安装 npm 包最主流也最推荐的方式最正统的安装命令是通过 npm 全局安装。很好理解就是把 CLI 当成一个全局可用的程序装到系统里之后你在任意目录下敲gemini都能调用它。在已经准备好 Node.js 的终端里执行npm install -g google/gemini-cli这个命令会从 npm 仓库拉取包并安装到全局目录。这里解释一下包名开头的google这是 npm 的“作用域包”机制等于把一个命名空间给了这个包避免跟第三方的gemini命名冲突。所以如果你在网上看到有人写npm install -g gemini那是另一个完全不同的工具别装错了。安装完成后先检查版本确认装好了gemini --version如果打印出了一个版本号说明安装成功。如果提示gemini 不是内部或外部命令基本都是 npm 全局目录没有进入 PATH 的问题我后面专门有一节讲怎么修。全局安装的优点是干净、直接gemini命令随处可用遇到问题也容易排查。缺点是全局目录里的包更新方式比较靠自觉需要你偶尔主动执行npm update -g google/gemini-cli来升级。对绝大多数 Windows 用户来说这就是首选方案。3.2 用 npx 临时运行适合还没想好要不要长期用的人如果你暂时不想往系统里装一个常驻的全局工具只是想先体验一下 Gemini CLI 的效果完全可以用 npx 直接启动。npx google/gemini-clinpx 是 npm 自带的工具执行器它的逻辑是如果本地没装这个包就临时下载到缓存里然后执行。这样你机器上不会残留一个全局的gemini命令属于“用完即走”的模式。但 npx 模式有两个明显的代价。第一每次执行如果缓存被清掉都会重新拉取一次完整的包耗时比直接执行全局命令长不少。第二包本身是缓存状态没法像全局安装那样随手升级版本控制会变得很被动。所以我的建议很明确这个方式适合第一次体验确定要继续用就一定切到全局安装。3.3 用 Bun 安装速度党可以试一试如果你已经在用 Bun 这个 JavaScript 运行时会发现用它装全局包速度非常快。命令如下bun add -g google/gemini-cliBun 的安装和启动速度都比 npm 快文件系统 IO 也更利落。但这里我必须说一句实话Bun 在 Windows 上属于“能用但不保证事事顺利”的阶段如果你装了 Bun 之后其他项目都正常那用它装 Gemini CLI 没问题但如果你的 Bun 本身测试环境还不成熟我不建议为了装这个 CLI 专门去折腾一个新运行时。工具的价值在于帮你干活不要在装工具的路上消耗太多体力。三种方式整理成一张表方便你参考安装方式命令推荐场景缺点npm 全局npm install -g google/gemini-cli日常主力使用需手动升级npx 临时npx google/gemini-cli首次体验、不想装全局每次可能重新拉包Bun 全局bun add -g google/gemini-cli已用 Bun 且运行正常Windows 下生态成熟度一般4. 首次运行与认证配置4.1 第一次输入 gemini 后会发生什么安装完成后在终端里敲gemini回车。第一次运行它会进入一个交互模式界面上会展示版本信息和欢迎提示。如果你的机器上没有配置过任何认证信息CLI 会进入登录流程。浏览器 OAuth 登录的体验比较顺滑CLI 会显示一个网址并询问你是否已经在浏览器里完成了授权。你需要在浏览器里打开那个网址使用你的账号完成确认然后把授权结果带回来。整个过程类似 GitHub CLI 或者很多云服务的 CLI 登录方式本质上就是让令牌跟本机的 CLI 绑定。如果你没有浏览器环境或者干脆不想用个人账号做授权那就按 API Key 的方式来。实际操作中我一般直接选择 API Key 路线因为在自动化脚本里它的行为更可预期而且 API Key 可以随时创建、随时撤销权限边界更清晰。4.2 用 API Key 完成认证两条路供你选拿到 API Key 以后有两条路可以把它交给 Gemini CLI。第一种是设置系统环境变量。在 Windows 11 / Windows 10 上右键“此电脑” → 属性 → 高级系统设置 → 环境变量。在“用户变量”区域点“新建”变量名填GEMINI_API_KEY变量值粘贴你的 Key一路确定保存。之后把终端重启Gemini CLI 启动时会自动读取这个环境变量。第二种是针对只想在当前终端会话临时使用的情况。直接在 PowerShell 里执行$env:GEMINI_API_KEY 你的 Key这种方式只在当前终端窗口有效窗口一关就失效适合临时换 Key 或测试多个 Key 的场景。如果你日常固定在某个项目里用还是用第一种方式一劳永逸比较省心。配置完成后重新运行gemini它会以你的 API Key 身份启动对话过程中不再要求登录。4.3 切换模型与确认运行状态认证不是唯一的初始化事项。Gemini CLI 默认会使用某个模型来回答但你可以通过环境变量GEMINI_MODEL指定其他模型。比如你想用某个擅长复杂推理的模型可以在环境变量里设GEMINI_MODELgemini-2.5-pro如果你只是想让每日的普通问答成本更低可以设成GEMINI_MODELgemini-2.5-flash这个变量的设置方法和GEMINI_API_KEY完全一样就不重复了。我第一次启动时踩过一次坑设好了GEMINI_API_KEY却发现 CLI 还是在走浏览器登录后来发现是因为设置完环境变量之后终端没有重启环境变量并没有被加载。这算是一个容易忽略但特别典型的 Windows 细节。所有环境变量的配置都必须在设置完以后重启终端才能生效这不是 Gemini CLI 的问题是 Windows 环境变量机制本身的行为。5. 日常使用的核心操作5.1 在终端里把它当技术参谋用装好 Gemini CLI 之后最直接的用法就是把它当成一个随叫随到的参谋。任何疑问直接以自然语言输入它会基于上下文回答。举个我自己的例子某天我在配置一个构建脚本终端报出一段很长的编译错误以前我会打开搜索引擎把错误信息复制进去然后在几个看起来差不多的网页之间来回折腾。现在直接在gemini的对话框里把错误信息复制进去然后补一句“帮我看这是什么原因”它会解析错误结构能拆出哪一行哪个库出了问题并给出可行的修复方案。这段效率上的提升非常明显因为问题上下文就在终端里不用来回切窗口。其他常见用法还包括解释一个冷门命令的参数、对比两个工具的思路、帮你回忆一段你写过但忘了放在哪的代码逻辑。它可以做的不是“背书式”解答而是在当前目录的上下文里理解你的问题。5.2 让它直面文件读写本地项目Gemini CLI 和普通网页聊天的最大区别是它默认能感知你运行时的当前目录可以读取目录里的文件、分析项目结构、甚至可以按你的指示写文件。比如我在某个项目目录下直接告诉它“看一下这个模块的代码结构帮我找出三个潜在的边界条件问题”它会先定位文件、读取内容、再给出分析。这跟把代码复制粘贴到网页上完全不是一个体感尤其当项目文件很多、跨模块调用复杂的时候让 CLI 直接操作文件系统会大幅减少你手工整理上下文的工作量。不过这里有一个使用技巧上的提醒它确实能听懂“帮我修改某文件”但修改文件前通常最好让它先说清楚改了哪几行、改动原因是什么确认后再动手。命令行环境里没有网页端的“应用变更”按钮一切以它的输出为准所以你保留一层人工确认会更稳。5.3 和 VS Code 里 AI 插件的互补有人问我IDE 里已经有各种 AI 插件了为什么还要装 Gemini CLI答案很简单因为终端的场景在 IDE 之外。你在本地仓库里跑测试、查日志、操作 Git 时那些时刻几乎都在终端里而 IDE 插件更多是围绕编辑器的提示和生成。如果有一个工具能直接在终端里理解你正在敲的东西你就不需要把命令输出复制回编辑器去问另一个 AI。我日常的习惯是给 Windows Terminal 设一个快捷键一键打开一个新标签页并自动运行gemini。配置方法不复杂在 Windows Terminal 的设置里新建一个配置文件命令行参数填cmd.exe /k gemini再把启动参数关联到这个配置文件。这样我任何时候想开一个 AI 对话窗口只要按一下快捷键终端就直接落在 Gemini CLI 的交互界面里。如果不配置快捷键一个标签页敲gemini也不会慢到哪去顺势为之就好。既然谈到了环境建议统一配置一个干净的提示符把gemini作为 Windows Terminal 独立标签页的默认启动命令后续切换上下文会比较自然。5.4 知道几个内置命令少走弯路进入 Gemini CLI 的交互界面后输入/help可以列出所有内置命令。有几个值得记一下/quit退出当前会话。/clear清空当前对话上下文重新开始。/model查看或者切换当前使用的模型。/status查看当前会话的认证状态和上下文信息。当你连续对话一段时间后上下文会变得很长回答质量和响应速度都会略有下降。这时候执行/clear清空上下文通常能让会话恢复到良好的状态。这和网页版聊天到一定程度主动开新会话是一个道理。6. Windows 上高频踩坑实录6.1 首次运行时报“禁止运行脚本”Windows 默认的 PowerShell 执行策略非常保守很多脚本和命令第一次运行就会提示“在此系统上禁止运行脚本”。这不是 Gemini CLI 特有的问题但第一次安装的人特别容易在这里蒙圈。解决办法是放宽当前用户的执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令的意思是允许本机脚本和已签名远程脚本运行但不需要管理员权限影响范围只限于当前用户。执行后如果系统询问是否要更改执行策略输入Y回车。设置完以后重新跑gemini通常就能正常启动。不用把策略改成UnrestrictedRemoteSigned 对日常使用已经完全够用。6.2 npm 全局安装时提示权限不足Windows 上执行npm install -g偶尔会报EPERM或者EACCES之类的权限错误。很多人第一反应是用管理员身份运行终端再来一次但我劝你尽量别这么干。以管理员身份运行会改变很多默认路径后面反而容易出现文件归属混乱的问题。更好的做法是把 npm 的全局目录指向当前用户目录下的一个文件夹npm config set prefix $env:APPDATA\npm再重新安装一次就不会再碰到必须提权的问题。这个配置改完以后记得检查一下%APPDATA%\npm是否已经加入了 PATH如果没加手工加上即可。6.3 输出乱码和中文字体显示错位Gemini CLI 的回显里会用到一部分特殊字符和彩色字体。Windows 默认终端字体在渲染某些 Unicode 字符时会出现方块或者错位尤其在表格类输出时最明显。我的建议是给 Windows Terminal 换一个等宽字体比如Cascadia Mono或者常见的Sarasa Mono。在 Windows Terminal 设置的“配置文件” → “外观” → “字体”里改。中文场景下某些字体需要额外指定 fallback如果字体不支持中文回显里的中文部分可能仍然显示成小方块。选了合适的字体后整体输出观感会完全不一样。顺带一提如果你在旧版控制台窗口里用chcp 65001这个命令可以把代码页切到 UTF-8缓解一部分乱码。但在 Windows Terminal 里一般不需要每次都做。6.4 网络波动导致的连接失败命令行工具没界面稍等一会儿提示碰不到服务是经常会遇到的事。这里先说清楚报错大多是网络层面的临时状况不代表安装坏了。遇到连接失败第一步可以先重新执行一次问句很多时候只是超时节奏的问题。如果反复失败建议做两个检查一是确认本机网络能正常访问外部站点排除断网二是看看是不是安全软件或者系统防火墙拦了终端进程的网络请求尤其是企业办公电脑上这类情况很常见。Windows Defender 本身一般不会拦但三方安全软件确实会。实在不行可以在 CLI 之外先确认一下网络直连状况再用/clear重新开始对话连接。这类问题没有太多黑魔法耐心重试十有八九能恢复。6.5 高频问题速查表现象原因解法gemini命令找不到npm 全局目录未加入 PATH配置 prefix 并把目录加入 PATH启动时报执行策略错误PowerShell 默认禁止脚本设置 RemoteSigned总是要求浏览器登录环境变量未加载重启终端后再试中文输出是方块终端字体不支持 Unicode换 Cascadia Mono 等字体请求频繁超时网络临时波动或安全软件拦截检查网络连通、重试对话久了回答变差上下文过长用/clear清理上下文7. 最后分享一点我自己的使用心得我在 Windows 上装 Gemini CLI 的时间不算短中间反复换过机器、重装过环境踩过的坑基本都写在前面了。如果只记住一句话那就是先确认 Node.js 环境和终端是否正常再想什么花活。这和很多命令行工具的道理是一样的环境是根。日常使用中我实际上用得最频繁的场景不是让它写一整套新功能而是让它“看一眼项目里正在出问题的那部分”。解释报错、分析日志、补一个正则、解释一个生僻的编译参数——这些散落在终端里的小事聚合起来节省的时间非常可观。你不需要把它当成一个程序员替身把它当成一个比你稍快的“检索器 概括器”会更顺手。它更擅长在你们俩共同的上下文里输出准确的东西上下文越充分答案越接近你的真实意图。装好之后建议你从自己手头真实存在的问题开始试而不是用那种“你是谁”的开场白测试。直接丢一段你没处理的报错过去你会马上感受到这个东西顺手不顺手。Windows 上的命令行生态这几年的进步其实很明显以前总感觉这类 CLI 工具在 Windows 上是二等公民但实际用下来只要环境和字体打理好体验跟其他平台没什么差距。剩下来要做的就是多问几个问题让这个终端里的新伙伴多帮你干点活。