Win11 下 Gemini CLI 的安装与 Traefik 集成指南

1. 环境准备与Node.js配置

在Windows 11上玩转Gemini CLI的第一步，就是搭建好Node.js运行环境。我强烈推荐使用Node.js 18或更高版本，因为Gemini CLI的部分功能依赖较新的ECMAScript特性。安装Node.js时有个小技巧：不要直接点"下一步"到底，记得勾选"Automatically install the necessary tools"选项，这样会自动安装构建工具链。

很多新手容易忽略npm的全局安装路径问题。默认情况下，全局包会塞进C盘的AppData目录，不仅占用宝贵系统盘空间，还可能遇到权限问题。我的做法是在非系统盘（比如D盘）创建专用目录：

mkdir D:\Nodejs_global mkdir D:\Nodejs_cache

然后通过npm config命令修改默认路径：

npm config set prefix "D:\Nodejs_global" npm config set cache "D:\Nodejs_cache"

配置完成后，记得把D:\Nodejs_global添加到系统环境变量PATH中。这里有个细节：Windows 11的环境变量界面改版后，添加路径时要注意区分用户变量和系统变量。我建议在用户变量中添加，避免权限问题。完成这些操作后，运行npm config list应该能看到类似这样的输出：

; userconfig C:\Users\yourname\.npmrc cache = "D:\\Nodejs_cache" prefix = "D:\\Nodejs_global"

如果遇到EACCES权限错误，别急着用管理员权限运行，先试试这个命令修改目录权限：

icacls "D:\Nodejs_global" /grant "你的用户名":(OI)(CI)F

2. Gemini CLI安装与认证

环境准备好后，安装Gemini CLI就很简单了：

npm install -g @google/gemini-cli

但安装只是开始，真正的挑战在认证环节。由于Gemini CLI需要调用Google Cloud服务，必须完成OAuth认证。这里我踩过最大的坑就是PowerShell的curl命令别名问题。Windows默认把curl映射到Invoke-WebRequest，这会导致认证流程失败。解决方法有两种：

临时方案（每次打开新终端都需要执行）：

Remove-Item alias:\curl

永久方案（创建新别名）：

Set-Alias -Name gcurl -Value "C:\Windows\System32\curl.exe"

测试网络连通性时，建议使用这个命令：

gcurl -I https://accounts.google.com --connect-timeout 5

如果看到HTTP/2 200响应，说明网络正常。如果遇到TLS错误，可能需要检查系统时间是否准确，或者尝试更新根证书：

certutil -generateSSTFromWU roots.sst certutil -addstore -f root roots.sst

完成认证需要三个关键步骤：

1. 在Google Cloud控制台创建项目
2. 启用"Generative Language API"服务
3. 设置环境变量GOOGLE_CLOUD_PROJECT

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

认证成功后，运行gemini --version应该能看到版本号输出。建议首次使用时先试个简单命令：

gemini generate "用三句话介绍量子计算"

3. Traefik集成配置

把Gemini CLI集成到Traefik需要解决几个关键问题。首先是路径配置，Traefik默认不会继承系统PATH，需要手动指定Node.js环境。编辑Traefik的settings.json文件（通常在%APPDATA%\Traefik目录）：

{ "terminal.integrated.env.windows": { "PATH": "D:\\Nodejs_global;${env:PATH}", "NODE_PATH": "D:\\Nodejs_global\\node_modules" } }

对于容器化部署的场景，建议使用Docker volume将Node.js全局模块挂载到容器内：

volumes: - D:\Nodejs_global\node_modules:/usr/local/lib/node_modules

Traefik路由配置的核心是正确设置中间件。这是我的生产环境配置示例：

http: middlewares: gemini-auth: basicAuth: users: - "test:$apr1$xxxxxx" routers: gemini-api: rule: "PathPrefix(`/gemini`)" middlewares: ["gemini-auth"] service: gemini-service

性能调优方面，建议在Traefik中为Gemini接口添加速率限制：

http: middlewares: gemini-limit: rateLimit: average: 10 burst: 30

日志配置也很重要，可以单独记录Gemini的请求日志：

http: routers: gemini-api: entryPoints: ["websecure"] rule: "Host(`api.yourdomain.com`) && PathPrefix(`/v1/gemini`)" service: gemini-service middlewares: ["gemini-log"] middlewares: gemini-log: chain: middlewares: - "traefik-log@file" - "custom-log@file"

4. 常见问题排查

遇到认证卡在浏览器循环跳转时，首先检查时区设置。我在UTC+8时区遇到过这个问题，临时切换到UTC时区后解决。另一个常见错误是"MODULE_NOT_FOUND"，这通常是因为NODE_PATH没正确设置。可以通过以下命令验证：

node -e "console.log(require.resolve('@google/gemini-cli'))"

网络问题方面，如果遇到ETIMEDOUT，试试这个诊断流程：

1. 检查本地端口监听：netstat -ano | findstr "7890"
2. 测试直接连接：tcping google.com 443
3. 验证DNS解析：nslookup google.com

对于Traefik集成特有的403错误，重点检查：

• CORS配置是否正确
• 请求头是否包含Content-Type: application/json
• 请求体是否超过Traefik默认的4MB限制

内存泄漏也是个潜在问题。建议定期监控Node.js内存使用：

Get-Process node | Select-Object PM,WS,CPU

如果发现内存持续增长，可以在启动Gemini CLI时加上内存限制：

node --max-old-space-size=2048 $(which gemini) generate "你的提示词"

最后分享一个实用技巧：在Traefik日志中过滤Gemini请求：

Get-Content -Path "C:\path\to\traefik.log" -Wait | Select-String "gemini"