icloudpd把 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 安装方式选择四条安装路径按你现有的环境挑一条即可pip已有 Python 环境通用性最好升级也最方便pip install icloudpdDocker容器化部署 / NAS 场景不污染宿主机适合长期挂在一个服务里跑docker pull icloudpd/icloudpdnpmNode 生态用户通过 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-datetimeRAW 对齐策略见--align-raw大库分批规避磁盘/网络压力--recent 1000→--recent 2000逐步放大或用--skip-created-before 30d划时间窗继续深入文档与源码文档按主题拆分出问题时按对应章节查即可安装细节docs/install.md认证流程含 2FA/2SA、会话存储docs/authentication.md三种工作模式mode说明docs/mode.mdRAW 与尺寸处理docs/raw.md、docs/size.md命名规则与文件夹结构docs/naming.mdNAS 部署docs/nas.mdWeb UI 认证界面docs/webui.md全部参数参考docs/reference.md源码入口命令行参数定义src/icloudpd/cli.py下载主逻辑src/icloudpd/download.py配置与会话管理src/icloudpd/config.pyiCloud 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），仅供参考