为什么要迁移会话？

最近我在参与一个挑战杯项目，用 Claude Code 做主力辅助开发。经过几轮深入对话，此时大量有价值的上下文已经"固化"在会话里。然而项目中途需要换到另一台电脑继续，单纯复制项目文件显然不够：新电脑的 Claude Code 不认识之前的对话，一切得重头再来。

能不能把完整会话上下文也一并迁移，实现"无缝衔接"？答案是肯定的。Claude Code 的数据存储设计天然支持可移植性，只需几步操作即可。

二、先搞懂 Claude Code 把数据存哪了

要进行迁移，必须知己知彼。Claude Code 的所有本地数据都集中在 ~/.claude/ 目录下，核心结构如下：

~/.claude/
├── projects/                    ← 🔑 最重要：按项目目录存放对话记录
│   └── <编码后的项目路径>/
│       ├── <session-id>.jsonl   ← 完整对话转录文件（核心数据）
│       └── memory/              ← 持久化记忆（/memory 命令保存的内容）
│
├── sessions/                    ← 会话元数据（pid、cwd、状态等）
│   └── <pid>.json
│
├── file-history/                ← 文件编辑历史（用于 /diff 等）
│   └── <session-id>/
│       └── *@v2
│
├── tasks/                       ← 任务追踪（内部状态）
│   └── <session-id>/
│       ├── .highwatermark
│       └── .lock
│
├── settings.json                ← 用户全局设置
└── settings.local.json          ← 本地权限配置

其中最关键的是 projects/<编码路径>/<session-id>.jsonl——它记录了所有对话消息，是上下文恢复的命脉。sessions/<pid>.json 则记录了会话的工作目录（cwd）和会话 ID，用于关联。

路径编码规则（非常重要）

Claude Code 会对项目绝对路径进行编码，作为 projects/ 下的子目录名。规则很简单：

• : → -
• \ → -
• 非 ASCII 字符（如中文）→ -（每个字符一个 -）
• 其他保留

关键点：如果两台电脑的用户名不同，编码目录名就不同，迁移时需要做目录重映射。

三、两种迁移方案

方案 A：相同路径（最简单）

如果你能在新电脑上完全复刻旧电脑的项目路径（包括盘符、用户名、文件夹名），那么迁移只需两步：

1. 复制项目文件夹到新电脑的相同位置。
2. 打包整个 ~/.claude/ 复制到新电脑的相同位置（覆盖或合并）。

然后在新电脑的项目目录下启动 claude，一切就绪。

优点：无需任何修改，操作简单。
缺点：实际场景中，两台电脑用户名不同或盘符不同很常见，此时路径无法完全一致。

方案 B：路径不同（通用方案）

当新电脑用户名、盘符或父目录发生变化时，需要额外处理目录重命名和 cwd 修正。下面结合我的实战案例详细说明。

实战场景

• 旧电脑路径：C:\Users\A\Desktop\挑战杯数据集（用户名 A）
• 新电脑路径：C:\Users\B\Desktop\挑战杯数据集（用户名 B）
• Session ID：66762821-XXXX-XXXX-XXXX-XXXXXXXXXXXX（示例占位符）
• PID：1111 （任意命名）

想要快速找到某一个项目的Session ID，直接打开~\.claude\history.jsonl，再Ctrl+F查找该项目的目录路径，即可看到对应的ID字段。

迁移包结构

claude-migration/
├── README.md
├── projects/
│   └── OLD_ENCODED/                 # 旧编码名：C--Users-A-Desktop-------
│       ├── 66762821-XXXX-....jsonl  # 对话转录
│       └── memory/                  # 持久化记忆（可能为空）
├── sessions/
│   └── 1111.json                    # 会话元数据（需要我们自己手动创建）
├── file-history/
│   └── SESSION_ID/                  # 文件编辑历史
│       └── *@v2
└── tasks/
    └── SESSION_ID/                  # 任务追踪数据
        ├── .highwatermark
        └── .lock

说明：下文所有命令和示例中的 A、B、66762821-XXXX-XXXX-XXXX-XXXXXXXXXXXX、1111 均为占位符，实际操作时请替换为你自己的真实值。

四、迁移执行步骤（新电脑上操作）

第 1 步：安装并初始化 Claude Code

在新电脑上安装 Claude Code，并至少运行一次（任意目录），让它自动生成 ~/.claude/ 骨架。

claude
# 进入后输入 /exit 退出

第 2 步：计算新路径的编码名

用 Python 脚本计算新项目路径的编码名（将路径中的 B 换成你的实际用户名）：

python -c "
import os
new_path = r'C:\Users\B\Desktop\挑战杯数据集'   # 改成你的实际路径
result = []
for c in new_path:
    if c == ':' or c == '\\' or c in '/*?\"<>|' or ord(c) > 127:
        result.append('-')
    else:
        result.append(c)
print('新编码名:', ''.join(result))
"

输出示例：新编码名: C--Users-B-Desktop-------。记下这个字符串。

第 3 步：迁移对话转录（核心）

将迁移包中的 projects/OLD_ENCODED/ 下的 .jsonl 文件复制到新电脑的 ~/.claude/projects/新编码名/ 目录下。

mkdir -p ~/.claude/projects/新编码名/
cp /path/to/claude-migration/projects/OLD_ENCODED/66762821-XXXX-XXXX-XXXX-XXXXXXXXXXXX.jsonl \
   ~/.claude/projects/新编码名/

如果 memory/ 目录不为空，也一并复制（本例为空，可跳过）。

第 4 步：迁移会话元数据并修正 cwd

mkdir -p ~/.claude/sessions/