icloud-photos-downloader（简称icloudpd）是一款基于Python开发的开源命令行工具，核心用于跨平台批量下载、同步iCloud照片库中的照片与视频，支持自动化备份、增量同步与自定义筛选，适合个人数据备份、本地归档等场景，遵循MIT许可证。以下从核心信息、功能、安装与使用、注意事项等方面详细介绍：
核心基础信息
| 项目 | 详情 |
| 开发者 | Nathan Broadbent，社区维护 |
| 项目地址 | https://github.com/icloud-photos-downloader/icloud_photos_downloader |
| 编程语言 | Python |
| 支持平台 | Linux、Windows、macOS，也可在NAS、树莓派等设备运行 |
| 运行方式 | Docker、PyPI、AUR、npm、预编译二进制文件、源码编译 |
| 核心交互 | 通过PyiCloud库与Apple的iCloud API交互，支持两步验证 |
核心功能
1. 三种核心操作模式Copy（默认）：仅下载iCloud新增照片/视频，不改动云端与本地已有文件。
a. Sync（–auto-delete）：下载新增文件，同时删除本地已在iCloud中删除的文件，保持本地与云端一致。
b. Move（–delete-after-download等）：下载后删除云端文件，可通过–keep-icloud-recent-days保留近期文件。
2. 高效批量与增量同步支持断点续传、自动去重，避免重复下载。
a. 可通过–watch-with-interval持续监视iCloud变更，定期增量同步；–until-found、–recent等参数优化增量运行效率。
3. 精准筛选与自定义按相册（–album）、日期（–recent等）、人脸识别相册等筛选下载，–list-albums可列出可用相册。
a. 支持Live Photos（图片视频分开存储）、RAW格式（含RAW+JPEG），保留EXIF元数据并可通过–set-exif-datetime更新元数据时间。
b. 自定义下载尺寸、本地文件夹结构（如按年/月/日归档）。
4. 安全与自动化支持两步验证，可配置邮箱接收授权失效提醒。
a. 可通过定时任务实现无人值守的自动备份，适合NAS等设备长期运行。
安装与快速使用
1. 安装方式（推荐优先级排序）Docker：环境隔离、依赖管理简单，适合长期使用。
a. PyPI：pip install icloud_photos_downloader，适合已配置Python环境的用户。
b. 预编译二进制文件：直接下载对应系统的可执行文件，适合临时使用。
c. 其他：Arch Linux可通过AUR安装，也可通过npm安装。
2. 基础使用步骤准备工作：在iPhone/iPad中开启“设置 > Apple ID > iCloud > 网页访问iCloud数据”，关闭“高级数据保护”，否则可能出现访问错误。
a. 基础命令：icloudpd –username 你的AppleID –password 你的密码 –directory 本地保存路径。
b. 进阶示例：指定相册并同步，icloudpd –username xxx –directory ./photos –album “旅行相册” –auto-delete。
注意事项
1. 账号安全：避免在命令行明文输入密码，建议使用系统密钥链等安全存储方式；两步验证过期后需重新授权。
2. 地区适配：中国大陆用户建议添加–domain .cn参数，将请求指向iCloud中国服务器。
3. 功能限制：不支持iCloud共享相册下载，部分特殊格式可能存在兼容性问题，需关注项目更新日志适配情况。