1. Windows平台安装Gemini CLI的完整指南作为一款新兴的命令行工具Gemini CLI在开发者社区中逐渐流行起来。不同于Linux/macOS系统Windows平台安装这类工具往往会遇到各种环境问题。今天我就结合自己多次踩坑的经验分享一套完整的Windows安装方案。提示本文基于Gemini CLI 1.2.3版本验证适用于Windows 10/11系统。安装前请确保已关闭所有杀毒软件实时防护功能。1.1 环境准备要点首先需要检查系统基础环境打开PowerShell输入$PSVersionTable查看版本要求PowerShell 5.1Win10默认版本建议升级到PowerShell 7.x获取更好体验执行[System.Environment]::OSVersion确认系统版本需要Windows 10 1809或更高版本检查.NET Framework版本输入reg query HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full /v Release要求4.7.2对应注册表值≥461808如果缺少必要组件建议通过以下方式安装PowerShell 7使用winget工具安装winget install --id Microsoft.PowerShell.NET Framework通过官方离线安装包部署1.2 安装方式对比Windows平台主要有三种安装方式方式命令优点缺点Wingetwinget install gemini-cli自动处理依赖版本可能滞后Scoopscoop install gemini环境隔离需先安装Scoop手动安装下载zip解压版本可控需手动配置PATH个人推荐使用Scoop安装能有效避免污染系统环境。若已使用Chocolatey等其它包管理器建议保持统一。2. 详细安装步骤解析2.1 通过Scoop安装推荐首先安装Scoop包管理器Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex添加extras仓库包含Gemini CLIscoop bucket add extras安装核心依赖scoop install git 7zip正式安装Gemini CLIscoop install gemini安装完成后执行gemini --version验证。如果报错无法加载模块需要执行Set-ExecutionPolicy Unrestricted -Scope CurrentUser2.2 手动安装方案从GitHub Releases下载最新zip包解压到C:\Tools\Gemini目录建议路径配置系统环境变量[System.Environment]::SetEnvironmentVariable( PATH, [System.Environment]::GetEnvironmentVariable(PATH, [System.EnvironmentVariableTarget]::User) ;C:\Tools\Gemini, [System.EnvironmentVariableTarget]::User)重启终端后验证安装重要手动安装时需要额外处理VC运行库依赖建议安装最新版Visual C Redistributable3. 常见问题排查指南3.1 证书验证失败错误现象SSL certificate problem: unable to get local issuer certificate解决方案临时方案不推荐$env:GEMINI_SSL_NO_VERIFYtrue永久方案下载cacert.pem文件设置环境变量$env:SSL_CERT_FILEC:\path\to\cacert.pem3.2 中文乱码问题在传统cmd窗口可能出现中文乱码推荐解决方案改用Windows Terminal执行chcp命令切换编码chcp 65001修改注册表永久生效Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage -Name OEMCP -Value 650013.3 代理配置异常如果需要通过代理访问配置方法如下$env:HTTP_PROXYhttp://127.0.0.1:8080 $env:HTTPS_PROXYhttp://127.0.0.1:8080注意在PowerShell中需要使用$env:语法而不是Linux风格的export命令。4. 进阶配置与优化4.1 命令自动补全启用PowerShell的预测性补全功能Set-PSReadLineOption -PredictionSource History Set-PSReadLineOption -PredictionViewStyle ListView对于更完善的补全支持可以安装PSReadLine模块Install-Module -Name PSReadLine -Force -AllowClobber4.2 性能调优修改Gemini的缓存配置提升响应速度创建配置文件~/.gemini/config.toml添加以下内容[cache] enabled true directory C:/Temp/gemini_cache max_size 1GB4.3 日志调试遇到异常时可以通过日志排查问题$env:GEMINI_LOG_LEVELdebug gemini your-command 2 gemini_debug.log日志会记录详细的API请求和响应信息适合开发调试使用。5. 安全最佳实践密钥管理不要将API密钥硬编码在脚本中使用Windows凭据管理器存储敏感信息cmdkey /generic:gemini_api /user:key_name /pass执行策略Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这能在安全性和便利性间取得平衡定期更新scoop update; scoop update gemini或手动检查GitHub Releases页面我在实际使用中发现Windows平台最大的挑战是环境隔离问题。建议为每个项目创建独立的虚拟环境python -m venv .venv .\.venv\Scripts\activate这样可以避免不同项目间的依赖冲突。
Windows安装Gemini CLI完整指南与问题排查
1. Windows平台安装Gemini CLI的完整指南作为一款新兴的命令行工具Gemini CLI在开发者社区中逐渐流行起来。不同于Linux/macOS系统Windows平台安装这类工具往往会遇到各种环境问题。今天我就结合自己多次踩坑的经验分享一套完整的Windows安装方案。提示本文基于Gemini CLI 1.2.3版本验证适用于Windows 10/11系统。安装前请确保已关闭所有杀毒软件实时防护功能。1.1 环境准备要点首先需要检查系统基础环境打开PowerShell输入$PSVersionTable查看版本要求PowerShell 5.1Win10默认版本建议升级到PowerShell 7.x获取更好体验执行[System.Environment]::OSVersion确认系统版本需要Windows 10 1809或更高版本检查.NET Framework版本输入reg query HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full /v Release要求4.7.2对应注册表值≥461808如果缺少必要组件建议通过以下方式安装PowerShell 7使用winget工具安装winget install --id Microsoft.PowerShell.NET Framework通过官方离线安装包部署1.2 安装方式对比Windows平台主要有三种安装方式方式命令优点缺点Wingetwinget install gemini-cli自动处理依赖版本可能滞后Scoopscoop install gemini环境隔离需先安装Scoop手动安装下载zip解压版本可控需手动配置PATH个人推荐使用Scoop安装能有效避免污染系统环境。若已使用Chocolatey等其它包管理器建议保持统一。2. 详细安装步骤解析2.1 通过Scoop安装推荐首先安装Scoop包管理器Set-ExecutionPolicy RemoteSigned -Scope CurrentUser irm get.scoop.sh | iex添加extras仓库包含Gemini CLIscoop bucket add extras安装核心依赖scoop install git 7zip正式安装Gemini CLIscoop install gemini安装完成后执行gemini --version验证。如果报错无法加载模块需要执行Set-ExecutionPolicy Unrestricted -Scope CurrentUser2.2 手动安装方案从GitHub Releases下载最新zip包解压到C:\Tools\Gemini目录建议路径配置系统环境变量[System.Environment]::SetEnvironmentVariable( PATH, [System.Environment]::GetEnvironmentVariable(PATH, [System.EnvironmentVariableTarget]::User) ;C:\Tools\Gemini, [System.EnvironmentVariableTarget]::User)重启终端后验证安装重要手动安装时需要额外处理VC运行库依赖建议安装最新版Visual C Redistributable3. 常见问题排查指南3.1 证书验证失败错误现象SSL certificate problem: unable to get local issuer certificate解决方案临时方案不推荐$env:GEMINI_SSL_NO_VERIFYtrue永久方案下载cacert.pem文件设置环境变量$env:SSL_CERT_FILEC:\path\to\cacert.pem3.2 中文乱码问题在传统cmd窗口可能出现中文乱码推荐解决方案改用Windows Terminal执行chcp命令切换编码chcp 65001修改注册表永久生效Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage -Name OEMCP -Value 650013.3 代理配置异常如果需要通过代理访问配置方法如下$env:HTTP_PROXYhttp://127.0.0.1:8080 $env:HTTPS_PROXYhttp://127.0.0.1:8080注意在PowerShell中需要使用$env:语法而不是Linux风格的export命令。4. 进阶配置与优化4.1 命令自动补全启用PowerShell的预测性补全功能Set-PSReadLineOption -PredictionSource History Set-PSReadLineOption -PredictionViewStyle ListView对于更完善的补全支持可以安装PSReadLine模块Install-Module -Name PSReadLine -Force -AllowClobber4.2 性能调优修改Gemini的缓存配置提升响应速度创建配置文件~/.gemini/config.toml添加以下内容[cache] enabled true directory C:/Temp/gemini_cache max_size 1GB4.3 日志调试遇到异常时可以通过日志排查问题$env:GEMINI_LOG_LEVELdebug gemini your-command 2 gemini_debug.log日志会记录详细的API请求和响应信息适合开发调试使用。5. 安全最佳实践密钥管理不要将API密钥硬编码在脚本中使用Windows凭据管理器存储敏感信息cmdkey /generic:gemini_api /user:key_name /pass执行策略Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这能在安全性和便利性间取得平衡定期更新scoop update; scoop update gemini或手动检查GitHub Releases页面我在实际使用中发现Windows平台最大的挑战是环境隔离问题。建议为每个项目创建独立的虚拟环境python -m venv .venv .\.venv\Scripts\activate这样可以避免不同项目间的依赖冲突。
