迁移指南
从旧版本升级到最新版本的 Gemini CLI
迁移概述
本指南帮助您从旧版本的 Gemini CLI 迁移到最新版本。我们将涵盖重大变更、配置更新，并提供平滑过渡的分步说明。
当前版本
2.0.0
支持的迁移
本指南涵盖从 1.x 版本到 2.0.0 的迁移
版本兼容性矩阵
检查哪个迁移路径适用于您的当前版本
1.0.x - 1.2.x2.0.0
重大30-60 分钟
重大变更: 高
1.3.x - 1.5.x2.0.0
中等15-30 分钟
重大变更: 中
1.6.x - 1.9.x2.0.0
轻微5-15 分钟
重大变更: 低
v2.0.0 中的重大变更
可能影响您现有设置的重要变更
配置
配置文件格式
配置文件格式已从 JSON 更改为 YAML，以提供更好的可读性和注释支持。
影响级别
高
迁移方法
使用内置迁移工具：gemini config migrate
之前 (v1.x)
{
"api_key": "your-key",
"model": "gemini-pro"
}之后 (v2.0)
api_key: your-key
model: gemini-pro
# 现在支持注释！命令
命令结构变更
一些命令已被重命名或重构以保持一致性。
影响级别
中
迁移方法
更新您的脚本和别名
命令变更
gemini chatgemini askgemini generategemini creategemini config showgemini config listAPI
API 密钥管理
API 密钥现在以更安全的加密格式存储。
影响级别
低
迁移方法
重新运行：gemini config set api-key YOUR_KEY
您现有的 API 密钥将在首次运行时自动迁移
分步迁移
按照这些步骤迁移到 Gemini CLI v2.0.0
1
备份您的配置
在开始迁移之前创建当前配置的备份。
命令：
gemini config list > gemini-config-backup.txtcp ~/.gemini/config.json ~/.gemini/config.json.backup这确保您可以在需要时恢复设置。
2
更新 Gemini CLI
安装最新版本的 Gemini CLI。
命令：
npm update -g @google/generative-ai-cli验证：
gemini --version3
运行迁移工具
使用内置迁移工具更新您的配置。
命令：
gemini config migrate这将自动将您的配置转换为新格式。
4
验证配置
检查您的配置是否已正确迁移。
命令：
gemini config listgemini ask "你好，测试迁移"确保所有设置都已保留，CLI 按预期工作。
5
更新脚本和别名
更新使用旧命令语法的任何脚本或别名。
请参考上面的命令变更部分了解所需的具体更新。
迁移故障排除
常见问题及其解决方案
配置迁移失败
症状：
- 错误：无法迁移配置
- 找不到配置文件
解决方案：
- 确保您对 ~/.gemini 目录有写权限
- 检查旧配置文件是否存在：ls ~/.gemini/
- 尝试手动迁移：gemini config migrate --force
迁移后命令不工作
症状：
- 找不到命令错误
- 意外行为
解决方案：
- 清除您的 shell 缓存：hash -r
- 重启您的终端会话
- 检查文档中的新命令语法
API 密钥不工作
症状：
- 身份验证错误
- 无效的 API 密钥消息
解决方案：
- 重新设置您的 API 密钥：gemini config set api-key YOUR_KEY
- 验证密钥是否正确：gemini config get api-key
- 在 Google AI Studio 中检查 API 密钥权限
回滚说明
如何在需要时恢复到以前的版本
⚠️ 仅在遇到阻止正常操作的关键问题时使用回滚。
- 1
卸载当前版本：npm uninstall -g @google/generative-ai-cli - 2
安装以前的版本：npm install -g @google/generative-ai-cli@1.9.0 - 3
恢复配置：cp ~/.gemini/config.json.backup ~/.gemini/config.json - 4
验证回滚：gemini --version
迁移后步骤
成功迁移后的推荐操作
更新文档
中更新任何内部文档或团队指南以反映新的命令语法。
测试自动化脚本
高运行您的自动化脚本和 CI/CD 管道，确保它们与新版本兼容。
清理备份
低确认一切正常工作后，您可以删除备份文件。