Migration Guide¶

重要性：⭐⭐ 目标读者：升级 Claude Code / 迁移到老版本关联：CHANGELOG.md（推测）、PERMISSIONS.md

1. 概览¶

本文档涵盖： - 版本升级 - 配置迁移 - 数据迁移 - API 变更 - 回滚步骤

2. 5 类版本¶

2.1 Stable¶

claude  # 默认 stable

稳定。

2.2 Latest¶

claude --latest  # 推测

2.3 Beta¶

claude install latest

Beta（推测）。

2.4 Specific¶

claude install 1.0.0

指定版本。

2.5 Rollback¶

claude rollback  # 推测

回滚。

3. 5 类升级路径¶

3.1 patch (1.0.0 → 1.0.1)¶

向后兼容 —— 直接升级。

claude update  # 自动

3.2 minor (1.0.0 → 1.1.0)¶

新功能 —— 通常兼容。

# 1. 备份
cp -r ~/.claude ~/.claude.bak

# 2. 升级
claude update

# 3. 验证
claude --version
claude mcp list
claude plugin list

3 步。

3.3 major (1.0.0 → 2.0.0)¶

可能 breaking —— 看 CHANGELOG。

# 1. 读 CHANGELOG
# 2. 检查 deprecation
# 3. 备份
# 4. 升级
# 5. 测关键功能

5 步。

3.4 settings 升级¶

# 自动 migrate
# 或手动：
# settings.json 字段可能改名

自动 / 手动。

3.5 数据迁移¶

# session log 自动迁移
# plugin 自动兼容
# marketplace 自动升级

自动。

4. 5 类 settings 迁移¶

4.1 自定义 keybindings¶

// v1
{ "keybindings": [...] }

// v2（推测）
{ "keyBindings": { "global": [...] } }

字段改名。

4.2 权限规则¶

// v1
{ "permissions": { "allow": ["Bash(git:*)"] } }

// v2（推测）
{ "permissions": { "rules": { "allow": ["Bash(git:*)"] } } }

结构改。

4.3 MCP servers¶

// v1: 顶级
{ "mcpServers": {...} }

// v2: 嵌套
{ "mcp": { "servers": {...} } }

嵌套。

4.4 Plugins¶

// v1
{ "plugins": [...] }

// v2
{ "plugins": { "enabled": [...], "config": {...} } }

结构改。

4.5 Hooks¶

// v1
{ "hooks": {...} }

// v2
{ "hooks": { "v2": true, ... } }

版本字段。

5. 5 类数据迁移¶

5.1 Session log¶

# 自动（推测）
# v1 → v2 schema migration

自动。

5.2 Plugin cache¶

# 自动（推测）
# 重新下载

自动。

5.3 MCP config¶

# 自动
# 但 clientSecret 可能需重输

自动 + 手动。

5.4 Marketplace cache¶

# 自动

自动。

5.5 User data¶

# 不动
# 推测：~/.claude/projects/<project>/

不动。

6. 5 个 API 变更¶

6.1 CLI flag 改名¶

# v1
claude --bare

# v2
claude --simple  # 推测

改名。

6.2 JSON 字段¶

// v1
{ "claude_code_entrypoint": "cli" }

// v2
{ "entrypoint": "cli" }  // 推测

字段。

6.3 file 路径¶

# v1: ~/.claude/...
# v2: ~/.config/claude/...  # 推测 XDG

路径。

6.4 环境变量¶

# v1: CLAUDE_CODE_*
# v2: ANTHROPIC_*  # 推测

env。

6.5 工具 / 命令¶

# v1
> /agents

# v2
> /team  # 推测

命令改名。

7. 5 步升级流程¶

7.1 备份¶

cp -r ~/.claude ~/.claude.bak-$(date +%Y%m%d)

备份。

7.2 读 CHANGELOG¶

# 推测
# /docs/CHANGELOG.md 或 GitHub release

CHANGELOG。

7.3 检查 breaking¶

# CHANGELOG 找 "BREAKING" / "DEPRECATED"

breaking。

7.4 升级¶

claude update
# 或
curl ... | sh

升级。

7.5 验证¶

claude --version
claude mcp list
claude plugin list
# 跑关键命令测试

验证。

8. 5 步回滚¶

8.1 备份当前¶

cp -r ~/.claude ~/.claude.broken

备份。

8.2 恢复旧版¶

claude rollback  # 推测
# 或
claude install 1.0.0

恢复。

8.3 恢复数据¶

# 推测
# 数据自动兼容旧版

自动。

8.4 验证¶

claude --version
claude mcp list

验证。

8.5 报告问题¶

# GitHub issue

报告。

9. 4 类 breaking change 案例¶

9.1 命令改名¶

# v1 → v2
claude --bare → claude --simple

rename。

9.2 JSON 改名¶

// v1 → v2
{ "permissionMode" } → { "defaultMode" }

field。

9.3 删除功能¶

v1: feature X
v2: REMOVED

删除。

9.4 默认值改¶

v1: defaultMode = default
v2: defaultMode = acceptEdits

default 改。

10. 5 个常见迁移问题¶

10.1 settings 字段 missing¶

// 旧 settings 缺新字段
// 自动用默认值

default 兜底。

10.2 MCP 凭据失效¶

# clientSecret 过期
# 重新 OAuth
claude mcp remove <name>
claude mcp add --transport stdio -- ...

重连。

10.3 Plugin 不兼容¶

# plugin 不支持新版本
# 1. 升级 plugin
claude plugin update <name>
# 2. 或禁用
claude plugin disable <name>

升级/禁用。

10.4 Session 不能 resume¶

# JSON 格式不兼容
# fork 或新建
claude --resume <id> --fork-session

fork。

10.5 Hook 失败¶

# hook 脚本 API 变
# 改 hook 脚本

改 hook。

11. 5 个最佳实践¶

升级前备份 —— 永远
读 CHANGELOG —— 必须
小步升级 —— patch → minor → major
测关键功能 —— 升级后
保留 1-2 个旧版本 —— 紧急回滚

5 条。

12. 5 个企业部署建议¶

12.1 预发布测试¶

# staging 环境先升级

staging。

12.2 灰度¶

# 10% → 50% → 100%

灰度。

12.3 监控¶

# 错误率 / 性能指标

监控。

12.4 回滚预案¶

# 1 分钟内回滚

预案。

12.5 通知¶

# 升级前通知
# 升级后状态

通知。

13. 5 个迁移检查¶

13.1 备份验证¶

ls ~/.claude.bak
# 完整

验证。

13.2 版本检查¶

claude --version
# 期望版本

检查。

13.3 功能 smoke test¶

> Hello
> /help
> git status

smoke。

13.4 数据完整性¶

# session 列表
claude --resume
# plugin 列表
claude plugin list
# MCP 列表
claude mcp list

完整性。

13.5 性能¶

time claude --resume <session>
# 与基线比较

性能。

14. 5 个迁移工具¶

14.1 claude update¶

claude update
# 自动下载 + 替换

update。

14.2 claude rollback¶

claude rollback
# 推测

rollback。

14.3 claude doctor¶

# 推测
# 检查配置 + 修复

doctor。

14.4 claude migrate¶

# 推测
# settings 自动迁移

migrate。

14.5 claude validate¶

# 推测
# 验证 settings / plugin / MCP

validate。

15. 总结¶

迁移 = 备份 + 升级 + 验证。

核心： - 5 类版本 - 5 类升级路径 - 5 类 settings 迁移 - 5 类数据迁移 - 5 步升级流程 - 5 步回滚

下一步： - 看 CHANGELOG.md - 备份当前 - 升级 - 验证