icloudpd把iCloud照片库完整备份到本地的实操教程【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader你的iCloud里可能已经积累了多年照片但这些数据完全托管在云端存储套餐会调整、条款会变而本地硬盘上没有一份副本。icloudpd是一款跨Windows、macOS、Linux的命令行工具能把iCloud照片库中的照片和视频批量下载到本地目录。本文按照验证认证 → 小批量试下载 → 全量备份 → 长期运行的顺序带你完整走一遍icloudpd使用教程。适用边界谁适合用iCloud照片备份工具谁不适合先说清楚icloudpd能做什么、不能做什么避免后面踩空。适合的情况想给整个iCloud照片库做一份本地副本并定期增量更新需要原始画质original尺寸、RAW文件含第三方相机RAW或Live Photos完整文件希望用脚本、定时任务把备份流程自动化。不适合的情况账户开启了高级数据保护icloudpd模拟的是网页端会话该模式下iCloud网页访问被禁用工具无法工作见认证说明想把本地照片上传回iCloud或想逐张管理、即时同步单张照片——它只做云到本地的批量下载不是同步客户端依赖硬件安全密钥FIDO登录的账户目前不受支持。它也不是只下载一次默认模式下本地已有的文件会被跳过重复运行就是增量同步。准备清单账户与系统的五个检查项开始之前把以下几项勾选完后面基本不会卡在认证上iCloud账户设置中已开启在网页上访问iCloud数据已关闭高级数据保护Advanced Data ProtectioniCloud照片已启用且近期的照片、视频已同步到云端本地装好了Pythonpip方式或Node.jsnpm方式或Docker三选一即可目标磁盘剩余空间大于照片库体积可先跳过下载前用--dry-run估算最小闭环从认证测试到首次全量备份安装包管理器是两条最短路径。有Python环境时pip install icloudpd习惯Node.js生态的话不落地安装、直接执行也行npx --yes icloudpd --help偏容器化的环境用Dockerdocker run -it --rm --name icloudpd \ -v $(pwd)/Photos:/data icloudpd/icloudpd:latest \ icloudpd --directory /data --username youexample.comWindows下pip安装后需要把%APPDATA%\Python\PythonXX\Scripts加入PATHmacOS类似安装结束时终端会打印该加到PATH的路径。完整步骤见安装文档。要从源码构建的话先克隆仓库再按构建脚本操作git clone https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader第一步只验证认证加上--auth-only工具只创建或刷新cookie与会话令牌然后立刻退出一个文件都不会下载icloudpd --username youexample.com \ --password 你的密码 --auth-only开了双重验证的账户会提示输入验证码。成功后会话保存在本地短期内不用重复输密码。首次运行若看到Bad Request (400)多半是Apple端还在为该账户准备照片数据等5到10分钟重试即可。第二步小批量试下载认证通了再碰真数据。先只下20张最近的照片、跳过视频检查文件名、文件夹结构和画质是否符合预期icloudpd --directory ~/iCloudBackup \ --username youexample.com --recent 20 --skip-videos--recent 20限定只处理最新的20项--skip-videos把体积最大的视频排除在外。文件落在--directory指定的目录里。第三步全量备份确认没问题后去掉--recent和--skip-videos并加--threads-num提高并发比如8个线程。默认下载original尺寸无需额外参数。策略分档按需求选参数组合同一套工具三类常见需求各有一套参数打法需求参数组合说明照片库很大数万张--threads-num 8首轮可先加--recent 5000大库先拉最近的部分验证吞吐再全量跑完只需要近期照片--recent 300 --skip-videos只覆盖最近300项配合定时任务滚动更新必须保留原始画质--size original --set-exif-datetime --align-raworiginal即原始文件RAWJPEG双表示时控制哪个算原始几个参数值得单独说明。--size默认就是original如果你只想要中等尺寸用于快速浏览可以指定medium文件会带-medium后缀规则见尺寸说明。RAW文件Apple ProRAW、Canon CR3、Sony ARW等的识别与RAWJPEG取舍逻辑在RAW文档里写得很细。--set-exif-datetime把照片的EXIF拍摄时间写回文件时间戳方便按时间排序和归档。异常处理三类现象与对应动作认证失败提示无效凭据或鉴权报错判断顺序账户设置 → 本地会话是否过期。动作确认已开启网页访问且关闭高级数据保护删除家目录下的.pyicloud文件夹清除旧会话后重新认证MFA账户重新输入一次验证码。下载缓慢进度条长时间不动判断当前是否网络高峰、卡住的是不是大体积视频。动作把--threads-num调高如4→8视频占大头时先用--skip-videos把照片下完改在网络空闲时段运行。磁盘空间不足下载中途报空间错误判断真实体积是否超出预期。动作先跑--dry-run不修改本地文件也不改iCloud只打印将写入的内容估算总量把--directory指向外置硬盘用--recent分几批完成。长期运行定时、常驻与通知一次性备份完成之后通常希望它持续跟着云端走。三种方式可以叠用定时触发。--watch-with-interval让工具常驻并按间隔检查增量单位是秒3600即每小时icloudpd --directory ~/iCloudBackup \ --username youexample.com --watch-with-interval 3600交给cron时仓库里的示例脚本做了防重复启动处理可以参考cron示例pgrep -f icloudpd exit 0 icloudpd --directory /data/photos \ --username youexample.com --recent 500Docker常驻同理把上面的命令塞进docker run -d即可挂载点用-v指定宿主机目录。通知。MFA会话大约两个月过期一次过期后定时任务会悄悄失效。配好SMTP后认证到期、运行结束都会发邮件在命令里加--smtp-username、--smtp-password、--smtp-host、--smtp-port收件人默认就是SMTP发件地址也可用--notification-email另指一个。最后提醒一句模式选择默认是复制只下本地没有的加--auto-delete变成同步云端移入最近删除的本地也删加--keep-icloud-recent-days N则会清理云端中N天以前的旧文件等于把iCloud空间释放出来。三种模式的差异见工作模式文档清理类参数不可随意混用。文档与源码入口参数速查以参数参考为准认证细节MFA、密码提供方式、大陆区域--domain cn在认证文档安装与平台差异Windows/macOS PATH、Docker、AUR在安装文档。想读代码的话下载主逻辑在src/icloudpd/download.py全部命令行参数定义在src/icloudpd/cli.py与iCloud服务的通信层在src/pyicloud_ipd/文件名规则可对照命名文档。【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考