跳到內容

從 QGIS 3.x 換到 4

外掛和舊專案要先檢查什麼

M0入門約 25 分鐘

草稿|尚未在 QGIS 4 實機驗證

QGIS 4 打開後,介面看起來和 3.x 差不多,於是直接把手上的專案打開來用。接著出現的狀況通常是:

  • 專案用到的外掛沒有自動出現,外掛管理員也搜不到。
  • 自己寫的 Python 腳本或處理模型(model)報錯。
  • 列印版面(layout)裡的圖例行為和以前不同。

這一頁說明 4.0 改了什麼、哪些東西最容易受影響,以及搬家前該做的檢查。

  • 一份你常用的 3.x 專案(.qgz 或 .qgs)與它用到的資料
  • 該專案用到的外掛清單:在 3.x 的 外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins ▸ 已安裝 Installed 分頁抄下來
  • 自己寫的 Python 腳本、處理模型(.model3)
  1. 先備份:把專案檔與資料整個資料夾複製一份。在 QGIS 4 存檔前,先另存成新檔名(例如加上 _qgis4),保留 3.x 可開的原檔。

  2. 核對外掛:逐一到 plugins.qgis.org 查每個外掛的版本表,看「最高 QGIS 版本」欄。4.99 代表宣告支援 QGIS 4;3.99 代表只支援 3.x。

  3. 在 QGIS 4 安裝支援的外掛:外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins,搜尋並安裝。

  4. 開啟專案(用複本):注意開啟時的訊息列。若有圖層找不到資料來源,QGIS 會跳出處理不可用圖層的對話框。

  5. 逐項檢查:

    • 圖層是否都正確顯示、坐標系是否正確(右下角的專案坐標系)
    • 列印版面的圖例:4.0 移除了圖例的「自動更新」勾選框,改成同步模式下拉選單,預設為「同步可見圖層」
    • 處理模型:在模型設計器開啟,確認每個元件的參數仍正確
    • Python 腳本:在 QGIS 4 的 Python 主控台實際執行一次
  6. 記錄差異:把不能用的外掛與替代方案寫在專案資料夾的說明檔,方便同事接手。

QGIS 的介面與大部分底層程式建立在 Qt 這套程式框架上。4.0 的更新紀錄把這次改版定位為「長期規劃的技術移轉」:把 QGIS 核心搬到 Qt6。Python 外掛透過 PyQt 呼叫 Qt,所以 Qt5 換 Qt6,等於 PyQt5 換 PyQt6,外掛程式碼裡的部分寫法必須修改。

對一般使用者來說,Qt6 換代本身不太會改變操作方式;影響集中在三處:

項目 影響 判斷方式
第三方外掛 作者要修改程式並更新宣告,才會出現在 QGIS 4 的外掛清單 外掛庫的最高版本欄
自寫 Python 腳本 PyQt5 專屬寫法、已廢除的 API 可能報錯 實際執行
舊版處理 API 更新紀錄提醒,QGIS 2.x 時代的 Processing API 等舊 API 在 4.x 不保證持續支援 腳本若是從很舊的教學抄來的,優先改寫

依外掛庫的 QGIS 4 移轉說明,外掛靠 metadata.txt 裡的 qgisMinimumVersion 與 qgisMaximumVersion 宣告支援範圍:

  • qgisMaximumVersion=4.99(或更高),外掛就會出現在 QGIS 4 的清單。
  • qgisMaximumVersion=3.99,只會出現在 3.x 的清單。
  • 早期的過渡旗標 supportsQt6=True 已不再有作用,只靠這個旗標的外掛已從 QGIS 4 清單移除。

所以「外掛管理員搜不到」不一定是外掛壞了,常常只是作者還沒更新宣告。反過來,宣告支援也不保證每個功能都正常,外掛庫的自動檢查(pyqgis4-checker)只是參考,不會擋下上架。

更新紀錄列出的部分項目:

  • 重新設計的歡迎頁
  • 可以自訂選單與工具列
  • 模型設計器的元件設定改在嵌入式面板,不再跳出對話框
  • 屬性表雙擊項目會選取並縮放到該圖徵
  • 註記(annotation)新增選取工具,可移動、刪除、縮放、旋轉
  • 列印版面的項目新增旋轉控點
  • 圖例的「全部更新 Update All」改為「重設 Reset」
  • 內建的 Night Mapping、Blend of Gray 等介面佈景改由外掛 API 提供
症狀 原因 解法
外掛管理員找不到某外掛 外掛最高版本仍是 3.99 查外掛庫版本表;不支援就留在 3.44 LTR,或找功能相近且支援 4 的外掛
自寫腳本出現 PyQt 相關錯誤 PyQt5 寫法在 PyQt6 不適用 參考 QGIS wiki 的 Qt6 移轉說明修改,或改用 qgis.PyQt 匯入
列印版面的圖例項目和以前不一樣 4.0 改成同步模式,預設同步可見圖層 在圖例屬性改同步模式,或改為手動管理項目
4.x 存檔後同事的 3.x 打不開或樣式跑掉 新版專案可能含舊版不認得的設定 交換專案前先確認雙方版本;需要交給 3.x 使用者時,保留 3.x 存的原檔

本單元目前沒有對應影片。

  1. 挑一個你常用的外掛,在外掛庫找出它目前最新版的最低與最高 QGIS 版本。
    • 檢查方式:外掛頁面版本表中的最低與最高 QGIS 版本兩欄,例如 QuickOSM 2.6.0 為 3.44.0 到 4.99.0(2026-11-22 查證)。
  2. 用 QGIS 4 開啟一份 3.x 專案的複本,找出一個列印版面,確認圖例的同步模式設定。
    • 檢查方式:圖例項目屬性中看得到同步模式下拉選單。
  3. 在 QGIS 4 的 Python 主控台執行 from qgis.PyQt.QtCore import QT_VERSION_STR; print(QT_VERSION_STR)。
    • 檢查方式:輸出的版本號以 6 開頭。