# Macos Migration > macOS 系统迁移助手 — 两阶段：先在旧系统采集清单（JSON），再在新系统还原。 Use when user mentions: 系统迁移、换电脑、新装系统、Time Machine 恢复、 数据迁移、重装系统、migration、setup new mac、restore from backup、备份系统。 自动检测当前是旧系统（采集模式）还是新系统（还原模式）。 前置：先做一次 Time Machine 全量备份；唯一软件依赖是 Homebrew。 - Skill: `ttfake92-lab/macos-migration` (Agent Skill) - Install (CLI): `npx skillmds add ttfake92-lab/macos-migration` - Raw SKILL.md: https://api.skillmd.com/api/skills/ttfake92-lab/macos-migration/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ttfake92-lab (https://skillmd.com/u/ttfake92-lab) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/ttfake92-lab/macos-migration --- # macOS 系统迁移助手 两阶段设计：**旧系统采集 → 新系统还原**。中间通过一个 JSON 清单文件衔接。 ## 前置要求（务必先做） **在旧系统上先做一次 Time Machine 全量备份。** 这是整个迁移的安全网——新系统上 任何一步出问题，都能从这份全量备份里捞回来。还原阶段也直接从 Time Machine 挂载点 读取数据。 > 没有 Time Machine 全量备份，就不要开始迁移。 ## 运行模式检测 判断「采集还是还原」只看一个信号：**清单文件在不在**。 ```bash ls ~/migration-manifest.json 2>/dev/null ``` | 条件 | 模式 | |------|------| | 无清单文件 | 采集模式（在旧系统上，生成清单） | | 有清单文件 | 还原模式（在新系统上，读清单还原） | Time Machine 只是还原阶段的**数据来源**，不参与模式判断。 用户也可以直接指定：「采集」「备份」「还原」「迁移」。 --- ## 第零步：Homebrew 检查（两种模式都必须） ```bash which brew && brew --version || echo "NOT_INSTALLED" ``` - 已安装 → 继续 - 未安装 → **引导用户在终端手动执行**安装命令。这一步需要输入管理员密码（sudo）， 无法静默完成： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` 装完后按提示把 brew 加入 PATH（Apple Silicon：`eval "$(/opt/homebrew/bin/brew shellenv)"`）， 再继续。 --- ## 模式 A：旧系统采集 在旧系统上运行，扫描所有软件、配置、开发环境，生成 `~/migration-manifest.json`。 ### A1. Homebrew 软件包 ```bash brew list --formula brew list --cask brew tap ``` ### A2. 系统 Applications ```bash ls /Applications/ ls ~/Applications/ 2>/dev/null ``` 与 Homebrew cask 列表对比，标记哪些是 Homebrew 装的、哪些是手动/App Store 装的。 ### A3. Mac App Store 应用 ```bash mas list 2>/dev/null || echo "mas not installed" ``` 如果 `mas` 未安装，提示用户是否要安装（`brew install mas`）。 ### A4. npm 全局包 ```bash npm ls -g --depth=0 2>/dev/null ``` ### A5. uv 工具 ```bash uv tool list 2>/dev/null ``` ### A6. pip/pipx 包 ```bash pip list 2>/dev/null pipx list 2>/dev/null ``` ### A7. Go 全局工具 ```bash ls ~/go/bin/ 2>/dev/null ``` ### A8. 配置文件扫描 扫描 home 目录下的 dotfiles 和配置目录： ```bash ls -la ~/ ``` 重点采集： - Shell：`.zshrc`, `.zshenv`, `.zprofile`, `.bashrc`, `.bash_profile` - Git：`.gitconfig`, `.gitignore_global` - SSH：`.ssh/` - 编辑器：`.claude/`, `.codex/`, `.config/`, `.cursor/`, `.zed/` - 容器：`.docker/`, `.kube/` - 包管理器：`.npm/`, `.nvm/`, `.bun/`, `.cargo/`, `.rustup/` - 其他应用配置：`.SwitchHosts/`, `.ollama/`, `.syncthing/` 等 **敏感数据先问后采**：`.ssh/`（私钥）、dotfiles 里可能含 token、`.aws/`、`.kube/`、 钥匙串等都是密钥级信息。采集这些之前**先问用户是否纳入**： - 用户同意 → 正常采集，并**明确提醒**：「清单和备份里含私钥/凭据，传输、存放、 通过网盘或聊天工具发送时注意不要外泄。」 - 用户拒绝 → 跳过这些项，在清单里记入 `"skipped_sensitive": [...]`，让用户日后 自行手动迁移（差异报告里也会再列一次）。 ### A9. LaunchAgents（自启动服务） ```bash ls ~/Library/LaunchAgents/ ``` ### A10. 用户项目目录 列出 home 目录下非 dotfile 的顶层目录： ```bash ls -d ~/*/ 2>/dev/null ``` 排除系统目录（Library, Applications, Public 等），记录用户自建的项目/数据目录。 ### A11. Shell 环境 ```bash # 当前 shell 版本 zsh --version # Homebrew 路径 / 版本管理器（nvm、fnm 等）配置 grep -iE 'brew|nvm|fnm' ~/.zshrc ``` ### A12. 其他易漏项 迁移时最容易漏、丢了又很烦的几类： ```bash # 编辑器扩展 code --list-extensions 2>/dev/null cursor --list-extensions 2>/dev/null # 自购/自装字体 ls ~/Library/Fonts/ 2>/dev/null # 定时任务 crontab -l 2>/dev/null # 手动装到非 Homebrew 路径的命令行工具 ls /usr/local/bin/ 2>/dev/null ls /opt/ 2>/dev/null ``` > 系统偏好（`defaults`）量大且与机型强相关，不自动采集；如用户在意，在还原差异 > 报告里提醒手动核对（键盘、触控板、Dock、快捷键等）。 ### A13. 生成清单文件 将以上所有信息写入 `~/migration-manifest.json`： ```json { "version": 1, "captured_at": "2026-06-28T16:00:00+08:00", "source_macos": "15.5", "source_hostname": "old-macbook", "homebrew": { "taps": ["user/repo", "..."], "formulas": ["git", "node@22", "..."], "casks": ["1password", "docker-desktop", "..."] }, "applications": { "homebrew_casks": ["claude", "firefox", "..."], "app_store": [{"id": 123456, "name": "App Name"}], "manual": ["Final Cut Pro.app", "..."] }, "package_managers": { "npm_global": ["@anthropic-ai/claude-code", "..."], "uv_tools": ["nano-pdf", "..."], "pip_packages": ["package1", "..."], "go_binaries": ["tool1", "..."] }, "configs": { "dotfiles": [".zshrc", ".gitconfig", ".ssh", "..."], "config_dirs": [".claude", ".codex", ".config", ".docker", "..."], "app_support_keys": ["Syncthing", "obs-studio", "..."] }, "editor_extensions": { "vscode": ["ms-python.python", "..."], "cursor": ["..."] }, "fonts": ["MyFont.otf", "..."], "crontab": "", "manual_bins": ["/usr/local/bin/foo", "/opt/bar", "..."], "launch_agents": ["com.github.syncthing.plist", "..."], "user_dirs": ["Projects", "Sites", "..."], "shell": { "shell": "zsh", "brew_in_path": true, "nvm_installed": true, "custom_env_vars": {} }, "skipped_sensitive": [] } ``` ### A14. 采集完成 输出清单摘要，提示用户： ``` ✅ 采集完成！清单已保存到 ~/migration-manifest.json 采集内容： - Homebrew: X taps, Y formulas, Z casks - 应用: X 个 Homebrew, Y 个 App Store, Z 个手动安装 - npm 全局包: X 个 - 配置文件: X 个 dotfiles, Y 个配置目录 - 编辑器扩展: X 个 / 字体: Y 个 / 定时任务: 有/无 - 自启动服务: X 个 - 用户目录: X 个 - 跳过的敏感项: X 个（用户选择不采集） ⚠️ 若采集了 .ssh / dotfiles 中的凭据，清单与备份含私钥，传输存放注意不要外泄。 下一步：确认已有 Time Machine 全量备份，将 migration-manifest.json 复制到新系统， 再次运行此 skill。 ``` --- ## 模式 B：新系统还原 在新系统上运行，读取 `migration-manifest.json` 并逐步还原。 ### B0. 获取清单 ```bash ls ~/migration-manifest.json ``` 如果不存在： ``` 找不到 migration-manifest.json。 请将旧系统上采集的清单文件复制到新系统的 home 目录： scp old-mac:~/migration-manifest.json ~/migration-manifest.json 或者手动指定路径。 ``` ### B1. Homebrew 软件安装 > 前提：第零步已确认 Homebrew 装好（需用户手动输密码安装）。装好之后这一步才能跑。 读取清单中的 `homebrew` 字段。 ```bash # 添加 taps（逐个） brew tap / # 信任第三方 taps brew trust / # 安装 formulas（批量，失败不回滚整批） brew install ... # 安装 casks（逐个，避免回滚） for cask in ...; do brew install --cask "$cask" 2>&1 | tail -3 done ``` 没装上的（需 sudo、网络失败等）先记下，最后在 B7 差异报告统一列给用户。 ### B2. 其他包管理器 读取清单中的 `package_managers` 字段。 ```bash # npm npm install -g ... # uv uv tool install ... # pip（如果需要） pip install ... # go binaries go install @latest @latest ... ``` ### B3. 配置文件恢复 读取清单中的 `configs` 字段。 有两种数据来源，优先级： 1. **Time Machine 直接复制**（如果有挂载） 2. **用户手动提供**（如果清单是从别的方式获取的） ```bash TM="