icloudpd iCloud照片本地备份实操：从首次认证到定时同步

icloudpd iCloud照片本地备份实操：从首次认证到定时同步

【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader

你手里的 iCloud 照片库攒了上万张照片，分散在几部手机里，而你想把它们合并进一块本地硬盘做一次完整备份，往后再定期补上增量。icloudpd 就是一个从 iCloud 照片库下载全部照片与视频的命令行工具，下面按完成这件事的先后顺序，讲清认证、运行和长期同步的做法。

📋 先划清边界：它做什么与不做什么

第三行值得多说一句：--threads-num参数在现行版本里已标记废弃且恒为 1，网上旧教程里"加线程提速"的说法不适用。

🔧 环境与最短路径：安装、前置条件与认证

安装只需一条命令：

pip install icloudpd

这条命令从 PyPI 装好icloudpd命令；习惯容器的人可用官方镜像icloudpd/icloudpd跑 Docker，也可用 npx 直接执行。Windows 上先pip install icloudpd --user，再把安装结束时显示的 Scripts 目录加入 PATH。

跑之前，账号设置上有几项前置条件，逐条核对：

• iPhone 上开启"在网页上访问 iCloud 数据"（设置 > Apple ID > iCloud）
• 关闭"高级数据保护"，否则服务器直接返回 ACCESS_DENIED
• 若账号开了两步验证，首次运行需接收并输入验证码
• 大陆账号加全局参数--domain cn（社区反馈效果不一）

装完后先做认证测试，它只建立会话、不下载任何东西：

icloudpd --username <你的邮箱> --password <你的密码> --auth-only

这条命令验证账号并把会话存在本地，之后运行不再需要输密码，直到两步验证过期（Apple 目前的周期约两个月）。

🎯 一条命令跑通：默认命令与两个微调变体

覆盖大多数场景的默认命令只有两个参数：

icloudpd --directory <备份目录> --username <你的邮箱>

参数说明：

• --directory：本地下载目录
• --username：Apple ID 邮箱
• 默认 Copy 模式，只取本地没有的文件
• 首次运行可能要输密码和验证码
• 默认按"年/月/日"子目录存放

跑完一轮，整个照片库就在本地了；之后再跑，只会补上新增的部分。

两个按需微调的变体。先用最近 100 张照片试跑、跳过视频，验证链路没问题：

icloudpd --directory <备份目录> --username <你的邮箱> --recent 100 --skip-videos

正式下载前想先看看会动哪些文件，加--dry-run空跑一次，它不修改本地系统也不改动 iCloud：

icloudpd --directory <备份目录> --username <你的邮箱> --dry-run

📈 三档进阶：偶尔跑一次、定期同步、长期常驻

偶尔跑一次：只补新增文件时，--until-found 10比--recent更准——它从最新加入的文件开始下，直到连续遇到 10 个已下载的文件才停：

icloudpd --directory <备份目录> --username <你的邮箱> --until-found 10

定期同步：交给 cron，在crontab -e里加一行，每天凌晨三点补一次增量：

0 3 * * * icloudpd --directory <备份目录> --username <你的邮箱> --until-found 10

仓库里附了带防重复运行逻辑的 cron 脚本样例，见 examples/cron_script.sh.example。

长期常驻：加--watch-with-interval 3600让进程每小时循环拉取，配合 SMTP 参数后，两步验证过期时（否则备份会静默失效）你会收到邮件：

icloudpd --directory <备份目录> --username <你的邮箱> \ --watch-with-interval 3600 \ --smtp-username <smtp邮箱> --smtp-password <smtp密码> \ --notification-email <通知收件邮箱>

用 Gmail 发信需要先开启两步验证并生成 App Password，细节在 docs/authentication.md。

🩺 故障速查：三个高频错误的定位与修复

登录即报 ACCESS_DENIED 或认证失败→ 定位：服务器在拒绝账号，原因几乎都在设置里。修复：在 iPhone 上确认"高级数据保护"已关、"在网页上访问 iCloud 数据"已开，改完重跑。

首次运行报 Bad Request (400)→ 定位：该账号此前没用过 iCloud 接口，Apple 服务器需要时间准备照片清单。修复：等 5–10 分钟后重跑同一命令；超过 30 分钟仍如此，把完整输出提交到项目 issue。

之前正常、现在提示凭据无效→ 定位：本地会话过期或密码改过。修复：删除用户主目录下的~/.pyicloud目录，再跑一次本文的--auth-only命令重建会话。

长尾提示一并放在这里：群晖 NAS 上容器报Failed to execv()时，用 SSH 执行sudo mount /tmp -o remount,exec规避，更多机型对照见 docs/nas.md。

📂 项目内资源索引

• docs/install.md：Docker、PyPI、AUR、npm 四种装法及各系统注意事项
• docs/mode.md：Copy、Sync、Move 三种模式的差异与对应参数
• docs/raw.md：--size与 RAW、原始尺寸的配合方式
• src/icloudpd/download.py：核心下载逻辑，想读代码从这里入手
• CONTRIBUTING.md：提 issue 与参与贡献的路径

收尾

接下来只做一件事：按本文的变体命令跑一次--recent 100 --skip-videos，跑完打开<备份目录>确认文件确实落位、日期目录结构正确。确认无误之后，再决定它是留在"偶尔跑一次"这一档，还是升级成定时任务或常驻进程。

【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader