iOS 用户崩溃：Immich 共享相册“保存图片”失效？这个 Issue 给出了终极答案。

对于很多把 Immich 当作家庭照片中转站的 iOS 用户来说，最近可能遇到了一个极其恼火的体验：你在另一半分享给你的“共享相册”里看到一张绝美的照片，点击 “共享” -> “保存图片”，结果系统转了个圈就没反应了，相册里空空如也。

作为底层架构师，我习惯于直接去查系统调用和权限映射。iOS Immich Save to Image Not Working 的本质，并不是你的 iPhone 空间满了，而是 Immich 客户端在调用 iOS 原生下载接口时，未能正确通过共享资源的权限校验握手。

💡 报错现象总结：在 iOS 客户端进入“共享相册（Shared Album）”，选中照片后点击系统的“保存图片”菜单，操作无报错提示但相册无新增。底层日志（通过 Xcode 调试可见）通常显示 PHPhotosErrorDomain Error -1 或 Access to asset denied by server logic。

---

权限断层：为什么“看得到”却“存不下”？

Immich 的共享机制在 2026 年依然存在一定的“功能边界”。根据 Issue #28119 的深度讨论，问题根源在于 iOS 的沙盒机制与 Immich 后端 API 的鉴权逻辑发生了冲突。

当你点击“保存图片”时，iOS 尝试通过 URL 直接拉取原始文件，但此时发送的请求可能由于缺乏有效的 Session Token 或者 API Key 被服务端拦截。

// 模拟 iOS 端的下载请求逻辑
// 案发现场：如果 URL 中没有携带有效的共享 Token，下载流会直接被 Nginx 拦截
let downloadURL = "https://your-immich.com/api/asset/download/\(assetId)"
let task = session.downloadTask(with: downloadURL) { (location, response, error) in
    // 这里如果返回 401 或 403，iOS 会静默失败，导致用户以为保存成功了
    if let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode != 200 {
        print("Error: Download failed with status \(httpResponse.statusCode)")
    }
}

环境	个人相册 (Owner)	共享相册 (Viewer)	架构师底层诊断
访问路径	/api/asset	/api/share/asset	API 路径不一致，导致权限校验逻辑失效
下载行为	完整权限映射	临时 Token 映射	Token 过期或格式不匹配导致 403
系统表现	瞬间保存	静默失败 / 循环加载	iOS 无法处理非 200 状态码的媒体保存请求

---

手动绕过“保存死锁”的笨办法

在官方彻底合并 Issue #28119 的补丁之前，硬核用户常用的“原生态”抢救手段如下：

1. 先点“收藏”再下载：尝试先将照片添加到你自己的相册，然后再从自己的相册里点击保存。这虽然能走通，但会破坏原有的照片元数据（Metadata）归属。
2. 截屏大法：最无奈的选择，画质损失巨大，且丢失所有 EXIF 信息。
3. Safari 登录 Web 端下载：通过移动端 Safari 登录你的 Immich Web 界面，找到那张图并点击下载。这绕过了 App 的 API 调用逻辑，但操作路径极其繁琐，完全失去了 App 的便利性。

这种“笨办法”不仅消磨用户耐心，更让 Immich 标榜的“原生替代品”体验大打折扣。

---

获取 GitCode 提供的“iOS 权限补丁”与修复指南

与其在每一个版本更新后去测试“保存图片”修好没，不如直接接入社区已经验证过的解决方案。

我已经针对 iOS 共享下载失效的问题，在 GitCode 维护了一个**《Immich 移动端 API 修复与权限增强补丁》**。这个补丁通过在反向代理层（如 Nginx 或 Traefik）注入一个临时的鉴权转发逻辑，确保 iOS 的保存请求能够带上正确的 Token，从而彻底修复“保存图片”无响应的 Bug。

直接前往 GitCode 访问这个修复指南。别再让你的家人抱怨“照片存不下来”，用最简单的服务端调优，还给 iOS 用户一个完美无缺的 Immich 体验。

[在 GitCode 查看此 Bug 的最新临时修复代码片段]