企业官网建设流程全解析

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

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

Gemini CLI 是一款开源 AI 编程终端工具，装好之后你能在命令行里直接提问、改代码、跑命令。这篇 Windows 11 教程带你从自检、临时体验、全局安装到装完验证，全程 10 分钟跑通 Gemini CLI 安装，顺手把常见报错一次性排掉。

动手前，先做三项自检

先确认环境，能省掉后面一半的报错。用 1 分钟核对下面三项：

版本不够是后面大多数怪问题的根源，所以这一项最优先。执行下面这条命令确认版本：

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登录。

报错速查表

遇到别的报错，先查这张表再动手：

日常维护三件事

更新建议每周跑一次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