immich-go 照片库批量迁移助手

要解决的问题

当你试图把十几年积累的照片档案迁移到 Immich 时，最常见的场景是这样的：源目录散落在多个硬盘、嵌套相册层级极深，甚至还有 Google Takeout 导出的压缩包。如果靠 Web 界面逐批手动上传，不但要反复处理断点续传，还很容易遗漏子目录，元数据丢失后还得回头重新对齐。本质上，这是重复劳动与状态不一致的双重问题。

技能如何工作

这个技能的核心是 immich-go 工具，它把迁移流程拆成了几个可预测的步骤：

• 批量扫描源库：直接读取本地目录、takeout 导出或嵌套相册，不需要你先手动整理成统一结构
• 元数据保留：在传输过程中同步 EXIF、拍摄时间、GPS 等信息，避免上传后照片变成“无头文件”
• 差异整合：通过 Immich API 识别已存在的条目，跳过重复文件，只补传缺失部分
• 凭证驱动：使用 API token 与服务器通信，整个过程可脚本化，适合挂在 CI 或定时任务里

适用边界与注意点

这个方案适合大规模、一次性或周期性归档场景，不适合偶尔传几张图的轻量使用。几个实际限制要提前留意：

• Immich 服务器需要开启 API 访问权限，token 要有写入相册的权限
• 如果源库使用了非标准命名或软链接，可能需要先做一轮整理
• immich-go 本身不负责存储去重，它只保证“上传到 Immich”这一步的正确性
• 迁移前最好对源库做一次完整备份，尤其是原始 RAW 文件

总体而言，它的价值在于把“搬照片”从手工活变成可重复执行的工程任务。