Gemini CLI安装失败时，Windows和Mac用户需按错误代码精准排障：EBADENGINE等版本问题须升级Node至v20.19.0并用nvm切换；EACCES权限错误推荐改npm全局路径而非sudo；1603/0x80070005需修复注册表并重启；ENOTFOUND须检查DNS与代理注入；“命令未找到”则需将npm bin路径加入PATH。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Gemini电脑版安装失败时，Windows和Mac用户常遇到npm报错、环境变量失效、代理配置错误、权限拒绝等具体代码提示，比如EBADENGINE、1603、0x80070005、EACCES、ENOTFOUND，这些不是随机弹窗，而是系统在明确告诉你哪一环断了。
Windows平台npm安装报错：EBADENGINE或undici版本不兼容
这类错误多出现在Node.js版本低于v20.18.1时，Gemini CLI依赖的undici@7.11.0等包会直接拒绝加载。
第一步：检查当前Node版本，在PowerShell中运行 node -v，若显示v20.13.1或更低，必须升级。
第二步：使用NVM切换到合规版本——先运行 nvm install 20.19.0，再执行 nvm use 20.19.0。注意不要跳过nvm use这步，否则终端仍调用旧版本。
第三步：清除npm缓存并重装CLI，依次运行：npm cache clean --force → npm install -g @google/gemini-cli。跳过缓存清理可能导致旧版本残留包干扰安装。
Mac系统报错EACCES：全局安装权限被拒绝
Mac默认不允许向/usr/local/bin写入文件，npm全局安装Gemini CLI时会因权限不足报EACCES错误。
方法一（推荐）：改用nvm管理npm全局路径，避免sudo——先确保已安装nvm，再运行：echo 'export NPM_CONFIG_PREFIX=$HOME/.npm-global' >> ~/.zshrc → source ~/.zshrc → mkdir -p ~/.npm-global → 重新安装：npm install -g @google/gemini-cli。
方法二（慎用）：临时加sudo，仅限测试——sudo npm install -g @google/gemini-cli。但【后续所有gemini命令都必须加sudo才能运行，否则报command not found】，极易引发权限混乱，不建议长期使用。
Windows安装卡在1603或0x80070005
这两个错误本质相同：Windows Installer服务被禁用或注册表策略阻止MSI安装行为，常见于企业域控环境或中文用户名系统。
按Win + R输入regedit，以管理员身份打开注册表编辑器。
Windows 桌面自动化技能，支持鼠标控制（移动/点击/拖拽/滚轮/截图）、键盘输入（文字输入/按键/组合键）、窗口管理（查找/聚焦/最大化/最小化/关闭/移动）、截图并发送文件。提供两种截图方式：Python pyautogui 截图（集成在自动化流程中）和 PowerShell + .NET 零依赖截图（支持区域截图和多显示器）。当用户需要自动化 Windows 桌面操作、控制鼠标键盘、管理窗口、执行 GUI 自动化任务、截图发送文件时使用。
定位到HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\Installer，检查右侧是否存在DisableMSI项；若数值为1，双击改为0。若该项不存在，右键新建DWORD（32位）值，命名为DisableMSI，设值为0。
接着跳转至HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\msiserver，确认Start值为2（自动）。若为4（禁用）或缺失，右键新建DWORD，命名为Start，设值为2。
【修改后必须重启电脑，否则msiserver服务不会加载，1603错误依旧】。
Mac或Windows均出现ENOTFOUND / getaddrinfo ENOTFOUND api.google.com
这是网络层根本连不上Google API域名，不是密钥或配置问题，而是DNS或代理未生效。
在终端中先验证基础连通性：ping api.google.com。若显示“unknown host”，说明DNS解析失败，需更换DNS为8.8.8.8或114.114.114.114。
若ping通但gemini仍报ENOTFOUND，则大概率是代理未注入到当前终端会话——macOS用户需在shell配置文件（~/.zshrc）中添加：export HTTPS_PROXY=http://127.0.0.1:1082（端口按你本地代理实际填写）→ 运行source ~/.zshrc刷新。
Windows PowerShell用户请运行：$env:HTTPS_PROXY="http://127.0.0.1:1082"，然后关闭并**重新打开PowerShell窗口**，否则变量不生效。
安装成功但运行gemini命令提示“不是内部或外部命令”
说明npm全局bin目录未加入系统PATH，Windows和Mac表现一致，但修复路径不同。
Windows用户：在PowerShell中运行Get-Command npm | Select-Object -ExpandProperty Definition，找到npm全局路径（如C:\Users\XXX\AppData\Roaming\npm），将其添加进系统环境变量PATH中。
Mac用户：运行npm config get prefix，输出路径如/Users/xxx/.nvm/versions/node/v20.19.0，则将$HOME/.nvm/versions/node/v20.19.0/bin加入~/.zshrc的PATH声明里，再执行source ~/.zshrc。
