icloudpd 完整使用指南5 个场景下的 iCloud 照片本地备份【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloadericloudpd 是跨平台命令行工具做 iCloud 照片备份把整个 iCloud 照片库完整下载到本地硬盘或 NAS。只管下载与同步没有图形界面。适合想把照片搬离单一云端的用户。这是什么 可以把 icloudpd 理解成 iCloud 照片库的单向搬运工它登录你的 Apple ID把照片一张张复制到本地文件夹。默认它只搬云端有、本地没有的新文件从不删除你本地已有的照片所以行为是安全且可预期的。运行前确认的 5 项准备 ✅Apple ID 密码若开了两步验证需随时能收到 6 位验证码。开启网页访问iPhone 上打开设置 Apple ID iCloud 在网页上访问 iCloud 数据。关闭高级数据保护同一菜单里关掉高级数据保护否则会报ACCESS_DENIED。一个运行环境装好 Docker、Python 或 npm 之一见 安装说明或直接下载对应平台的二进制。本地目录 空间准备目标文件夹磁盘容量要装得下照片库。可选大陆网络在大陆访问 iCloud 时准备加上--domain cn。首次备份的最小命令 先跑一条最短命令icloudpd --username youexample.com --directory ~/iCloud备份首次运行会提示输入密码开了两步验证的话再输入一次收到的验证码。成功后~/iCloud备份里会按年/月/日出现分层的照片文件夹出现这些目录就是成功的标志。不想真下手时有两个只读参数加--only-print-filenames只打印将下载的文件名加--auth-only只创建或刷新登录会话、不下载任何照片用来验证账号是否仍有效。5 个高频场景与对应参数 下面每个场景都在上面的基础命令上加参数。场景一每天只补新照片什么时候用首次全量备份完成后之后每天只想把新拍的照片补进来。命令基础命令加--until-found 5。预期效果从最新照片往下取连续遇到 5 张已下载过的就停跳过重复、只下增量第二次以后速度很快。场景二本地与云端保持一致什么时候用你在 iCloud 里删了照片希望本地备份跟着删两边保持一样。命令基础命令加--auto-delete。预期效果进入同步模式扫描 iCloud 的最近删除把本地对应文件一并删掉。这是真删本地文件执行前先加--dry-run模拟一遍。场景三下载完就删、释放 iCloud 空间什么时候用iCloud 存储告急想把旧照片搬本地、只把最近的留在云端。命令基础命令加--keep-icloud-recent-days 30。预期效果下载后把早于 30 天的照片从 iCloud 删掉进最近删除近 30 天的仍保留。设为0则下完全删慎用。场景四一次拉多个账号什么时候用家庭多台 iPhone或多套 Apple ID想一次拉取、各存各的目录。命令icloudpd --username aexample.com --directory ~/a \ --username bexample.com --directory ~/b预期效果按--username分组每个用户名后面的参数只作用于该账号写在第一个用户名之前的参数对所有账号生效。场景五只下原始大小或 RAW什么时候用摄影师要原始文件或本地空间有限、只要中等尺寸。命令加--size original或--size medium拍 RAW 的再加--align-raw original。预期效果只下指定尺寸的文件medium、thumb会在文件名加后缀避免和原图混淆RAWJPEG 可按需都按原始大小保留。进阶玩法定时、容器与调参 ⚙️持续监控加--watch-with-interval 3600程序无限循环、每 3600 秒检查一次新照片适合长期挂在 NAS 上省去单独配 cron。容器化在支持 Docker 的机器上一条命令跑起来docker run -it --rm -v ~/iCloud备份:/data \ icloudpd/icloudpd \ icloudpd --directory /data --username youexample.com --watch-with-interval 3600常用调参--skip-videos/--skip-live-photos跳过视频或实况照片先只下静态图。--set-exif-datetime写入 EXIF 拍摄时间方便按时间排序。--dry-run全程模拟不改动本地也不动 iCloud动手前必用。--keep-unicode-in-filenames保留中文等 Unicode 文件名。常见问题快修 首次运行报Bad Request (400)原因是 Apple 服务器还没为账号准备好 API 数据通常要几分钟到半小时。解决等 10–30 分钟重试仍失败就带日志去提 issue。登录过期、反复要验证码原因是两步验证会话约两个月过期。解决重跑一次--auth-only刷新会话或把密码存进 keyring。认证报ACCESS_DENIED原因是账号没开网页访问、或开着高级数据保护。解决iPhone 上开在网页上访问 iCloud 数据、关高级数据保护再清理~/.pyicloud会话目录重登。文件名被改、少了中文原因是默认会去掉非 ASCII 字符。解决加--keep-unicode-in-filenames。下载慢原因是网络或服务器负载且--threads-num已废弃、固定为 1。解决用--until-found做增量、挑网络空闲时段跑。资源导航 文档安装说明、认证、工作模式源码核心下载逻辑、iCloud 通信层全部参数运行icloudpd --help社区参与贡献、版本记录下一步建议先用--recent 10只下最近 10 张验证整条链路再换成--until-found做长期增量最后加--watch-with-interval挂到 NAS 上长期运行。【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
