Gemini CLI故障排除指南

💡 快速诊断：大多数问题都可以通过重新启动 Gemini CLI 或检查网络连接来解决。

安装和启动问题

问题：命令未找到

症状：

bash

$ gemini
bash: gemini: command not found

解决方案：

检查 Node.js 版本：

bash

# 确保 Node.js 版本 20+
node --version

# 如果版本过低，更新 Node.js
# 访问 https://nodejs.org 下载最新版本

重新安装：

bash

# 全局安装
npm install -g @google/gemini-cli

# 或直接运行（推荐）
npx https://github.com/google-gemini/gemini-cli

检查 PATH 配置：

bash

# 查看 npm 全局 bin 目录
npm config get prefix

# 确保该目录在 PATH 中
echo $PATH | grep $(npm config get prefix)

问题：启动后无响应

症状：

CLI 启动但不显示欢迎界面
输入命令没有反应
进程卡住

解决方案：

bash

# 强制停止并重启
Ctrl+C  # 停止当前进程
gemini  # 重新启动

# 清除缓存
rm -rf ~/.gemini/cache/
gemini

认证和连接问题

问题：认证失败

症状：

Authentication failed. Please check your credentials.

解决方案：

Google 账户登录：

bash

# 重新进行认证
/auth

# 按提示在浏览器中完成登录
# 确保使用正确的 Google 账户

API 密钥问题：

bash

# 验证 API 密钥格式
export GEMINI_API_KEY="your-api-key"

# 确保密钥以 "AIza" 开头
echo $GEMINI_API_KEY | grep "^AIza"

# 重新生成密钥
# 访问 https://aistudio.google.com/apikey

Vertex AI 配置：

bash

# 检查 Vertex AI 环境变量
export GOOGLE_API_KEY="your-vertex-ai-key"
export GOOGLE_GENAI_USE_VERTEXAI=true

# 验证配置
gemini
> 测试连接

问题：网络连接超时

症状：

Network timeout. Please check your connection.

解决方案：

检查网络连接：

bash

# 测试基本连接
ping google.com

# 测试 HTTPS 连接
curl -I https://ai.google.dev

# 检查 DNS 解析
nslookup ai.google.dev

代理配置：

bash

# 如果在企业网络中，配置代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://proxy.company.com:8080

# 重启 CLI
gemini

使用过程中的问题

问题：文件读取失败

症状：

bash

> 分析这个文件 @config.json
Error: Could not read file

解决方案：

检查文件路径：

bash

# 确认文件存在
ls -la config.json

# 使用绝对路径
> 分析这个文件 @/full/path/to/config.json

# 检查当前目录
> 当前目录下有哪些文件？ !ls -la

文件权限问题：

bash

# 检查文件权限
ls -la config.json

# 修复权限
chmod 644 config.json

# 检查目录权限
ls -ld .

文件编码问题：

bash

# 检查文件编码
file config.json

# 转换编码（如果需要）
iconv -f gbk -t utf-8 config.json > config_utf8.json
> 分析这个文件 @config_utf8.json

问题：响应质量差

症状：

回答不相关
输出格式混乱
内容重复或截断

解决方案：

优化提示：

bash

# ❌ 模糊提示
> 帮我改代码

# ✅ 具体提示
> 重构这个函数以提高性能 @src/utils.js

# ❌ 过于宽泛
> 分析项目

# ✅ 明确范围
> 分析用户认证模块的安全性 @src/auth/

管理上下文：

bash

# 压缩长对话
/compress

# 清理无关上下文
/clear

# 开始新对话
/quit
gemini

提供更多上下文：

bash

# 包含相关文件
> 根据这个配置文件 @package.json 和这个组件 @src/App.tsx 分析依赖关系

# 使用项目配置
# 确保项目根目录有 GEMINI.md 文件
/memory refresh

问题：会话状态丢失

症状：

AI 忘记之前的对话内容
重复询问相同信息
上下文断裂

解决方案：

保存和恢复会话：

bash

# 保存重要会话
/chat save important-project

# 列出保存的会话
/chat list

# 恢复会话
/chat resume important-project

检查内存状态：

bash

# 查看当前 AI 内存
/memory show

# 重新加载项目配置
/memory refresh

# 手动添加重要信息
/memory add "这是一个 React + TypeScript 项目"

性能问题

问题：响应速度慢

症状：

等待时间过长
请求超时
系统资源占用高

解决方案：

优化请求：

bash

# 避免包含过多文件
# ❌ 包含整个项目
> 分析项目结构 @

# ✅ 指定具体目录
> 分析组件结构 @src/components/

# 分批处理大任务
> 先分析这个模块的主要功能 @src/auth/
> 然后详细分析每个函数

管理资源：

bash

# 查看当前统计
/stats

# 压缩历史记录
/compress

# 重启 CLI
/quit
gemini

问题：内存使用过高

症状：

系统变慢
CLI 进程占用大量内存
出现内存警告

解决方案：

bash

# 清理缓存
/clear

# 压缩对话
/compress

# 重启 CLI
/quit
gemini

# 分段处理大文件
# 而不是一次性包含全部内容

Shell 集成问题

问题：Shell 命令执行失败

症状：

bash

> !ls -la
Error: Command failed

解决方案：

检查权限：

bash

# 确保有执行权限
> !whoami
> !pwd

# 检查命令是否存在
> !which ls

路径问题：

bash

# 使用完整路径
> !/bin/ls -la

# 或切换到正确目录
> !cd /path/to/project && ls -la

Shell 模式问题：

bash

# 如果 shell 模式卡住
!  # 再次输入 ! 退出
# 或强制退出
Ctrl+C

高级诊断

创建诊断报告

bash

#!/bin/bash
# 快速诊断脚本

echo "=== Gemini CLI 诊断报告 ==="
echo "时间: $(date)"
echo

echo "1. 系统信息"
echo "操作系统: $(uname -a)"
echo "Node.js 版本: $(node --version 2>/dev/null || echo '未安装')"
echo "npm 版本: $(npm --version 2>/dev/null || echo '未安装')"
echo

echo "2. CLI 状态"
echo "CLI 路径: $(which gemini 2>/dev/null || echo '未找到')"
echo "npx 可用: $(which npx 2>/dev/null && echo '是' || echo '否')"
echo

echo "3. 网络测试"
if ping -c 1 google.com >/dev/null 2>&1; then
    echo "网络连接: ✓ 正常"
else
    echo "网络连接: ✗ 异常"
fi

echo "4. 环境变量"
echo "GEMINI_API_KEY: $(echo $GEMINI_API_KEY | cut -c1-10)... (已脱敏)"
echo "GOOGLE_API_KEY: $(echo $GOOGLE_API_KEY | cut -c1-10)... (已脱敏)"
echo "GOOGLE_GENAI_USE_VERTEXAI: $GOOGLE_GENAI_USE_VERTEXAI"

echo "=== 诊断完成 ==="

常见错误代码

错误信息	可能原因	解决方案
`command not found`	CLI 未安装	重新安装或使用 npx
`Authentication failed`	认证问题	重新登录或检查 API 密钥
`Network timeout`	网络问题	检查连接或配置代理
`File not found`	路径错误	检查文件路径和权限
`Permission denied`	权限不足	修改文件权限

获取帮助

内置帮助

bash

# 查看帮助
/help

# 查看版本信息
/about

# 查看工具列表
/tools

社区资源

官方文档: https://github.com/google-gemini/gemini-cli
GitHub Issues: https://github.com/google-gemini/gemini-cli/issues
社区讨论: https://github.com/google-gemini/gemini-cli/discussions

问题报告格式

当寻求帮助时，请提供：

系统信息: 操作系统、Node.js 版本
错误信息: 完整的错误消息
重现步骤: 如何触发问题
尝试的解决方案: 已经尝试过的方法

示例报告：

系统: macOS 14.0, Node.js 20.5.0
错误: Authentication failed after login
重现步骤:
1. 运行 `gemini`
2. 选择 Google 账户登录
3. 完成浏览器认证
4. 返回 CLI 显示认证失败

已尝试: 重新安装 CLI，清除浏览器缓存

预防措施

定期维护

bash

# 保持 Node.js 最新
node --version  # 检查版本

# 清理缓存
rm -rf ~/.gemini/cache/

# 备份重要会话
/chat save important-work

最佳实践

定期保存重要会话
使用具体的文件路径
避免包含过大的文件
定期压缩长对话
保持网络连接稳定

🔧 记住：大多数问题都有简单的解决方案。如果遇到困难，尝试重启 CLI 或检查基本的网络和认证设置。

性能问题

问题7：响应速度慢

症状：

bash

# 请求耗时过长
$ time gemini generate "hello"
real    0m45.123s

诊断步骤：

bash

# 测试网络延迟
ping -c 4 ai.google.dev

# 检查模型选择
gemini config get model

# 测试不同模型的速度
time gemini generate "test" --model gemini-pro

优化方案：

缓存策略：

bash

# 启用结果缓存
gemini config set cache-enabled true
gemini config set cache-duration 3600

# 预缓存常用查询
gemini generate "常用提示词" --cache-key "common-prompt"

# 查看缓存效果
gemini cache stats

批量处理优化：

bash

# 使用批量模式
echo -e "任务1\n任务2\n任务3" | gemini generate --batch

# 并行处理（谨慎使用，注意API限制）
cat tasks.txt | xargs -P 2 -I {} gemini generate "{}"

问题8：内存使用过高

症状：

系统变慢
CLI进程占用大量内存
出现内存不足错误

解决方案：

bash

# 限制缓存大小
gemini config set cache-max-size 100MB

# 清理缓存
gemini cache clear

# 限制历史记录
gemini config set history-max-entries 100

# 使用流式输出
gemini generate "长文本任务" --streaming

文件处理问题

问题9：文件读取失败

症状：

bash

$ gemini file document.txt "summarize"
Error: Could not read file: Permission denied

解决方案：

bash

# 检查文件权限
ls -la document.txt

# 修复权限
chmod 644 document.txt

# 检查文件编码
file document.txt
iconv -f gbk -t utf-8 document.txt > document_utf8.txt

# 使用绝对路径
gemini file /full/path/to/document.txt "summarize"

问题10：大文件处理问题

症状：

文件过大无法处理
输出截断
处理超时

解决方案：

bash

# 分割大文件
split -l 1000 large_file.txt chunk_

# 批量处理分片
for chunk in chunk_*; do
    gemini file "$chunk" "总结内容" --output "summary_$chunk.txt"
done

# 合并结果
cat summary_chunk_*.txt > final_summary.txt

# 增加处理超时
gemini config set file-timeout 300  # 5分钟

高级故障排除

完整诊断脚本

bash

#!/bin/bash
# gemini_diagnostics.sh - Gemini CLI诊断脚本

echo "=== Gemini CLI 诊断报告 ==="
echo "时间: $(date)"
echo

echo "1. 基本信息检查"
echo "操作系统: $(uname -a)"
echo "CLI版本: $(gemini --version 2>/dev/null || echo '未安装或无法执行')"
echo "安装路径: $(which gemini 2>/dev/null || echo '未找到')"
echo

echo "2. 配置检查"
echo "配置文件位置:"
ls -la ~/.gemini/config.yaml 2>/dev/null || echo "配置文件不存在"
echo
echo "当前配置:"
gemini config list 2>/dev/null || echo "无法读取配置"
echo

echo "3. 网络连接测试"
echo "Google AI 服务连通性:"
if ping -c 1 ai.google.dev >/dev/null 2>&1; then
    echo "✓ 网络连接正常"
else
    echo "✗ 网络连接失败"
fi

echo "HTTPS连接测试:"
if curl -s -I https://ai.google.dev >/dev/null; then
    echo "✓ HTTPS连接正常"
else
    echo "✗ HTTPS连接失败"
fi
echo

echo "4. 认证测试"
gemini auth test 2>/dev/null && echo "✓ 认证成功" || echo "✗ 认证失败"
echo

echo "5. 基本功能测试"
if gemini generate "hello" --max-tokens 10 >/dev/null 2>&1; then
    echo "✓ 基本生成功能正常"
else
    echo "✗ 基本生成功能异常"
fi
echo

echo "6. 系统资源"
echo "可用磁盘空间:"
df -h ~/.gemini 2>/dev/null || df -h ~
echo
echo "内存使用:"
free -h 2>/dev/null || vm_stat 2>/dev/null || echo "无法获取内存信息"
echo

echo "=== 诊断完成 ==="

日志分析工具

bash

#!/bin/bash
# analyze_logs.sh - 日志分析脚本

LOG_FILE="$HOME/.gemini/logs/gemini.log"

if [[ ! -f "$LOG_FILE" ]]; then
    echo "日志文件不存在: $LOG_FILE"
    exit 1
fi

echo "=== Gemini CLI 日志分析 ==="
echo

echo "1. 错误统计"
echo "总错误数: $(grep -c "ERROR" "$LOG_FILE")"
echo "网络错误: $(grep -c "network\|timeout\|connection" "$LOG_FILE")"
echo "认证错误: $(grep -c "auth\|api.key\|unauthorized" "$LOG_FILE")"
echo "配额错误: $(grep -c "quota\|rate.limit\|429" "$LOG_FILE")"
echo

echo "2. 最近错误"
echo "最近10个错误:"
grep "ERROR" "$LOG_FILE" | tail -10
echo

echo "3. 性能分析"
echo "平均响应时间: $(grep "response_time" "$LOG_FILE" | awk '{sum+=$NF; count++} END {print sum/count "ms"}')"
echo "最慢请求: $(grep "response_time" "$LOG_FILE" | sort -k3 -n | tail -1)"
echo

echo "4. 使用模式"
echo "最常用命令:"
grep "command:" "$LOG_FILE" | awk '{print $NF}' | sort | uniq -c | sort -nr | head -5

最佳实践总结

预防性维护

定期检查清单：

bash

# 每周执行的维护脚本
#!/bin/bash
# weekly_maintenance.sh

echo "开始每周维护..."

# 更新CLI
brew upgrade gemini-cli 2>/dev/null || echo "手动检查CLI更新"

# 清理缓存
gemini cache clean --older-than 7d

# 备份配置
gemini config export --output "backup/config-$(date +%Y%m%d).json"

# 检查API使用量
gemini usage summary --period week

# 测试基本功能
gemini generate "test" --max-tokens 5 >/dev/null && echo "✓ 功能正常"

echo "维护完成"

监控脚本：

bash

#!/bin/bash
# monitor.sh - 持续监控脚本

while true; do
    # 检查服务状态
    if ! gemini auth test >/dev/null 2>&1; then
        echo "$(date): 警告 - Gemini CLI服务异常"
        # 发送通知（根据需要实现）
    fi
    
    # 检查配额使用
    USAGE=$(gemini usage current --format json | jq '.percentage')
    if [[ $USAGE -gt 80 ]]; then
        echo "$(date): 警告 - API配额使用超过80%"
    fi
    
    sleep 300  # 5分钟检查一次
done

紧急恢复程序

快速恢复步骤：

备份当前配置
重置所有设置
重新配置基本参数
测试功能

bash

# emergency_recovery.sh
#!/bin/bash

echo "开始紧急恢复程序..."

# 备份当前配置
cp ~/.gemini/config.yaml ~/.gemini/config.yaml.backup.$(date +%s) 2>/dev/null

# 重置配置
gemini config reset --confirm

# 重新设置API密钥
read -p "请输入API密钥: " api_key
gemini config set api-key "$api_key"

# 基本配置
gemini config set model gemini-pro
gemini config set temperature 0.7
gemini config set max-tokens 1000

# 测试功能
if gemini generate "test" --max-tokens 5 >/dev/null; then
    echo "✓ 恢复成功"
else
    echo "✗ 恢复失败，请手动检查"
fi

获取帮助和支持

官方资源

文档和API参考：

官方文档: https://ai.google.dev/docs
API参考: https://ai.google.dev/api
社区论坛: https://groups.google.com/g/generative-ai

命令行帮助：

bash

# 查看全局帮助
gemini --help

# 查看命令特定帮助
gemini generate --help
gemini config --help

# 查看示例
gemini examples

社区支持

问题报告：

bash

# 生成问题报告
gemini diagnostic --output bug_report.txt

# 包含的信息：
# - 系统信息
# - CLI版本
# - 错误日志
# - 配置信息（敏感信息已脱敏）

寻求帮助的最佳方式：

明确描述问题现象
提供错误信息和日志
说明重现步骤
包含系统环境信息

结语

通过本教程，您现在具备了：

✅ 识别和诊断常见问题的能力
✅ 系统性的故障排除方法
✅ 预防性维护的知识
✅ 紧急情况的恢复技能

记住：

大多数问题都有标准解决方案
详细的错误信息是解决问题的关键
定期维护比事后修复更有效
备份配置是避免数据丢失的最佳保险

💡 专业建议：建议创建一个问题解决知识库，记录您遇到的问题和解决方案。这不仅帮助您快速解决重复问题，也能帮助团队其他成员。

现在您已经掌握了Gemini CLI的完整使用技能，从基础入门到高级应用，再到故障排除。希望这个工具能够显著提升您的工作效率！

Gemini CLI故障排除指南 ​

安装和启动问题 ​

问题：命令未找到 ​

问题：启动后无响应 ​

认证和连接问题 ​

问题：认证失败 ​

问题：网络连接超时 ​

使用过程中的问题 ​

问题：文件读取失败 ​

问题：响应质量差 ​

问题：会话状态丢失 ​

性能问题 ​

问题：响应速度慢 ​

问题：内存使用过高 ​

Shell 集成问题 ​

问题：Shell 命令执行失败 ​

高级诊断 ​

创建诊断报告 ​

常见错误代码 ​

获取帮助 ​

内置帮助 ​

社区资源 ​

问题报告格式 ​

预防措施 ​

定期维护 ​

最佳实践 ​

性能问题 ​

问题7：响应速度慢 ​

问题8：内存使用过高 ​

文件处理问题 ​

问题9：文件读取失败 ​

问题10：大文件处理问题 ​

高级故障排除 ​

完整诊断脚本 ​

日志分析工具 ​

最佳实践总结 ​

预防性维护 ​

紧急恢复程序 ​

获取帮助和支持 ​

官方资源 ​

社区支持 ​

结语 ​

Gemini CLI故障排除指南

安装和启动问题

问题：命令未找到

问题：启动后无响应

认证和连接问题

问题：认证失败

问题：网络连接超时

使用过程中的问题

问题：文件读取失败

问题：响应质量差

问题：会话状态丢失

性能问题

问题：响应速度慢

问题：内存使用过高

Shell 集成问题

问题：Shell 命令执行失败

高级诊断

创建诊断报告

常见错误代码

获取帮助

内置帮助

社区资源

问题报告格式

预防措施

定期维护

最佳实践

性能问题

问题7：响应速度慢

问题8：内存使用过高

文件处理问题

问题9：文件读取失败

问题10：大文件处理问题

高级故障排除

完整诊断脚本

日志分析工具

最佳实践总结

预防性维护

紧急恢复程序

获取帮助和支持

官方资源

社区支持

结语