iCloud 照片怎么下载到本地？icloudpd 从安装到自动同步的实操说明

iCloud 照片怎么下载到本地？icloudpd 从安装到自动同步的实操说明

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

苹果的 iCloud 照片库缺少官方桌面端批量下载途径，网页手动导出又慢。icloudpd 是开源的 iCloud 照片下载命令行工具，用来做 iCloud 照片备份：把照片和视频存到本地磁盘，支持 Linux、Windows、macOS，NAS 也能跑。本文按检查、安装、首跑、长期运行的顺序讲一遍。

一、项目速览：它是什么、跑在哪些系统上、适合谁

icloudpd 定位单一：以命令行方式从 iCloud 下载照片和视频到本地文件夹，输出就是普通目录结构，方便后续用其他工具管理。

• 系统：Linux、Windows、macOS 均可，笔记本和台式机都能跑；NAS 上同样可以，下文安装部分给出常用路径。
• Live Photos（实况照片）：图片和对应的短视频作为两个文件分别下载。
• RAW：支持 RAW 格式，也包括 RAW+JPEG 组合素材。
• 去重：本地已有同名照片时按文件大小区分命名，不会互相覆盖。
• 增量下载：重复运行只下载新增照片，--until-found、--recent两个参数可进一步缩短耗时。

适合谁：想要一份完整本地照片库、或给 NAS 上盘做 iCloud 照片备份的用户。完整参数列表见 docs/reference.md。

二、跑之前的三项账户检查

这一步不做，后面会直接收到 ACCESS_DENIED（访问被拒绝）。在 iPhone 或 iPad 上确认三件事：

1. 开启"设置 > Apple ID > iCloud > 通过网页访问 iCloud 数据"，这是工具读取照片的前提。
2. 关闭"设置 > Apple ID > iCloud > 高级数据保护"，开启后相关接口不可用。
3. 确认两步验证可用：先手动登录一次 icloud.com，确保能收到短信或应用验证码，之后每次新会话认证都依赖它。

三、安装：按环境选一条路

三条路按环境挑一条：

1. Docker 一条命令：不装任何依赖，容器起来就能跑；多数 NAS 用户走这条，搜"icloudpd NAS 上怎么装"基本都指向它。
2. 包管理器：PyPI 执行pip install icloudpd；Node.js 环境执行npm install -g @icloudpd/icloudpd；Arch Linux 用户装 AUR 包即可。适合已有 Python 或 Node 环境的机器。
3. 源码构建：适合开发者或想使用最新功能的高级用户，构建脚本见 scripts/build_whl。

Docker 命令（把当前目录下的 Photos 挂载为容器内/data，即下载目录）：

docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data icloudpd/icloudpd:latest icloudpd --directory /data --username you@example.address

pip / npm 二选一：

pip install icloudpd npm install -g @icloudpd/icloudpd

注意可执行文件名是icloudpd，不是icloud。更多细节见 安装文档。

四、第一次完整备份怎么走

最小可运行命令如下（替换为你的 Apple ID 邮箱）：

icloudpd --directory ~/Photos --username you@example.com --watch-with-interval 3600

• --directory：照片保存的本地目录，不存在会自动创建。
• --username：iCloud 账户邮箱；首次运行会提示输入密码，开启两步验证的账户还要输入验证码。
• --watch-with-interval 3600：每 3600 秒（1 小时）检查一次 iCloud 是否有新照片并下载；只想跑一次就删掉该参数。

这是 iCloud 照片导出到本地最省事的形态：一条命令跑通即可。全部参数用icloudpd --help查看。

五、选哪种备份模式：复制、同步、移动

三种模式的行为差异（详见 docs/mode.md）：

• 复制（默认）：只下载本地没有的照片，本地已有文件一律不动。首次备份和日常增量都选它。
• 同步（加--auto-delete）：下载新照片，同时删除本地对应 iCloud 里已移除（进入"最近删除"相册）的文件。想让本地与 iCloud 完全一致时用。
• 移动（加--keep-icloud-recent-days N）：下载后从 iCloud 删除本地已有的照片，可保留最近 N 天。目标是给 iCloud 腾空间时用。

同步和移动都会删文件且不可逆，建议先跑一段时间复制模式，确认无误再切换。

六、让它长期干活：自动同步、文件夹组织与进度查看

• 自动同步：--watch-with-interval N让进程常驻并每 N 秒轮询一次 iCloud，有新增就下载，这是 icloudpd 自动同步设置的核心；不想常驻就用 cron 定时触发，示例脚本见 examples/cron_script.sh.example。
• 照片按月归档怎么做：--folder-structure控制目录层级，写法沿用 Python 日期格式，默认{:%Y/%m/%d}即年/月/日三级目录；只按年分写{:%Y}，全部放一个目录写none。详见 命名规则。
• 进度查看：下载过程在终端实时显示进度条；无交互的 SSH 环境可用--no-progress-bar关闭。

七、在浏览器里输密码：Web UI

1.21.0 版本起，icloudpd 可以在 8080 端口启动内置 Web 服务，把密码和 MFA 验证码的输入从终端搬到浏览器。典型场景：机器终端不方便交互（如某些 NAS 容器环境），或验证码发到手机上、希望在电脑上直接填写。需先将 MFA 或密码提供方式设为 webui，启动方法见 Web UI 文档 与 认证文档。

八、不 work 时查这四处

1. 访问被拒绝（ACCESS_DENIED）：回到第二节逐项重查"网页访问 iCloud 数据"开关和"高级数据保护"状态，并确认近期没有改过密码。
2. 下载中断或超时：检查网络是否稳定。icloudpd 是增量下载，重跑只会补未完成的部分，无需清空目录重来。
3. 认证反复失败：先用--auth-only单独验证登录流程，例如icloudpd --username 邮箱 --password 密码 --auth-only；能单独通过再跑下载。细节见 docs/authentication.md。
4. 找不到命令：确认执行的是icloudpd而非icloud，并用--version核对是否为预期版本。

到这里，iCloud 照片本地备份方法就闭环了：账户三项检查、一条安装路径、一次首跑，之后交给--watch-with-interval常驻。建议先用复制模式完整备份一遍，核对文件无误后，再决定是否开启同步或移动模式。

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