先明确：Gemini CLI、API配置和数据库连接分别解决什么问题

Gemini CLI 是面向开发者和技术用户的命令行工具，常用于在终端中调用 Gemini 能力、辅助生成代码、分析项目文件或完成自动化开发任务。安装失败通常与 Node.js 版本、包管理器权限、网络访问质量、系统路径变量有关；API配置则主要涉及密钥、模型名称、调用地址和权限范围；数据库连接配置并不是 Gemini CLI 的必需项，而是当你的项目需要让 AI 辅助读取配置、生成查询语句、调试后端接口时，需要把数据库连接信息规范地放在项目环境变量中。

因此，排查时不要把所有问题混在一起。正确顺序应是：先确认本机运行环境，再安装 Gemini CLI，随后配置 Gemini API Key，最后在项目中整理数据库连接参数，并用最小化请求验证 API 是否可用。这样可以快速判断问题出在工具安装、密钥权限、项目配置还是数据库服务本身。

安装前环境检查

安装 Gemini CLI 前，建议先检查 Node.js 与 npm。打开终端，执行 node -v 和 npm -v。如果提示命令不存在，说明 Node.js 未安装或系统路径未生效。建议使用较新的 LTS 版本，避免旧版本导致依赖解析失败。macOS 和 Linux 用户还需要确认当前终端是否拥有写入全局 npm 目录的权限；Windows 用户应尽量使用普通英文路径安装 Node.js，避免中文路径、空格路径引发脚本解析异常。

如果公司或学校网络环境对外部包源有限制，可能出现下载超时、连接重置、依赖包不完整等现象。此时不要反复强行安装，应先确认 npm 源是否可访问，并清理缓存后重试。可执行 npm cache verify 检查缓存状态，必要时使用 npm cache clean --force 清理。清理后重新打开终端，避免旧环境变量继续影响安装。

Gemini CLI 安装步骤

常见安装方式是通过 npm 全局安装。终端执行 npm install -g @google/gemini-cli。安装完成后执行 gemini --version 或 gemini --help 检查命令是否可用。如果能看到版本号或帮助信息，说明命令已正确写入系统路径。

如果提示“permission denied”或“EACCES”，通常是全局目录权限不足。macOS 和 Linux 用户不建议随意使用最高权限长期安装开发工具，更稳妥的方法是通过 Node 版本管理工具重新配置用户级 npm 目录，或把 npm 全局包路径设置到当前用户目录。Windows 用户如果提示无法执行脚本，可检查 PowerShell 执行策略，也可以尝试使用“命令提示符”重新执行安装命令。

如果提示“command not found”但安装过程显示成功，通常是 PATH 未包含 npm 全局 bin 目录。可执行 npm config get prefix 查看全局安装路径，再确认该路径下的可执行文件目录是否加入系统环境变量。修改环境变量后必须重新打开终端，否则新配置不会生效。

API Key 配置方法

Gemini CLI 需要通过 API Key 或账户授权来访问模型能力。对于本地项目，建议使用环境变量保存密钥，不要把密钥写入代码文件、提交记录或截图中。常见做法是在项目根目录创建 .env 文件，写入 GEMINI_API_KEY=你的密钥，并确认 .gitignore 已包含 .env。

在 macOS 或 Linux 的当前终端会话中，也可以临时执行 export GEMINI_API_KEY="你的密钥"。Windows PowerShell 可使用 $env:GEMINI_API_KEY="你的密钥"。临时变量只在当前窗口有效，关闭后需要重新设置；长期使用则应配置到系统用户环境变量中。

配置后可执行 Gemini CLI 的帮助命令或简单对话命令进行验证，例如让工具返回一段简短文本。如果报“API key not found”，说明环境变量名称不匹配或终端未重新加载；如果报“permission denied”或“quota exceeded”，则需要检查密钥权限、项目额度和模型可用范围；如果报模型不存在，通常是模型名称拼写不正确或当前账号未开通对应模型。

数据库连接配置思路

数据库连接参数应由你的应用程序读取，而不是直接交给 Gemini CLI。推荐把连接配置放在 .env 中，例如主机地址、端口、库名、用户名、密码、连接池大小等。常见字段包括 DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD。如果使用 PostgreSQL、MySQL 或 SQLite，字段含义会略有差异，但原则一致：配置与代码分离，敏感信息不入库，不在聊天记录里暴露完整连接串。

以 Node.js 项目为例，应用启动时可通过 dotenv 读取环境变量，再由数据库驱动创建连接。测试连接时，不要一开始就运行复杂查询，先执行最小化检查，例如连接成功后读取当前时间、数据库版本或一张测试表的少量记录。这样可以排除账号权限、端口、服务状态、库名拼写等基础问题。

如果希望让 Gemini CLI 辅助排查数据库问题，可以提供脱敏后的配置结构、错误信息、表结构片段和目标需求，不要提供真实密码、生产地址和完整业务数据。较安全的提问方式是：“这是脱敏后的连接配置和报错，请判断可能原因”，而不是直接粘贴完整连接串。

API 调用测试步骤

第一步，确认环境变量已加载。在终端中检查变量是否存在，但不要把完整密钥展示给他人。第二步，使用最小请求测试 Gemini API。可以通过 CLI 发起一次简单问题，例如要求返回“连接测试成功”这类短文本，观察是否能收到响应。第三步，测试项目代码中的调用逻辑，确认 SDK、模型名称、超时时间和异常捕获都已配置。第四步，再把 AI 调用与数据库读取流程串联起来，例如先从测试表读取一条非敏感数据，再交给模型生成摘要。

测试时建议把日志分层：安装日志、API请求日志、数据库连接日志分开记录。API日志中不要打印完整密钥；数据库日志中不要打印密码；业务日志中不要输出用户隐私数据。若需要定位问题，可以记录请求时间、模型名称、状态码、错误类型和耗时，这些信息通常足够排查。

安装失败常见问题

问题一：npm 安装卡住或超时。优先检查 Node.js 版本和 npm 源可访问性，再清理缓存重试。不要同时打开多个终端重复安装，以免锁文件冲突。

问题二：安装成功但 gemini 命令不可用。重点检查 npm 全局路径是否加入 PATH。修改后重启终端，必要时重启编辑器或开发工具。

问题三：提示依赖版本冲突。可以升级 npm，删除旧的全局包后重新安装。若项目内已有同名依赖，注意区分全局 CLI 与项目依赖，避免在错误目录下排查。

问题四：API 调用返回鉴权失败。检查环境变量名称、密钥是否复制完整、当前终端是否生效、项目权限是否匹配。密钥发生泄露风险时，应立即作废并重新生成。

问题五：数据库连接失败。先确认数据库服务运行、端口开放、账号密码正确、目标库存在，再检查连接字符串格式。若本地能连而程序不能连，多半是环境变量未加载或运行目录不正确。

安全边界和实用建议

使用 AI 工具排查项目时，要把“可分享信息”和“敏感信息”分清。可以提供错误堆栈、脱敏配置、表结构样例、伪造数据和复现步骤；不应提供真实密钥、生产库密码、完整用户数据、内部接口凭据。团队协作时，建议建立 .env.example 文件，只放字段名和示例值，让成员自行填写本地配置。

对于新手，最稳妥的实践是先在测试项目中完成 Gemini CLI 安装和 API 调用，再接入真实业务项目。数据库也应优先使用测试库，确认查询、写入和异常处理都稳定后，再进入正式环境。任何会修改数据的操作，都要先备份、再小范围验证，并在代码中加入超时、重试和错误提示。

总体来看，Gemini CLI 安装失败并不复杂，关键是按层拆解：系统环境是否正常、CLI 是否可执行、API Key 是否生效、数据库配置是否被项目正确读取。只要每一步都用最小化测试验证，就能快速定位问题，减少无效重装和盲目改配置带来的风险。