Immich iPhone 视频缩略图生成失败？几招帮你搞定 MOV 显示异常

最近在折腾自建相册的朋友们可能会遇到一个比较烦人的问题：把 iPhone 里的视频备份到 Immich 后，有的视频缩略图死活刷不出来，变成一片黑或者默认图标，但点进去播放又是完全正常的。

这种情况尤其在 MOV 格式的视频上出现得比较多。如果你的 Immich 服务器部署在低配机器上，或者用的是某些特定的容器环境，这个概率似乎更高。今天就来聊聊这背后的原因，以及几个亲测有效的解决办法，希望能帮你省去翻遍日志的时间。

为什么会出现这个问题？

首先我们要知道，iPhone 拍摄的视频通常采用 HEVC（H.265）编码，封装格式就是 MOV。这种编码虽然压缩率高，但对解码器的压力比传统的 H.264 要大不少。

Immich 在生成缩略图时，本质上是后台调用 FFmpeg 对视频进行截帧。如果 FFmpeg 的版本不兼容，或者服务器缺少必要的硬件加速支持（比如英特尔的 Quick Sync 或 NVIDIA 的 NVENC），在解析某些高码率的 iPhone 视频时就会“卡壳”，导致缩略图生成失败但又不影响原视频文件存储。

在docker-compose.yml中添加硬件加速设备映射

此外，Immich 对内存的消耗比较大，如果服务器剩余内存紧张，视频解码进程可能会被系统直接杀掉，导致缩略图生成中断。

解决方案一：调整 FFmpeg 硬件加速设置

如果你的服务器带有核显或独显，确保 Immich 能够调用它们是解决问题的关键。大多数 Docker 部署的 Immich 默认只使用 CPU 进行软解，这不仅慢，还容易出错。

你可以尝试修改 docker-compose.yml 文件，在 immich-server 和 immich-microservices 服务中增加设备映射。以英特尔核显为例，通常需要加入以下设备：

device:
  - /dev/dri/renderD128 # 用于视频加速

修改并重启容器后，再去上传几个 iPhone 视频试试，缩略图生成的速度和成功率通常会有显著提升。

解决方案二：启用兼容性转码

如果硬件加速暂时搞不定，或者你的机器实在拉不动 HEVC，可以让 Immich 在备份时自动进行转码。

进入 Immich 的管理后台（Administration），在 System Settings -> Job Settings -> Video Conversion 中，确保开启了硬件加速（如果有的话），并将转码策略设置为更兼容的模式。你可以强制将 H.265 转码为 H.264，虽然文件体积会稍微变大，但兼容性会好很多，缩略图生成也就不再是问题了。

解决方案三：手动重建缩略图

对于那些已经备份、但缩略图坏了的“历史遗留问题”，我们不需要重新上传视频，直接让后台重新跑一遍任务即可。

在 Immich 的 Administration -> Jobs 面板中，找到 Thumbnail Generation 或者 Video Metadata Extraction 相关的任务队列。你可以点击“Run Now”来手动触发。

如果后台任务一直显示失败或卡住，建议清理一下 Immich 的 Redis 缓存，或者重启 immich-microservices 微服务，把那些卡死的状态清空，然后再重新触发生成任务。

总结

Immich 虽然好用，但在处理 Apple 这种“特立独行”的 HEVC 格式时，偶尔还是会水土不服。大部分情况下，通过开启硬件加速或调整转码策略都能解决缩略图不显示的问题。

如果你还有其他关于自建相册的奇葩问题，欢迎在评论区交流，咱们一起避坑！

Immich中部分MOV视频缩略图显示为黑色或默认图标