iCloud照片下载器(icloud_photos_downloader)使用指南与参数详解

项目概述

iCloud照片下载器是一个命令行工具，专门用于从iCloud照片库中批量下载照片和视频。该工具提供了丰富的参数选项，可以满足不同场景下的照片备份需求。本文将全面解析该工具的各项参数及其使用场景。

核心参数解析

下载范围控制参数

增量下载优化参数

--until-found X 参数实现了智能增量下载机制：

• 从最新到最旧检查云端照片
• 仅下载本地缺失的照片
• 当连续X张照片都已存在于本地时停止检查
• 优势：大幅减少本地IO操作，适合定期同步场景
• 注意：不会检查并补全历史数据中的缺失文件

测试用下载参数

--recent X 参数专为测试设计：

• 仅处理最新的X张照片
• 便于快速验证配置参数
• 避免全量下载的长时间等待

相册与图库管理

相册选择参数

--album X 允许指定下载特定相册：

• 默认下载整个照片库
• 每次只能指定一个相册
• 配合--list-albums可查看所有可用相册

图库选择参数

--library X 支持多图库账户：

• 默认使用"个人图库"
• 企业版iCloud用户可能需要此参数
• --list-libraries可列出所有可用图库

高级功能参数

自动同步模式

--watch-with-interval X 实现持续同步：

• 以X秒为间隔定期检查更新
• 适合7×24小时运行的备份服务器
• 注意：间隔过短可能触发苹果的API限制

特定地区支持

--domain .cn 参数专为特定地区设计：

• 解决iCloud国际版的访问限制
• 将请求指向iCloud特定地区服务器(.cn)
• 默认使用国际版(.com)

安全与认证相关

认证参数最佳实践

• --username 指定Apple ID
• 避免直接在命令行使用--password
• 推荐使用系统密钥链等安全密码存储方式
• --auth-only 可单独测试认证流程

认证缓存管理

--cookie-directory 自定义认证缓存位置：

• 默认存储在用户目录的.pyicloud文件夹
• 可指定其他位置实现多账户隔离

文件处理策略

下载内容筛选

• --size 控制下载的图片质量
• --skip-videos 跳过视频文件
• --skip-live-photos 跳过实况照片
• --skip-created-before 按创建时间过滤

文件命名与存储

• --folder-structure 自定义目录结构
• --keep-unicode-in-filenames 保留特殊字符
• --set-exif-datetime 自动修复EXIF信息
• --xmp-sidecar 生成XMP元数据文件

云端管理功能

自动清理选项

--keep-icloud-recent-days X 实现智能清理：

• 下载后自动删除云端旧照片
• 保留指定天数内的新照片
• 基于照片拍摄时间而非上传时间
• 比废弃的--delete-after-download更安全可靠

实用调试参数

测试运行模式

--dry-run 参数提供安全检查：

• 测试完整运行流程
• 显示将会执行的操作
• 不实际修改任何文件

最小输出模式

--only-print-filenames 简化输出：

• 仅打印文件路径
• 适合与其他工具集成
• 无进度条等附加信息

总结建议

对于初次使用者，建议从简单参数组合开始：

1. 使用--recent测试基本功能
2. 添加--dry-run验证配置
3. 确认无误后移除--dry-run执行实际下载
4. 稳定运行后可考虑添加--watch-with-interval实现自动同步

对于高级用户，可以探索：

• 结合--keep-icloud-recent-days的自动云端清理
• 使用XMP元数据保留完整照片信息
• 配置SMTP通知实现监控告警

通过合理组合这些参数，可以构建出适合各种场景的iCloud照片备份解决方案。