iCloud Photos Downloadericloudpd完整使用指南从安装、认证到三种同步模式与文件管理策略【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader导读icloud_photos_downloader 是一款开源的命令行工具用于把 iCloud 照片库批量下载到本地存储Linux、Windows、macOS 均可运行也可部署在 NAS 上。本文以仓库文档门户 docs/index.md 为骨架完整展开其功能特性、安装方式、认证流程、三种操作模式、文件命名与去重策略、资源尺寸与 RAW 处理并结合仓库源码如 src/icloudpd/cli.py、src/icloudpd/autodelete.py给出实现层面的佐证。读完本文你将掌握如何安装、配置并长期运行icloudpd把 iCloud 照片安全地同步到本机或 NAS。文档门户 docs/index.md 通过 Sphinxtoctree聚合了完整文档集包括 安装、认证、文件命名、操作模式、资源尺寸、RAW 资源、Web UI、NAS 部署 与 CLI 参考本文按此体系展开。一、项目核心功能总览项目定位是把 iCloud 照片下载到本地存储的命令行工具其功能清单收录于 README.md 的 Features 段落该段落正是 docs/index.md 通过include指令内嵌的主体内容三种操作模式Copy复制——从 iCloud 下载本地没有的新照片默认模式Sync同步——在 Copy 基础上删除 iCloud 中已删除移入最近删除相簿的本地文件对应--auto-delete选项Move移动——在 Copy 基础上删除 iCloud 中已存在于本地的资源并可选保留最近 N 天的照片对应--keep-icloud-recent-days选项。Live Photos 与 RAW 支持实况照片照片 视频两个独立文件以及 RAW含 RAWJPEG 双格式均可下载。自动去重处理同名照片冲突。一次性下载与持续监听--watch-with-interval选项可按固定间隔持续检查 iCloud 变化。增量运行优化--until-found与--recent选项减少重复检查。EXIF 元数据更新--set-exif-datetime选项可为缺少 EXIF 的照片写入拍摄时间。在动手之前请先确认 iCloud 账号满足两个前提条件否则 Apple 服务器会返回ACCESS_DENIED错误开启网页访问 iCloud 数据在 iPhone/iPad 上进入设置 Apple ID iCloud 访问 iCloud 网页数据并开启关闭高级数据保护ADP在设置 Apple ID iCloud 高级数据保护中关闭。因为icloudpd模拟的是网页访问方式开启 ADP 后该方式会被禁用详见 docs/authentication.md 的 ADP 说明。二、三种安装与运行方式安装文档 给出了三种运行icloudpd的方式用户可根据平台与使用习惯任选其一。1. 直接下载可执行文件从 GitHub Releases 下载对应平台Linux/macOS/Windows、x64/arm64 等的二进制可执行文件然后直接运行例如icloudpd --username youremail.address --directory photos --watch-with-interval 3600以 macOS 为例Intel 64 位二进制也可在 M1/M2/M3 的 ARM Mac 上运行完整步骤如下从 Releases 下载icloudpd-1.32.3-macos-amd64到本地目录赋予可执行权限chmod x icloudpd-1.32.3-macos-amd64终端启动icloudpd-1.32.3-macos-amd64Apple 提示无法检查恶意软件时点击OK打开系统设置 隐私与安全性找到被阻止的icloudpd-1.32.3-macos-amd64点击允许再次启动Apple 再次弹出警告时点击打开之后即可正常运行例如icloudpd-1.32.3-macos-amd64 --help。2. 通过包管理器安装Dockerdocker run -it --rm --name icloudpd -v $(pwd)/Photos:/data -e TZAmerica/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username myemail.address --watch-with-interval 3600镜像会把资源日期按指定的TZ时区转换再用于创建文件夹见 文件夹结构。查看全部参数docker run -it --rm icloudpd/icloudpd:latest icloudpd --helpWindows 注意事项使用%cd%代替$(pwd)或直接写全路径如-v c:/photos/icloud:/data且仅支持 Linux 容器。PyPIpip install icloudpd icloudpd --directory /data --username myemail.address --watch-with-interval 3600Windows建议pip install icloudpd --user并把C:\Users\用户名\AppData\Roaming\Python\Python版本\Scripts加入 PATH安装结束时终端会给出确切路径macOS把/Users/用户名/Library/Python/版本/bin加入 PATH。AURArch Linux手动安装git clone https://aur.archlinux.org/icloudpd-bin.git cd icloudpd-bin makepkg -sirc或使用 AUR 助手如 yayyay -S icloudpd-binnpmnpx --yes icloudpd --directory /data --username myemail.address --watch-with-interval 3600npm 包相关脚本与发布配置可参考仓库的 npm/icloudpd/package.json 与 scripts/build_npm。3. 从源码构建运行仓库提供了完整的构建脚本链位于 scripts 目录build_whl构建 wheel 包、build_bin1构建二进制、build_npm构建 npm 包、build_static构建静态资源、install_deps安装依赖等。依赖声明见 pyproject.toml。首次运行的常见错误首次运行可能遇到Bad Request (400)错误这通常是因为账号从未使用过 iCloud APIApple 服务器需要约 510 分钟准备照片数据。等待几分钟后重试即可若 30 分钟后仍出现该错误请带上脚本输出到项目 Issues 反馈。三、快速上手示例持续同步推荐用法把 iCloud 照片集合持续同步到本地icloudpd --directory /data --username myemail.address --watch-with-interval 3600--directory /data指定下载根目录--watch-with-interval 3600每 3600 秒1 小时重新检查一次 iCloud 变化无限循环运行同步逻辑可通过命令行参数调整完整列表用icloudpd --help查看。注意可执行文件名是icloudpd不是icloud后者是配套的会话管理工具。仅认证auth-only独立创建并授权会话如需要会完成 2SA/2FA 校验可用于检查会话是否仍然有效icloudpd --username myemail.address --password my_password --auth-only从 CLI 参考 可知--auth-only自 1.17.0 起只做认证并把令牌/ Cookie 持久化后退出不处理任何资源--cookie-directory可自定义认证结果Cookie/令牌的持久化目录默认是~/.pyicloud。四、三种操作模式详解操作模式文档 明确定义了三种模式模式行为启用参数Copy下载 iCloud 中本地不存在的资源默认模式Sync同 Copy另删除 iCloud 中已删除进入最近删除相簿的本地文件--auto-deleteMove同 Copy另删除 iCloud 中已存在于本地的资源可保留最近 N 天--keep-icloud-recent-days源码层面Sync 模式的删除逻辑实现在 src/icloudpd/autodelete.pyautodelete_photos函数遍历library_object.recently_deletediCloud 的最近删除相簿把本地匹配的文件os.remove删除dry-run 时走delete_file_dry_run只打印[DRY RUN] Would delete ...。--auto-delete参数在 src/icloudpd/cli.py 中定义帮助文本明确提示如果你在 iCloud 中恢复了照片它会再次被下载。Move 模式对应的--keep-icloud-recent-days X参数自 1.26.0 起取代已废弃的--delete-after-download会在资源下载完成或确认本地已有后删除 iCloud 中的副本但保留拍摄时间在指定天数内的资源设为 0 则全部删除。几个关键细节若使用了过滤器如--skip-videos被过滤掉的资源不会从 iCloud 删除——例如对全是视频的大图库运行--skip-videos将下载和删除都不发生资源年龄按 iCloud 报告的拍摄时间计算例如 2000 年拍摄、2024 年上传的资源到 2025 年算 25 岁该时间戳同样用于本地文件夹结构未指定该参数时不删除 iCloud 中的任何内容自 1.8.0 引入、1.26.0 废弃的--delete-after-download语义是下载完成后删除 iCloud 副本且只有实际下载过的远程资源才会被删除本地已存在的不会删。五、iCloud 认证机制认证文档 覆盖了从 MFA 到多账户配置的完整认证链路。多因素认证MFAApple 对新账号强制要求双重认证。启用后运行脚本会提示输入验证码会话有效期由 Apple 决定目前约两个月到期后需要重新认证。可以通过 SMTP 在认证过期时收到邮件提醒icloudpd --smtp-username yourgmail.com --smtp-password app_password邮件默认发给--smtp-username也可用--notification-email指定其他收件人。若使用 Gmail 且开启了双重认证需要在 Google 账户设置中生成应用专用密码App Password。MFA 提供者MFA Providers自 1.21.0 起MFA 验证码有两种输入途径用--mfa-provider选择console——终端输入默认webui——通过内置 Web 界面输入。在源码 src/icloudpd/cli.py 中--mfa-provider的choices只有console和webui两个值默认console与文档一致。密码提供者Password Providers自 1.20.0 起密码可以四种方式提供用--password-provider指定可多次指定顺序即检查顺序parameter——命令行--password参数keyring——系统密钥环console——终端交互输入webui——Web 界面输入1.21.0 起。例如--password-provider keyring --password-provider console表示先查密钥环没有再在终端询问。默认顺序是parameter、keyring、console。源码 src/icloudpd/cli.py 中该参数actionappend支持多次追加choices为[console, keyring, parameter, webui]。注意事项keyring 提供者会把有效密码写回密钥环console 与 webui 互不兼容且必须排在提供者列表最后因为它们无法被跳过使用--password直接传参并非好实践可能被日志记录或泄露优先考虑其他提供者。管理系统密钥环使用配套的icloud命令注意是icloud而非icloudpd可以存入或删除密钥环中的密码$ icloud --username jappleseedapple.com ICloud Password for jappleseedapple.com: Save password in keyring? (y/N)删除已存储的密码icloud --username jappleseedapple.com --delete-from-keyring多账号与多配置icloudpd支持一个账号多个配置或多个账号并行下载重复指定--username即可--username之后的选项只作用于该用户第一个--username之前的参数作为所有用户配置的默认值全局参数可出现在任意位置此能力自 1.32.0 起。两个账号示例icloudpd --use-os-locale --cookie-directory ./cookies --username aliceapple.com --directory ./alice --username bobapple.com --directory ./bob--use-os-locale是全局参数位置不限--cookie-directory ./cookies是两个用户的默认值因为会话与 Cookie 按用户名存为不同文件共用同一目录不会冲突--directory ./alice、--directory ./bob分别指定两人的下载目录。同一账号两套配置示例例如照片与视频分开下载icloudpd --cookie-directory ./cookies --username aliceapple.com --directory ./photos --skip-videos --username aliceapple.com --directory ./videos --skip-photos --use-os-locale--cookie-directory ./cookies是两套配置的默认值第一套照片下载到./photos跳过视频--skip-videos第二套视频下载到./videos跳过照片--skip-photos自 1.30.0 起--use-os-locale为全局参数。其他认证要点中国大陆访问iCloud.com 在中国大陆被屏蔽可用--domain cn参数改用.cn内部域名下载但社区反馈该参数效果不一--domain自 1.9.0 起默认.com仅支持.cn一个备选FIDO 硬件密钥不支持ADP 高级数据保护不支持icloudpd模拟网页访问而 ADP 会禁用网页访问偶发认证错误清理用户主目录下的.pyicloud子文件夹有时可解决部分认证错误。六、Web UI 与 NAS 部署Web UI自 1.21.0 起icloudpd可在8080 端口启动内置 Web 服务器从浏览器输入密码和 MFA 验证码代替终端交互。只有当webui被选作 MFA 提供者和/或密码提供者时Web 服务器才会启动。其实现位于 src/icloudpd/server模板文件在 src/icloudpd/server/templatespassword.html、code.html、status.html 等。NAS 部署示例NAS 文档 给出 TrueNAS 与 Synology 的部署参考。TrueNAS使用安装自定义应用功能创建icloudpd容器关键配置项包括字段值说明Application Nameicloudpd镜像仓库icloudpd/icloudpdtag 用latest容器入口参数icloudpd -u youremail.address -d /data --password-provider webui --mfa-provider webui --watch-with-interval 3600每项单独作为参数参数名与参数值拆成两个参数容器端口8080节点端口9090或主机上其他可用端口主机路径/mnt/my_pool/photos宿主机照片存储位置挂载路径/data容器内挂载点Portal 配置启用Portal 名称icloudpdHTTP 协议端口与节点端口一致9090应用启动后可通过浏览器访问 NAS 的 9090 端口或在 TrueNAS Portal 中点击icloudpd按钮进入 Web UI 输入密码和 MFA 码。Synology若遇到Failed to execv() /tmp/staticx-kJmNbp错误可 SSH 执行sudo mount /tmp -o remount,exec解决。文档还附带了大量非 x64 机型的架构对照表如 DS124 为 arm64、DS218j 为 arm64、DS116 为 arm32v7 等结论是x12 及更早的非 x86-64 型号不受支持。七、文件命名、去重与 Live Photos文件命名文档 解释了icloudpd如何依据资源元数据组织文件。文件夹结构icloudpd使用资源的**创建时间created date**构建目录层级可用--folder-structure调整自 1.7.0 起支持none值1.22.0 起支持 OS 区域设置。--folder-structure none将所有文件放入同一目录。格式遵循Python 字符串格式化语法例如{:%Y}只提取 4 位年份完整格式码见 Pythonstrftime文档。默认格式为{:%Y/%m/%d}年月日三级目录该默认值定义在 src/icloudpd/cli.py 中。部分格式码如%B打印完整月份名依赖语言环境。默认始终使用英语加--use-os-locale自 1.22.0 起后改用操作系统区域设置Linux/macOS 示例LC_ALLru_RU.UTF.8 icloudpd --use-os-locale --version同名文件去重大型图库易出现文件名冲突用--file-match-policy自 1.20.0 起选择去重策略name-id7在文件名上追加资源的不变唯一标识后缀如IMG_1234_QAZXSW.JPGname-size-dedup-with-suffix追加文件大小后缀如第二个同名资源变为IMG_1234-67890.JPG——这是默认策略。Live Photos 视频命名Live Photo 资源包含静态图片和短视频两个部分视频部分文件名可用--live-photo-mov-filename-policy自 1.18.0 起控制original视频沿用与图片相同的文件名建议搭配--file-match-policy name-id7避免与其他视频冲突suffix在图片文件名基础上追加后缀如图片IMG_1234.HEIC对应视频IMG_1234_HEVC.MOV——默认策略仅适用于 HEIC 静态图片。Unicode 文件名默认自 1.18.0 起出于兼容性考虑会从文件名中剥离 Unicode 字符指定--keep-unicode-in-filenames则保留。八、资源尺寸与 RAW 处理基本尺寸资源尺寸文档 指出iCloud 中每个资源可能提供多种下载尺寸original原始medium中等thumb缩略图用--size选择自 1.19.0 起可多次指定如--size original --size medium默认original。若指定尺寸在 iCloud 中不可用则回退下载original加--force-size则只下载指定尺寸。非原始尺寸的文件名会带后缀如IMG-1234-medium.JPG。另有--live-photo-size单独控制 Live Photo 资源的尺寸。特殊尺寸 adjusted自 1.19.0 起图片编辑结果作为特殊尺寸adjusted提供。两种常见用法只下载编辑版未编辑则下载原图--size adjusted同时下载编辑版与原始版--size adjusted --size original若编辑版与原图扩展名相同编辑版加-adjusted后缀。人像模式Portrait在 iCloud 中以编辑形式表示。RAW 资源RAW 文档 说明Apple ProRAW/ProRes以 DNG 格式拍摄的照片/视频可被正常下载第三方导入 RAW自 1.19.0 起支持 Adobe DNG同 ProRAW、Canon CR2/CR3/CRW、Sony ARW、Fuji RAF、Panasonic RW2、Nikon NRF/NEF、Pentax PEF、Olympus ORF 等格式。RAWJPEG 双表示自 1.19.0 起支持下载双表示资源一个表示为original尺寸另一个为alternative尺寸RAW 资源即使用alternative尺寸。iCloud 中资源的表示顺序可用--align-raw控制original——始终把 RAW 当作 originalalternative——始终把 RAW 当作 alternativeas-is——按 iCloud 数据原样处理。九、增量下载优化与其他实用参数CLI 参考文档 收录了全部命令行选项以下为高价值参数摘要增量优化--until-found X从最新到最旧检查资源的本地副本连续 X 次发现本地已存在后停止整个流程。适合增量更新减少本地 I/O 检查但不会填补本地存储的缺口。注意资源按添加到 iCloud 的时间而非拍摄时间排序检查--recent X只检查最近添加到 iCloud 的 X 个资源适合测试参数、控制下载量。相簿与图库--album X指定要下载的相簿自 1.31.0 起可多次指定多个相簿不指定则处理全部资源--list-albums列出所有可用相簿--library X选择图库默认 Personal Library自 1.16.0 起支持 iOS 16 共享图库--list-libraries列出可用图库同一时间只能使用一个图库。运行控制--watch-with-interval X自 1.10.0 起以 X 秒为间隔无限循环检查 iCloud 变化间隔过短可能触发 Apple 端限流暂无实证--dry-run自 1.15.0 起不实际改动本地与远程存储只执行认证、比对并报告差异适合试验新参数--only-print-filenames不下载只输出文件路径输出中不含其他信息--no-progress-bar隐藏进度条适合把输出重定向到文件--version报告当前版本及构建时的 commit 哈希与日期若此前指定了--use-os-locale日期按 OS 区域格式化。资源过滤与元数据--skip-videos/--skip-photos自 1.30.0 起/--skip-live-photos分别跳过视频、照片、实况照片--skip-created-before自 1.28.0 起/--skip-created-after自 1.29.0 起按拍摄时间过滤接受 ISO 时间戳如2025-06-01未指定时区则按本地时区或相对间隔如5d表示 5 天前--set-exif-datetime仅当资源缺少 EXIF 时把拍摄/创建时间写入 DateTimeOriginal 标签--xmp-sidecar自 1.25.0 起把附加数据导出为 XMP 旁路文件默认不导出。通知与 SMTP--smtp-username、--smtp-password、--smtp-host默认smtp.gmail.com、--smtp-port、--smtp-no-tls认证过期时的邮件通知配置--notification-email、--notification-email-from通知邮件的收件/发件地址--notification-script认证过期时执行的脚本。上述参数的解析与校验均可回溯到 src/icloudpd/cli.py 的 argparse 定义例如--folder-structure的默认值{:%Y/%m/%d}与类型校验validate_folder_structure、--password-provider的append多值行为等均可直接阅读源码核对。十、小结与下一步本文围绕 docs/index.md 的文档体系完整覆盖了icloudpd的功能特性、三类安装方式、认证与多账户配置、三种同步模式、文件命名与去重、资源尺寸与 RAW 策略以及 NAS 部署要点。实践建议先确认 iCloud 账号满足网页访问开启 ADP 关闭两个前提用--auth-only完成一次认证并验证会话用--dry-run配合--recent 10小范围试运行确认参数效果正式运行采用--watch-with-interval 3600持续同步并视需求选择 Sync--auto-delete或 Move--keep-icloud-recent-days模式。更多细节可直接查阅仓库中的 安装指南、认证、操作模式、文件命名、资源尺寸、RAW、Web UI、NAS 与 CLI 完整参考源码级实现可从 src/icloudpd/cli.py、src/icloudpd/autodelete.py 以及 tests 下的测试用例如 tests/test_autodelete_photos.py、tests/test_keep_icloud_mode.py继续深入。【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考