iCloud照片下载器命令行工具完全指南

一、工具简介与安装

1.1 工具概述

iCloud照片下载器是一款轻量级命令行工具，专为从iCloud照片库批量下载照片和视频而设计。它提供了灵活的参数配置，支持增量同步、选择性下载和自动化管理等高级功能，适用于个人备份、数据迁移和服务器定时同步等多种场景。

1.2 安装方法

Python环境安装：

pip install icloudpd

源码安装：

git clone https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
cd icloud_photos_downloader
pip install -r requirements-pip.txt
python setup.py install

💡 安装技巧：建议使用虚拟环境隔离依赖，避免与系统Python环境冲突。

二、基础使用与认证配置

2.1 基本命令格式

icloudpd --username <Apple ID> [参数选项] <下载目录>

2.2 认证方式

交互式认证（推荐）：

icloudpd --username [e-mail] ./downloads

密码安全存储： ⚠️ 不建议直接在命令行使用--password参数，推荐使用系统密钥链：

icloudpd --username [e-mail] --use-keychain ./downloads

多账户管理：通过--cookie-directory指定不同缓存目录实现多账户隔离：

icloudpd --username [e-mail] --cookie-directory ~/.icloudpd/account1 ./downloads/account1

三、下载策略与范围控制

3.1 增量同步设置

智能增量下载：--until-found X参数从最新照片开始检查，当连续X张照片已存在时停止：

icloudpd --username [e-mail] --until-found 5 ./downloads

适用场景：定期同步场景，减少不必要的文件检查和IO操作。

3.2 选择性下载

按数量筛选：--recent X仅下载最新的X张照片，适合测试配置：

icloudpd --username [e-mail] --recent 10 ./downloads

按时间筛选：--skip-created-before YYYY-MM-DD跳过指定日期前的照片：

icloudpd --username [e-mail] --skip-created-before 2023-01-01 ./downloads

内容类型筛选：

# 仅下载照片，跳过视频
icloudpd --username [e-mail] --skip-videos ./downloads

# 仅下载视频
icloudpd --username [e-mail] --only-videos ./downloads

四、相册与文件管理

4.1 相册与图库选择

指定相册下载：--album "相册名称"下载特定相册内容：

icloudpd --username [e-mail] --album "旅行照片" ./downloads

查看可用相册：

icloudpd --username [e-mail] --list-albums

多图库支持：企业用户可使用--library参数指定图库：

icloudpd --username [e-mail] --library "工作图库" ./downloads

4.2 文件命名与存储结构

自定义目录结构：使用--folder-structure定义文件组织方式：

# 按年/月/日组织文件
icloudpd --username [e-mail] --folder-structure "{:%Y/%m/%d}" ./downloads

文件命名策略：

# 保留原始文件名
icloudpd --username [e-mail] --original-filenames ./downloads

# 保留Unicode字符
icloudpd --username [e-mail] --keep-unicode-in-filenames ./downloads

五、高级功能与自动化

5.1 持续同步模式

--watch-with-interval X参数实现定时同步，每隔X秒检查一次更新：

icloudpd --username [e-mail] --watch-with-interval 3600 ./downloads

适用场景：24小时运行的服务器，实现iCloud照片自动备份。

⚠️ 注意：间隔设置过短可能触发iCloud API限制，建议设置3600秒（1小时）以上。

5.2 云端照片管理

自动清理云端照片：--keep-icloud-recent-days X保留最近X天的云端照片，删除更早的内容：

icloudpd --username [e-mail] --keep-icloud-recent-days 30 ./downloads

💡 使用技巧：先使用--dry-run测试效果，确认无误后再实际执行。

仅下载原始文件：

icloudpd --username [e-mail] --download-original ./downloads

六、实用参数与场景示例

6.1 调试与测试参数

模拟运行：--dry-run显示操作但不实际下载或删除文件：

icloudpd --username [e-mail] --recent 5 --dry-run ./downloads

简化输出：--only-print-filenames仅输出文件路径，适合与其他工具集成：

icloudpd --username [e-mail] --only-print-filenames ./downloads > download_list.txt

6.2 完整场景示例

场景1：日常增量备份

icloudpd --username [e-mail] \
  --until-found 10 \
  --folder-structure "{:%Y/%m}" \
  --set-exif-datetime \
  --cookie-directory ~/.icloudpd/cookies \
  ./photos_backup

场景2：服务器自动同步

icloudpd --username [e-mail] \
  --watch-with-interval 3600 \
  --keep-icloud-recent-days 90 \
  --skip-videos \
  --xmp-sidecar \
  /mnt/nas/icloud_backup

七、常见问题解决

7.1 认证问题

问题：频繁要求输入验证码
解决：使用--cookie-directory保存认证状态：

icloudpd --username [e-mail] --cookie-directory ~/.icloudpd/cookies ./downloads

7.2 下载速度慢

问题：下载速度远低于网络带宽
解决：添加--threads参数增加并发连接（建议不超过5）：

icloudpd --username [e-mail] --threads 3 ./downloads

7.3 文件名乱码

问题：下载的文件出现中文或特殊字符乱码
解决：使用--keep-unicode-in-filenames参数：

icloudpd --username [e-mail] --keep-unicode-in-filenames ./downloads

7.4 API请求限制

问题：出现"Too many requests"错误
解决：延长同步间隔，减少并发请求：

icloudpd --username [e-mail] --watch-with-interval 7200 --threads 1 ./downloads

总结

iCloud照片下载器通过丰富的参数选项，提供了灵活高效的iCloud照片备份解决方案。无论是个人用户的简单备份需求，还是企业级的自动化同步系统，都能通过合理配置参数实现最佳效果。建议新用户从基础参数开始，逐步探索高级功能，构建符合自身需求的照片管理流程。

官方文档：docs/index.md