icloudpd：把 iCloud 照片完整备份到本地的轻量命令行方案
【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
icloudpd 是一个跨平台的命令行工具，用来把 iCloud 照片库中的照片和视频批量下载到本地目录。一条命令即可完成一次完整的 iCloud 照片备份：登录、遍历资源、按目录结构落地文件，并且支持增量运行——已下载过的文件不会重复拉取。它适合把云端照片库做一份持久化备份，也适合在 NAS 或服务器上长期定时运行。
icloudpd 安装方式选择
四条安装路径，按你现有的环境挑一条即可：
- pip（已有 Python 环境）：通用性最好，升级也最方便
pip install icloudpd- Docker（容器化部署 / NAS 场景）：不污染宿主机，适合长期挂在一个服务里跑
docker pull icloudpd/icloudpd- npm（Node 生态用户）：通过 npm 分发的是预编译二进制
npm install -g @icloudpd/icloudpd- 源码构建（需要定制或参与开发）：
git clone https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader cd icloud_photos_downloader构建方式参考仓库根目录的scripts/下的构建脚本（scripts/build_whl、scripts/build_npm等）与 pyproject.toml。
首次跑通：iCloud 照片本地备份认证
第一次运行前，先在 iCloud 侧确认三件事，这是认证失败最常见的根源：
- iCloud 账户已开启「在网页上访问 iCloud 数据」；
- 已关闭「高级数据保护」（Advanced Data Protection）——这是硬性前提，开启状态下工具无法完成认证；
- iCloud 照片库已开启且同步基本完成。
确认无误后，先只做认证、不下载，验证凭据可用：
icloudpd --username 你的邮箱@example.com --password 你的密码 --auth-only验证成功的标志：命令正常退出，且本地生成了会话凭证（默认保存在~/.pyicloud，可用--cookie-directory指定其他位置）。之后即使不再传--password，也会复用已有会话。
认证通过后，建议先小规模试下载一批文件，确认目录结构、文件命名、尺寸选择都符合预期：
icloudpd --directory ~/照片备份 \ --username 你的邮箱@example.com \ --recent 100 \ --skip-videos检查~/照片备份下是否按日期目录生成了文件、图片能否正常打开，这一步通过后再跑全量备份。
参数速查表
日常使用只需要下面这组参数，覆盖全量、增量、按尺寸、按时间范围等常见诉求：
| 参数 | 作用 | 什么时候用 |
|---|---|---|
--directory | 本地下载目录 | 每次运行都要指定备份落地位置 |
--auth-only | 只创建/刷新会话凭证，不下载 | 首次配置、会话过期后重新认证 |
--size | 下载尺寸，可选original/medium/thumb/adjusted/alternative | 要原片加 RAW 元数据用original；只备份缩略图省空间用thumb |
--recent | 只下载最近 N 张照片 | 试跑、定期增量拉取新增内容 |
--skip-videos | 不下载视频 | 网络慢、带宽受限时先只搬照片 |
--dry-run | 只模拟，不修改本地系统和 iCloud | 首次配置、想确认将要下载哪些文件时 |
--set-exif-datetime | 若缺失则写入 DateTimeOriginal EXIF 标签 | 照片归档后要保证拍摄时间元数据完整时 |
--threads-num | 并发线程数（当前版本已弃用，恒为 1） | 保留兼容用途，不必依赖它提速 |
--watch-with-interval | 循环运行，每 N 秒跑一轮 | 让进程自己保持在线，代替外部定时器 |
--until-found | 从最新照片往前下载，直到连续命中 N 张已下载的 | 增量同步的替代写法，比--recent更精确 |
几个组合习惯：
- 如果你有多台设备多个 Apple ID：同一命令行里可以写多组
--username ... --directory ...，每组是独立配置块，一次跑多个库； - 如果你是摄影师，需要原片和时间信息：
--size original --set-exif-datetime； - 如果你只想快速开始：
--recent 100 --skip-videos先试水，确认无误再去掉--recent做全量。
增量是内建的：默认就会跳过本地已存在的同名文件（去重策略可用--file-match-policy调整），所以全量备份之后反复运行同一命令，就是增量同步，无需额外的 skip 开关。
让 icloudpd 自动跑起来：定时、容器与邮件通知
三种自动化方案，按需选一种。
cron 定时（Linux/macOS，最常见）：每天凌晨 3 点跑一轮增量。
crontab -e # 添加： 0 3 * * * /usr/local/bin/icloudpd --directory /备份/照片 --username 你的邮箱@example.comDocker 常驻：用--watch-with-interval让容器内进程自己循环，每小时检查一次。
docker run -d \ --name icloudpd \ -v icloudpd_data:/data \ icloudpd/icloudpd \ --directory /data \ --username 你的邮箱@example.com \ --watch-with-interval 3600邮件通知：两步验证（2FA/2SA）会周期性过期，配好 SMTP 后工具会在需要重新认证时发邮件提醒，避免备份静默中断。
icloudpd --directory /备份/照片 \ --username 你的邮箱@example.com \ --smtp-username 邮箱@example.com \ --smtp-password 密码 \ --smtp-host smtp.example.com \ --smtp-port 587 \ --notification-email 接收邮箱@example.com间隔时间的参考值：拍摄频繁 3600 秒（1 小时），日常 21600 秒（6 小时），低频 86400 秒（24 小时）。
常见故障排查
认证失败（Authentication failed / Invalid credentials）现象：命令直接报错退出。原因：绝大多数是 iCloud 侧设置不满足——「在网页上访问 iCloud 数据」未开启，或「高级数据保护」仍开着。修复：到 iCloud 网页/系统设置里改好这两项；仍不行就清掉旧会话重新认证：
rm -rf ~/.local/share/icloudpd icloudpd --username 你的邮箱@example.com --password 你的密码 --auth-only下载速度慢、长时间无进展现象：进度停滞。原因：视频文件体积大，或网络高峰。修复：先用--skip-videos把照片搬完，视频后续单独补；同时避开网络高峰时段。
磁盘空间不足现象：下载到一半中断。原因：目标盘容量小于照片库实际体积。修复：先空跑估算规模：
icloudpd --dry-run --username 你的邮箱@example.com再用--recent 500之类分批搬，或把--directory指到外置盘/NAS 挂载点。
会话过期、需要重新输入验证码现象：跑了一段时间后卡在等待 2FA/2SA 验证码。修复：重新执行一次带--password和--auth-only的认证命令；长期方案见上一节的 SMTP 邮件通知。
建议的下载节奏与参数
按照片库规模和用途，给一个可照抄的节奏：
| 阶段 | 目的 | 命令要点 |
|---|---|---|
| 试跑 | 验证认证与目录结构 | --recent 100 --skip-videos --dry-run，确认无误后去掉--dry-run实下 |
| 首次全量 | 完整备份 | 去掉--recent，--directory指向容量充足的位置 |
| 日常增量 | 持续同步新增 | 同一命令重复运行（自动跳过已有文件），cron 每日一次或--watch-with-interval 3600 |
| 摄影师补充 | 原片与元数据 | 追加--size original --set-exif-datetime，RAW 对齐策略见--align-raw |
| 大库分批 | 规避磁盘/网络压力 | --recent 1000→--recent 2000逐步放大，或用--skip-created-before 30d划时间窗 |
继续深入：文档与源码
文档按主题拆分，出问题时按对应章节查即可：
- 安装细节：docs/install.md
- 认证流程（含 2FA/2SA、会话存储）：docs/authentication.md
- 三种工作模式（
mode）说明：docs/mode.md - RAW 与尺寸处理：docs/raw.md、docs/size.md
- 命名规则与文件夹结构：docs/naming.md
- NAS 部署：docs/nas.md
- Web UI 认证界面：docs/webui.md
- 全部参数参考：docs/reference.md
源码入口：
- 命令行参数定义：src/icloudpd/cli.py
- 下载主逻辑：src/icloudpd/download.py
- 配置与会话管理：src/icloudpd/config.py
- iCloud API 交互层：src/pyicloud_ipd/
- 版本变更记录：CHANGELOG.md
【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
