10 分钟跑通 Gemini CLI：Windows 11 安装避坑完整指南

10 分钟跑通 Gemini CLIWindows 11 安装避坑完整指南【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLI 是一款开源 AI 编程终端工具装好之后你能在命令行里直接提问、改代码、跑命令。这篇 Windows 11 教程带你从自检、临时体验、全局安装到装完验证全程 10 分钟跑通 Gemini CLI 安装顺手把常见报错一次性排掉。动手前先做三项自检先确认环境能省掉后面一半的报错。用 1 分钟核对下面三项检查项要求不达标怎么办Node.js20.0.0 及以上到 Node 官网装新版装完重开终端终端Windows Terminal内置 PowerShell 5.1 也可用用系统自带 PowerShell 即可权限普通用户权限即可遇到写入拒绝再开管理员终端以管理员身份重开 PowerShell版本不够是后面大多数怪问题的根源所以这一项最优先。执行下面这条命令确认版本node -v输出里出现v20或更高数字就可以继续往下走。官方对系统的完整要求可查仓库内的 安装文档。先用 npx 跑通一次不装任何东西第一次先用 npx 体验不用写任何安装配置。因为 npx 会把包下到本地缓存里直接启动关掉终端包还在但不会把命令注册进 PATH所以它只算临时体验不算安装。在任意目录输入npx google/gemini-cli你会看到什么第一次运行会先联网下载依赖进度条走完才出画面。接着是启动动画和大号 GEMINI 标志然后它直接要求你登录 Google 账户。选 Quickstart 或填 API Key 都行之后进入交互界面上方是欢迎提示底部是输入框可以用 引用文件状态栏显示当前目录和沙箱状态就像下面这样配置默认存在用户目录的.gemini文件夹关掉终端再进还在。体验满意的话下一步才值得做正式安装。正式落地一条命令全局安装记得重开终端决定长期用的话一条命令就完成安装npm install -g google/gemini-cli这条命令把 Gemini CLI 装进 npm 的全局目录。这里有个坑先说在前面npm 的全局 bin 目录在 Windows 上默认是%APPDATA%\npm你的终端启动时才会读取一次 PATH所以已经开着的窗口永远认不出gemini。装完别急着敲命令新开一个终端窗口再验证。如果新窗口里仍然提示命令未识别查一下全局路径对不对npm config get prefix输出的路径加\bin应该就在系统 PATH 里。不在的话把它追加进环境变量再重开终端。装完先做这三步验证装完别急着干活先花一分钟做三步验证把问题挡在后面。先确认版本号能读出来gemini --version看到类似0.59.0的输出说明 bin 注册成功。再确认功能参数齐全gemini --help能列出常用参数说明脚本本身没被环境拦。最后首次运行gemini完成认证它会自动打开浏览器让你登录 Google 账户选一次授权模式即可。令牌会存进 Windows 凭据管理器之后的会话直接复用不用再登。Windows 专属的两个坑现象、原因、一行修复Windows 上真正会卡住你的主要是下面两处。现象敲gemini报「无法加载文件 xxx.ps1因为在此系统上禁止运行脚本」。原因PowerShell 执行策略默认禁止运行脚本而gemini的入口是 .ps1 包装脚本。修复以管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser回车输入 Y 确认重开终端即可。这条只改当前用户不动整机策略影响面最小。现象之前登录过最近却反复弹认证。原因凭据管理器里的旧令牌失效或过期。修复打开「控制面板 → 凭据管理器 → Windows 凭据」删掉 gemini 相关条目再重新跑一次gemini登录。报错速查表遇到别的报错先查这张表再动手报错信息可能原因处理方法The term gemini is not recognized全局 bin 不在 PATH或没重开终端npm config get prefix核对路径追加进 PATH 后重开窗口Unable to load file ... ps1禁止运行脚本执行策略过严Set-ExecutionPolicy RemoteSigned -Scope CurrentUserunsupported engine或 Node 版本过低Node 小于 20升级 Node 20重开终端npm: command not foundNode 没装好或 PATH 缺 Node 路径重装 Node勾选加入 PATH 的选项反复弹出登录页凭据缓存失效清理凭据管理器旧条目后重新认证日常维护三件事更新建议每周跑一次npm install -g google/gemini-cli。npm 会重新解析最新版比npm update这类只更新顶层依赖的命令更可靠。如果项目之间要切换 Node 版本建议装 nvm-windows 做环境隔离不同项目的依赖和全局包互不干扰Gemini CLI 也跟着对应的 Node 环境走。换机器或重装系统前把用户目录的.gemini文件夹整个拷走再从凭据管理器导出 Google 相关凭据。认证和配置就都保住了。下一步到这里环境、安装、验证、排错都齐了。现在打开一个新 PowerShell 窗口输入gemini回车给它一个具体任务比如让它解释当前目录里的 README.md。跑通第一个任务就算正式上手了。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考