企业官网建设流程全解析

icloudpd 使用教程：iCloud 照片视频如何备份到本地

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

icloudpd 是一个开源的命令行工具，能把 iCloud 账户里的照片和视频库批量下载到本地磁盘，支持 Windows、macOS 和 Linux。它的仓库名为 icloud_photos_downloader，本文面向零基础的新手，按安装、认证、定时同步的顺序讲清 icloudpd 的完整用法。

🧩 它解决什么问题

• 云端照片没有本地副本：账户异常或订阅到期后照片可能无法访问，icloudpd 下载后的文件完全属于自己
• 释放 iCloud 空间：支持"移动"模式，旧照片下载完成后从 iCloud 删除，只保留近几天的照片
• 开源且运行在本地：照片不经过任何第三方服务器，Windows、macOS、Linux 乃至 NAS 都能跑
• 增量同步：重复运行时只下载新照片，已存在的文件自动跳过

📦 安装

三种方式按人群任选其一，装完后命令都叫icloudpd：

• pip（机器上已有 Python 环境的人）：pip install icloudpd，装完终端直接就能用
• Docker（想装在 NAS、服务器，或不想污染系统环境的人）：docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data icloudpd/icloudpd:latest icloudpd --directory /data --username you@example.com，把本地文件夹挂载进容器即可
• npm（前端开发者，免安装直接跑）：npx --yes icloudpd --directory /data --username you@example.com，npx 会自动拉取最新版执行

🚀 首次运行

前置条件

在 iPhone 或 iPad 上开启"设置 > Apple ID > iCloud > 在网页上访问 iCloud 数据"，并关闭"高级数据保护"（Advanced Data Protection，一种端到端加密模式），否则 Apple 服务器会返回 ACCESS_DENIED 错误。

认证测试

icloudpd --username you@example.com --password your-password --auth-only

该命令只做登录并把会话信息保存到~/.pyicloud，不下载任何文件；账户开启双重认证时会提示输入验证码。认证成功后，后续运行不再需要输入密码（双重认证约两个月过期一次）。

小批量验证

icloudpd --directory ~/iCloudPhotos --username you@example.com --recent 10

--recent 10只检查最近加入 iCloud 的 10 个资产，用来确认目录结构和文件能正常打开，再开始完整备份。首次运行若报 Bad Request (400)，等 5~10 分钟重试即可，那是 Apple 服务端在为你的图库准备数据。

📋 参数速查

其余参数（RAW 格式、文件夹结构、多账号等）完整列表见 docs/reference.md，也可以在终端执行icloudpd --help查看。

🎯 按需求选方案

家庭多账号

一条命令依次处理多个账户，每个账户的照片落到各自文件夹：

icloudpd --cookie-directory ./cookies \ --username dad@apple.com --directory ./dad \ --username kid@apple.com --directory ./kid

会话文件按账户名区分，所以共用一个 cookie 目录不会冲突。

摄影师原图

icloudpd --directory ~/Work/Originals \ --username pro@apple.com --size original \ --set-exif-datetime --threads-num 8

--size original下载原始尺寸文件，--set-exif-datetime把拍摄时间写进图片 EXIF，--threads-num 8用 8 个线程并行下载加快速度。RAW 文件的处理规则见 docs/raw.md。

轻量备份

icloudpd --directory ~/Photos/Backup \ --username you@example.com --recent 100 --skip-videos

只取最近 100 个资产并跳过视频，几分钟内就能完成一轮，适合先建立日常小批量备份的习惯。

🩹 排障手册

认证失败

• 现象：报 ACCESS_DENIED，或反复要求重新登录
• 处理：先确认"在网页上访问 iCloud 数据"已开启、"高级数据保护"已关闭；仍失败则删除主目录下的.pyicloud会话缓存，重新执行认证测试

下载速度慢

• 现象：大图库进度条推进缓慢
• 处理：把并行度提高到--threads-num 8；日常增量同步可加--until-found 10，连续 10 个文件本地已存在就提前停止，省去全量核对

存储空间不足

• 现象：下载中途因磁盘写满而中断
• 处理：先加--dry-run跑一遍，统计待下载资产的数量和体积，再把--directory指向外置硬盘或 NAS 上的大目录

⏰ 自动化

推荐用 cron 定时任务（仓库已附示例脚本 examples/cron_script.sh.example，内容如下）：

pgrep -f icloudpd && exit 0 icloudpd /data/photos \ --username you@example.com \ --recent 500 --auto-delete

pgrep那一行防止上一轮还没跑完时重复启动；--recent 500每轮只核对最近 500 个资产；--auto-delete让本地文件跟随 iCloud"最近删除"相册同步删掉。用crontab -e加入一行0 3 * * * /path/to/script.sh，即每天凌晨 3 点自动执行。

如果选择 Docker 部署，则把--watch-with-interval 3600放进容器命令常驻运行，每小时自查一次，无需系统级定时。

邮件通知只需加一组参数，即可在双重认证到期时收到提醒：

icloudpd --username you@example.com \ --smtp-username smtp@example.com --smtp-password app-password \ --smtp-host smtp.example.com --smtp-port 587 \ --notification-email receive@example.com

🔍 继续深入

• 文档：docs/install.md 安装细节（含 macOS 二进制的放行步骤）、docs/authentication.md 认证与多因子细节、docs/mode.md Copy/Sync/Move 三种模式、docs/reference.md 全部参数
• 源码：src/icloudpd/cli.py 命令行参数定义、src/icloudpd/download.py 下载主流程、src/pyicloud_ipd/ 与 iCloud 服务通信的接口层

最小可行第一步：先跑--auth-only确认账户能登录，再加--recent 10下载 10 个最近资产并确认文件可打开。这两步通过后，再决定目录规划和定时策略，整条备份链路就算跑通了。

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