Claude Code 配置迁移指南：换电脑不丢 Skills

claude-code-config-migration-guide
新电脑到手，Claude Code 装好，终端一开——Skills 没了，API 配置没了，调了好久的 settings 也没了。这不是 bug，是设计如此。Claude Code 作为 CLI 工具，所有状态存在本地，官方不提供跨设备同步，也没有迹象表明这个设计会改变。迁移这件事，只能自己解决。

这篇文章整合了社区里分散的实践经验，给出一条从旧机器到新机器可以照着跑通的路径：先搞清楚要动哪些文件，再挑合适的工具，最后用一份 checklist 收尾。

先搞清楚要备份什么

Claude Code 的配置状态散落在两个核心路径：

~/.claude.json —— 全局配置文件
~/.claude/settings.json —— 全局设置

除这两个文件外，还有四类数据值得备份：memories、skills、settings、conversation files。后三类都在 ~/.claude/ 目录下，但官方没有公开完整目录树。直接在自己机器上跑 ls -la ~/.claude/，比任何文档都准确。

Windows 用户注意：Anthropic 官方推荐通过 WSL 2 + Ubuntu 运行 Claude Code，配置文件路径在 Linux 子系统内部，不在 Windows 用户目录下。在 PowerShell 里找 ~/.claude.json 是找不到的。

四类数据的迁移优先级大致如下：

数据类型	迁移价值	备注
settings	高	API 配置、行为偏好，重建成本最高
skills	高	积累的能力包，丢了要重新找
memories	中	项目上下文，可重建但耗时
conversation files	低～中	历史对话，恢复后能否续上存疑

会话历史这块要留个心眼。文件备份容易，但恢复到新机器后能否真正续上对话，目前没有可靠的确认。不要对「无缝衔接」抱太高期望。

两个工具，分别解决不同问题

社区围绕 Claude Code 配置可移植性出现了两个工具，定位不重叠，按需选用。

claude-code-backup：跨平台全量备份

Sibyllablueviolet195/claude-code-backup 做的就是完整搬家这件事：自动备份和同步 memories、skills、settings、conversation files 四类数据，覆盖 Windows / macOS / Linux。

目前社区里唯一明确以「跨平台备份同步」为核心功能的工具。如果你的需求就是把东西从旧机器搬到新机器，这是第一个应该看的。具体备份机制和可用命令直接看 GitHub 仓库的 README。

CCC：配置档案切换器

yoyooyooo/claude-code-config（简称 CCC）解决另一个问题：在多套 API 配置之间快速切换。

同时用两个服务商的 API 端点，或者个人项目和工作项目配置不同，CCC 可以保存多套配置档案，一条命令切换。几个值得注意的细节：

纯 Shell 脚本，只依赖 jq，没有额外依赖
切换使用原子性操作——直接手动编辑 settings.json 有数据损坏风险，工具的价值不只是方便
敏感信息显示时自动脱敏

重要限制：CCC 只支持 macOS 和 Linux，不支持 Windows 原生环境。Windows 用户想用 CCC，必须走 WSL 2 路径。

从零开始，在新机器上跑完整套流程

以下操作适用于 macOS / Linux 用户，或 Windows 下已配置好 WSL 2 + Ubuntu 的用户。目标是把旧机器的配置完整迁移过来。

第一步：打包旧机器上的配置

# 先看看实际目录结构
ls -la ~/.claude/
cat ~/.claude.json  # 检查内容，注意 API key 不要泄露

# 用 tar 打包整个 .claude 目录
tar -czf claude-config-backup.tar.gz \
  ~/.claude.json \
  ~/.claude/

如果用 Git 管理备份，把 ~/.claude.json 里的 API key 值排除在外，只同步配置结构。API key 单独保存，不要提交到仓库。

第二步：新机器安装 Claude Code

macOS/Linux 直接跑：

npm install -g @anthropic-ai/claude-code

Windows 用户先装 WSL 2，进入 Ubuntu 环境后执行同样的命令。

第三步：恢复配置文件

# 解压到 home 目录
tar -xzf claude-config-backup.tar.gz -C ~/

恢复后确认一下：

cat ~/.claude/settings.json  # 确认设置完整
ls ~/.claude/                # 确认 skills 等目录在

第四步：安装 CCC 并导入配置档案

先装依赖：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL/Fedora
sudo yum install jq

一键安装 CCC：

curl -fsSL https://raw.githubusercontent.com/yoyooyooo/claude-code-config/refs/heads/main/ccc | bash

或者手动安装：

chmod +x ccc
sudo mv ccc /usr/local/bin/ccc

初始化并导入当前配置：

ccc init
ccc import default  # 把当前 settings.json 导入为 default 档案

多套配置的管理：

ccc add work    # 交互式添加新配置
ccc list        # 查看所有档案状态
ccc use work    # 切换到 work 这套配置

调试时可以检查三个文件：~/.claude/settings.json（主配置）、~/.claude/ccc-config.json（CCC 自身配置）、~/.claude/settings.json.backup.*（备份文件）。

第五步：验证 Skills

Skills 本质上是遵循路径约定的一组文件，没有「重新安装」这回事。第三步恢复了整个 ~/.claude/ 目录，Skills 应该已经跟着回来了。启动 Claude Code，验证之前的 Skills 是否可用。

Skills 跨工具迁移：一个容易忽略的细节

如果你同时在用 Claude Code 和 Codex（OpenAI 的 CLI AI 编程工具），有个很实用但鲜少被提到的技巧：Skills 从 Claude Code 迁移到 Codex，只需要把路径里的 .claude 改成 .codex。

就是字面意思。Skills 的可移植性完全依赖这个路径约定，不绑定任何工具自身的机制。在 Claude Code 里积累的 Skills，不是被锁死在这个工具里的。

说到 Skills 积累，社区生态目前挺活跃。有一个中文社区维护的精选集（Claude Code Skills 合集），截至 2026 年 7 月收录了 401+ 条目，按场景分类，覆盖代码审查、README、API 测试、性能分析、重构建议等高频场景，还包含 Supabase、Together AI、Sentry、腾讯 RTC 等官方资源。复制即装，不用从零找起。

更大的生态里，NVIDIA 官方提供了 230 个验证型 Agent Skills，PlanetScale 官方提供了 15 个数据库审查与运维 Skills。

Skills 积累得越多，迁移成本意识自然越强。把 Skills 纳入版本控制或云存储，值得早点建立这个习惯。

MCP 配置也要一起迁移

MCP（Model Context Protocol）Server 配置是另一个经常被遗漏的部分。如果你在 Claude Code 里接入了 MCP Server，相关配置也存在 ~/.claude/settings.json 或项目级别的配置文件里。

迁移时确认一下：

全局 MCP Server 配置随 settings.json 一起打包，恢复时会带过来
项目级别的 MCP 配置通常在项目目录下的 .claude/ 文件夹，如果项目本身在 Git 里，这部分一般不会丢
MCP Server 本身（比如本地运行的 Node 进程）需要在新机器上单独重装，配置文件恢复了，但服务端程序不会自动出现

做完 Claude Code 配置迁移后，跑一遍 MCP Server 的连通性验证，别跳过这步。

Windows 用户额外要注意的坑

除了 CCC 不支持 Windows 原生之外，还有一个更隐蔽的问题：core.autocrlf=true 会破坏同步幂等性。

Git 在 Windows 上默认开启 CRLF 自动转换。如果用 Git 同步 Skills 或配置文件，每次 pull 之后 Git 可能把所有文件识别为有变更（行尾字符被转换了），导致同步永远不「干净」。处理方式是在脚本层面保留目标文件原有的行尾格式。

最稳的做法还是走 WSL 2 + Ubuntu，在 Linux 子系统里操作。路径问题、换行问题、CCC 兼容问题，一并绕开。

没有额外工具时的最小方案

有时候在受限环境里，装不了额外工具。

社区有一个自发形成的约定：每次会话结束前，让 Claude 把关键上下文写入 claude.md，再通过 Git 在多台机器间同步这个文件。零工具依赖，只要有 Git 就能用。

缺点也很直接：依赖每次手动触发，只保存语义上下文，不保存 Skills 文件，API 配置也不在覆盖范围内。

把它当补充手段比较合适。「换台机器继续某个项目」的场景，claude.md 能让新机器上的 Claude Code 快速回到状态；完整的环境迁移还是得走前面那套流程。

迁移 checklist

按顺序走，不跳步：

旧机器上确认 ~/.claude.json 和 ~/.claude/ 目录完整
打包备份，API key 不提交到公开仓库
新机器安装 Node.js 和 Claude Code
恢复配置文件到 ~/ 对应位置
验证 ~/.claude/settings.json 内容正确
安装 jq，安装 CCC（macOS/Linux 或 WSL 2 内）
ccc init + ccc import 导入配置档案
启动 Claude Code，检查 Skills 是否可用
如有 MCP Server，验证连通性
Windows 用户：确认在 WSL 2 内操作，检查 Git core.autocrlf 设置

知道要备份什么，执行并不难。把 ~/.claude/ 目录纳入日常备份流程，比事后补救轻松得多。

关于 Easy Claude Code

如果你想用上 Claude Code，可以试试我们 ECC（Easy Claude Code）的中转服务：免🪜、低成本、快速稳定，直连官方 Claude Code。企业定制化服务可详询。

购买地址：https://store.easyclaude.com
文档中心：https://easyclaude.com/doc

Claude Code 配置迁移完整指南：换电脑不丢 Skills 和设置