Immich 出現 app major version not compatible 怎麼修

Immich App 顯示 app major version not compatible 是什麼意思

Immich 手機 App 出現 app major version not compatible，代表手機 App 和伺服器的主版本號（major version，版本號 3.2.4 裡的 3）對不上。最常見的情況是：伺服器已經升到 v3，手機 App 還停在 v2。大多數人的正確修法是更新手機 App，而不是把伺服器降回去。

這篇只處理這個錯誤。先確認兩邊的版本號，再依照是哪一邊落後，選對應的修法。最後把伺服器固定在一個主版本，讓同樣的事不會在半夜自己發生。

Immich 官方的版本相容規則

官方文件的升級頁（docs.immich.app，2026 年 10 月 13 日查閱）寫得很清楚：

The mobile app is typically compatible with the current and prior major version. However, the server is only compatible with the matching major version.

同一頁也寫了升級順序：

we recommend upgrading all mobile clients before upgrading the server to ensure compatibility.

換成實際情況來看：v3 的 App 可以連 v3 伺服器，也可以連 v2 伺服器。v2 的 App 只能連 v2 伺服器。所以順序是先更新所有手機，再升級伺服器。反過來做，舊 App 就會被擋在門外，畫面上出現的就是這個錯誤。

Immich 依照語意化版本（semantic versioning）發布，格式是 <major>.<minor>.<patch>。會破壞相容性的改動，包括 API 的改動，原則上只放在主版本。v3.0.0 在 2026 年 7 月 2 日發布，v2 的 App 因為 API 改動而無法再連上 v3 伺服器。截至 2026 年 10 月 13 日，最新版是 2026 年 10 月 8 日發布的 v3.3.1。

伺服器為什麼會自己跳到 v3

多數人沒有手動升級，伺服器是被某個自動機制推上去的。官方的 docker-compose.yml 這樣寫映像檔：

image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}

.env 裡沒有 IMMICH_VERSION，或值是 release，伺服器就會使用 release 這個標籤（tag）。release 永遠指向最新的正式版，所以 v3 一發布，它就指向 v3。接下來只要任何東西重新拉映像檔，伺服器就升上去了。常見的來源有這幾種：

• Watchtower 這類自動更新工具。它看到同一個標籤有新映像檔，就會拉下來並重建容器。
• Synology 的 Container Manager 專案或 QNAP 的 Container Station。重新建置專案或手動拉取映像檔時，release 會解析成當下最新的版本。
• NAS 的應用程式目錄（例如 TrueNAS Apps、Unraid 的社群套件）。這類套件的版本由目錄維護者更新，開了自動更新就會跟著跳主版本。
• 你自己跑了 docker compose pull，但沒注意到 .env 追的是最新版。

先查清楚兩邊的版本號

不要用猜的。兩個數字都看到，才知道是哪一邊落後。

伺服器的版本

Immich 有一個不需要登入的 API 端點，回傳伺服器的版本。在伺服器上執行：

curl -s http://localhost:2283/api/server/version

健康的回應長這樣：

{"major":3,"minor":2,"patch":4}

major 是 3，就代表伺服器已經在 v3。伺服器在 NAS 上的話，把 localhost 換成 NAS 的位址。也可以直接在手機瀏覽器打開同一個網址，這樣還能順便確認手機連得到伺服器。網頁介面登入後，左側欄底部的伺服器狀態區塊也會顯示版本號。

接著確認伺服器是被哪個標籤帶上去的。在 docker-compose.yml 所在的資料夾執行：

grep IMMICH_VERSION .env
docker compose images

docker compose images 的 TAG 欄位顯示 release，或 grep 什麼都沒印出來，就表示伺服器在追最新版。這就是它會自己升級的原因。

手機 App 的版本

在 Immich App 點右上角的個人頭像。打開的面板裡有一個資訊區塊，列出 App Version 和 Server Version 兩行。App Version 開頭是 2.，伺服器卻是 3，就是這篇要處理的情況。

情況一：手機 App 太舊，更新它

這是最常見的情況，也是最安全的修法。伺服器已經在 v3，就讓手機也到 v3。iPhone 到 App Store、Android 到 Play 商店搜尋 Immich 並按更新。用 F-Droid 安裝的 Android 手機，先看 F-Droid 上的版本號，見下一段。

更新後回到個人頭像的面板，App Version 應該要是 3. 開頭。重新開啟 App，錯誤應該就消失了，相簿和備份會照常同步。商店有時要幾個小時才會推送更新給所有人，看不到更新按鈕時，等一下再查一次。

F-Droid 使用者要多注意一步

F-Droid 上的版本會比官方發布晚。2026 年 7 月 5 日，YunoHost 論壇有使用者回報：伺服器從 2.7.5 升到 3.0.2 之後，F-Droid 上的 v3 App 還沒上架，原因是 F-Droid 的建置卡在一個 SQLite 相依套件的問題。這個延遲現在已經解決：2026 年 10 月 13 日查看 F-Droid 的 Immich 頁面，最新版是 3.3.1（10 月 12 日加入，比 GitHub 晚了四天）。你手機上的 F-Droid 版本如果還是 2.，它就連不上 v3 伺服器，先在 F-Droid 重新整理套件庫，再更新 Immich。

另一種做法是到 Immich 的 GitHub Releases 頁面 下載官方 APK。F-Droid 版和 GitHub 版的簽章可能不同，簽章不同時 Android 會拒絕覆蓋安裝，你得先解除安裝舊版。解除安裝只會清掉手機上的 App 設定和登入狀態，伺服器上的照片不受影響。重新登入後，App 會比對手機相簿和伺服器上已有的檔案，不會整批重新上傳。

情況二：伺服器是不小心升上去的

有些人無法馬上更新所有手機，例如家人的手機不在身邊，或某台舊裝置只能用 F-Droid。這時很容易想直接把 IMMICH_VERSION 改回 v2。不要這樣做。

原因是資料庫遷移（database migration）。v3 伺服器第一次啟動時，會修改 Postgres 資料庫的結構，讓它符合 v3 的程式。v2 的程式不認得改過的結構，所以直接換回 v2 映像檔，是讓舊程式去讀新格式的資料庫。官方文件的立場也很明確：

Downgrading to an earlier version, even within the same minor version, is not supported.

所以你只有兩條安全的路：

1. 留在 v3，更新所有 App。 這是推薦的做法。舊手機暫時連不上，但伺服器和資料都沒事，照片也還在。
2. 用升級前的資料庫備份還原，並搭配 v2 的映像檔。 這是唯一安全的回頭路。Immich 預設會定期自動匯出資料庫備份，存在上傳目錄底下的 backups 資料夾。先找到伺服器跳版之前的那一份，再照 Immich 資料庫備份與還原的完整步驟 操作。不確定上傳目錄在 NAS 的哪裡，先看 Immich 在 Docker 裡把照片和資料庫存在哪裡。

選第二條路要清楚代價：舊備份不包含跳版之後的變更。之後新建的相簿、標記和新上傳的紀錄都不在那份資料庫裡。還原完成後，記得把 IMMICH_VERSION 固定在當時的 v2 版本，例如 v2.7.5，否則下一次拉取映像檔又會回到 v3。

v3 也有和手機無關的破壞性改動，簡單列一行：v3 移除了 pgvecto.rs 支援，所以還沒遷移到 VectorChord 的舊安裝要先照官方的遷移指南處理；它也移除了已棄用的環境變數，並改了多個 API 端點，會影響第三方工具。伺服器升上 v3 後如果連網頁都打不開，問題多半在這裡，不是手機 App。

把 IMMICH_VERSION 固定在主版本

問題解決之後，把伺服器固定在一個主版本。Immich 提供 v3 這種主版本標籤：它會跟著 v3.x.x 的修正和小版本更新，但不會自己跳到 v4。編輯 .env，加入或修改這一行：

IMMICH_VERSION=v3

然後拉取映像檔並重建容器：

docker compose pull
docker compose up -d

再確認一次：

docker compose images
curl -s http://localhost:2283/api/server/version

TAG 欄位應該顯示 v3，API 回傳的 major 應該是 3。從這裡開始，Watchtower 或任何自動更新工具都只會在 v3 範圍內更新，伺服器不會在你更新手機之前就跳到下一個主版本。

在 Synology 上，.env 和 docker-compose.yml 放在同一個專案資料夾。用 File Station 編輯 .env，再到 Container Manager 停止專案並重新建置。QNAP Container Station 的做法相同。透過 NAS 應用程式目錄安裝的 Immich，通常看不到 .env，這時要到該套件的設定裡關掉自動更新。

下一個主版本 v4 出來時，要照官方的順序：先讀發布說明，先更新所有手機 App，確認 App Version 都到了新主版本，最後才把 .env 改成 v4。改之前先做一份備份，完整流程可以參考 備份並升級 Docker Compose 服務的標準流程。還沒決定 Immich 要長期放在 NAS 還是 VPS，可以先讀 儲存型 VPS 和家用 NAS 的比較。

FAQ

為什麼 Immich App 會顯示 app major version not compatible？

因為手機 App 的主版本落後伺服器。官方文件說 App 通常相容目前和前一個主版本，所以 v3 的 App 也能連 v2 伺服器，但 v2 的 App 不支援 v3 伺服器，v2 App 一看到伺服器的主版本和自己不同，就會顯示這個訊息。最常見的是伺服器已經升到 v3，手機還在 v2。用 curl -s http://localhost:2283/api/server/version 看伺服器的 major，再到 App 的個人頭像面板看 App Version，就能確認是哪一邊落後。

可以直接把 IMMICH_VERSION 改回 v2 嗎？

不行。v3 伺服器第一次啟動時已經修改了資料庫結構，v2 的程式不認得新結構，而 Immich 官方明確表示不支援降版。安全的做法是留在 v3 並更新所有手機 App。一定要回到 v2，只能用升級前的資料庫備份還原，再搭配 v2 的映像檔，並接受跳版之後的變更會遺失。

F-Droid 上的 Immich 還是 2.x，要怎麼辦？

F-Droid 的版本通常比官方發布晚，2026 年 7 月就有使用者回報 v3 App 因為建置問題延遲上架。現在 F-Droid 已經有 v3 App，2026 年 10 月 13 日查看時最新是 3.3.1。先在 F-Droid 重新整理套件庫並更新 Immich，或改裝 Immich GitHub Releases 頁面上的官方 APK。兩者簽章不同時，要先解除安裝 F-Droid 版。伺服器上的照片不會因此受影響。

怎麼避免 Immich 伺服器自動升到下一個主版本？

在 .env 裡設定 IMMICH_VERSION=v3，然後執行 docker compose pull 和 docker compose up -d。v3 標籤只會跟著 v3.x.x 更新，不會跳到 v4，所以 Watchtower 也會停在 v3。用 NAS 應用程式目錄安裝的話，要在套件設定裡關掉自動更新。