在 VS Code 中安装与配置 Gemini CLI 的完整指南

前言

Gemini CLI 是由 Google 推出的命令行工具，主要用于本地与 Gemini 大语言模型进行交互与应用开发。通过该工具，开发者可以更便捷地调用 Gemini API，快速进行原型搭建、模型测试和脚本化操作。在实际安装过程中，由于系统环境或依赖版本不一致，常常会遇到各种问题，尤其是在 Windows + VS Code 的开发环境下。本文将基于个人实战经验，系统梳理 Gemini CLI 安装过程中可能遇到的常见报错及其解决方案，帮助读者顺利完成安装并运行。

1 安装 Gemini CLI

安装命令

要全局安装 Gemini CLI，只需在终端中执行以下命令：

npm install -g @googlegemini-cli

这个命令会将 Gemini CLI 安装到全局环境中，确保你可以在任何项目路径下通过 gemini 命令进行调用。然而，在执行过程中，开发者可能会遇到版本兼容性和脚本执行策略的限制问题，下面我们将逐一进行分析和解决。

2 报错一：NPM 或 Node.js 版本过低

2.1 报错信息解析

在执行安装命令时，如果出现如下提示：

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: 'undici\@7.11.0',
npm WARN EBADENGINE   required: { node: '>=20.18.1' },
npm WARN EBADENGINE   current: { node: 'v20.13.1', npm: '10.5.2' }
npm WARN EBADENGINE }

说明当前系统中安装的 Node.js 版本不满足 Gemini CLI 的最低依赖要求。Gemini CLI 依赖的某些核心库（如 undici）需要运行在 >=20.18.1 或 >=22.9.0 的环境中。

2.2 解决办法：使用 NVM 升级 Node.js 版本

如果你使用的是 NVM（Node Version Manager），可以通过以下命令快速切换或安装所需版本：

nvm install 20.19.0
nvm use 20.19.0

上面的命令表示安装并切换到 v20.19.0，该版本符合 Gemini CLI 的要求。如果你尚未安装 NVM，可参考 NVM for Windows 官方仓库 进行配置。

注意事项： 安装后可通过以下命令确认版本：

node -v
npm -v

建议确认 node 至少为 20.18.1，npm 为 10.x 以上。

3 报错二：Windows 系统禁止执行PowerShell 脚本

3.1 报错信息解析

首次安装成功后，在 PowerShell 中执行 gemini 命令时，可能会遇到如下错误提示：

gemini : 无法加载文件 D:\software\nvm\nodejs\gemini.ps1，因为在此系统上禁止运行脚本。
有关详细信息，请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。

这表明当前 Windows 系统的 PowerShell 执行策略阻止了脚本的运行，出于安全性考虑，默认状态下很多系统会禁止 .ps1 文件的执行。

3.2 解决办法

针对该问题，有两种解决方案，分别适用于临时会话和永久生效的场景。

方法一：临时更改执行策略（推荐）

此方法仅影响当前 PowerShell 会话，不会更改系统默认策略，也不会带来永久性风险。

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

执行后即可在当前窗口中运行 gemini 命令。关闭窗口后，执行策略会自动恢复为默认状态，适合开发者临时使用。

方法二：永久更改当前用户执行策略

如果你在本地经常需要运行此类脚本，且为个人设备，可以考虑修改当前用户的执行策略：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

该策略允许运行本地脚本，同时仍对远程脚本保留安全验证要求（需签名），是一种平衡安全性与使用便利性的方式。

策略类型	描述	是否推荐
Restricted	默认状态，不允许任何脚本运行	❌ 不推荐
Bypass	允许所有脚本运行，但仅在当前会话中生效	✅ 推荐
RemoteSigned	本地脚本无签名可运行，远程脚本需签名	✅ 推荐
Unrestricted	允许所有脚本运行，无需签名	❌ 不推荐

4 验证安装与运行效果

完成上述设置后，可以通过以下命令确认 Gemini CLI 是否正常运行：

gemini --help

若命令行输出 Gemini 的帮助信息，说明安装成功。你现在可以开始调用 Gemini 模型进行交互、构建插件或本地应用开发。

示例输出：

Usage: gemini [options] [command]Google Gemini CLI - Interact with Gemini LLM locallyOptions:-v, --version        output the version number-h, --help           display help for command
...

5 常见问题排查

5.1 gemini 命令无效或不是内部命令

如果终端提示 gemini 不是内部或外部命令，请检查以下事项：

• 是否已通过 npm install -g 安装
• npm root -g 的路径是否已加入系统环境变量
• 当前使用的终端是否为 PowerShell（建议避免在 CMD 中运行）

5.2 修改完执行策略仍然报错

可能是以管理员权限打开了 PowerShell，但实际执行策略并未应用。可尝试：

• 使用非管理员身份重新打开窗口
• 再次执行 Set-ExecutionPolicy 命令
• 或者尝试在 VS Code 的集成终端中执行相关命令

结语

Gemini CLI 是一个功能强大、适用于本地开发与快速迭代的工具，但其依赖的环境配置对新手并不友好，特别是在 Windows 系统下，涉及 Node.js 版本和 PowerShell 策略配置的问题比较常见。通过本文的详细指引，相信你已经能够顺利完成 Gemini CLI 的安装与配置，并开启强大的本地 AI 开发之旅。如果你在使用过程中遇到更多问题，欢迎在评论区交流探讨。