從 QGIS 3.x 換到 4
外掛和舊專案要先檢查什麼
QGIS 4 打開後,介面看起來和 3.x 差不多,於是直接把手上的專案打開來用。接著出現的狀況通常是:
- 專案用到的外掛沒有自動出現,外掛管理員也搜不到。
- 自己寫的 Python 腳本或處理模型(model)報錯。
- 列印版面(layout)裡的圖例行為和以前不同。
這一頁說明 4.0 改了什麼、哪些東西最容易受影響,以及搬家前該做的檢查。
- 一份你常用的 3.x 專案(
.qgz或.qgs)與它用到的資料 - 該專案用到的外掛清單:在 3.x 的 外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins ▸ 已安裝 Installed 分頁抄下來
- 自己寫的 Python 腳本、處理模型(
.model3)
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
先備份:把專案檔與資料整個資料夾複製一份。在 QGIS 4 存檔前,先另存成新檔名(例如加上
_qgis4),保留 3.x 可開的原檔。 -
核對外掛:逐一到 plugins.qgis.org 查每個外掛的版本表,看「最高 QGIS 版本」欄。4.99 代表宣告支援 QGIS 4;3.99 代表只支援 3.x。
-
在 QGIS 4 安裝支援的外掛:外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins,搜尋並安裝。
-
開啟專案(用複本):注意開啟時的訊息列。若有圖層找不到資料來源,QGIS 會跳出處理不可用圖層的對話框。
-
逐項檢查:
- 圖層是否都正確顯示、坐標系是否正確(右下角的專案坐標系)
- 列印版面的圖例:4.0 移除了圖例的「自動更新」勾選框,改成同步模式下拉選單,預設為「同步可見圖層」
- 處理模型:在模型設計器開啟,確認每個元件的參數仍正確
- Python 腳本:在 QGIS 4 的 Python 主控台實際執行一次
-
記錄差異:把不能用的外掛與替代方案寫在專案資料夾的說明檔,方便同事接手。
Qt6 換代是什麼
Section titled “Qt6 換代是什麼”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 不保證持續支援 | 腳本若是從很舊的教學抄來的,優先改寫 |
外掛相容性怎麼宣告
Section titled “外掛相容性怎麼宣告”依外掛庫的 QGIS 4 移轉說明,外掛靠 metadata.txt 裡的 qgisMinimumVersion 與 qgisMaximumVersion 宣告支援範圍:
qgisMaximumVersion=4.99(或更高),外掛就會出現在 QGIS 4 的清單。qgisMaximumVersion=3.99,只會出現在 3.x 的清單。- 早期的過渡旗標
supportsQt6=True已不再有作用,只靠這個旗標的外掛已從 QGIS 4 清單移除。
所以「外掛管理員搜不到」不一定是外掛壞了,常常只是作者還沒更新宣告。反過來,宣告支援也不保證每個功能都正常,外掛庫的自動檢查(pyqgis4-checker)只是參考,不會擋下上架。
4.0 介面上看得到的變化
Section titled “4.0 介面上看得到的變化”更新紀錄列出的部分項目:
- 重新設計的歡迎頁
- 可以自訂選單與工具列
- 模型設計器的元件設定改在嵌入式面板,不再跳出對話框
- 屬性表雙擊項目會選取並縮放到該圖徵
- 註記(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 存的原檔 |
本單元目前沒有對應影片。
- 挑一個你常用的外掛,在外掛庫找出它目前最新版的最低與最高 QGIS 版本。
- 檢查方式:外掛頁面版本表中的最低與最高 QGIS 版本兩欄,例如 QuickOSM 2.6.0 為 3.44.0 到 4.99.0(2026-11-22 查證)。
- 用 QGIS 4 開啟一份 3.x 專案的複本,找出一個列印版面,確認圖例的同步模式設定。
- 檢查方式:圖例項目屬性中看得到同步模式下拉選單。
- 在 QGIS 4 的 Python 主控台執行
from qgis.PyQt.QtCore import QT_VERSION_STR; print(QT_VERSION_STR)。- 檢查方式:輸出的版本號以 6 開頭。
- QGIS 4.0 更新紀錄:Qt6 移轉、介面變化、舊 API 支援聲明
- 外掛庫 QGIS 4 移轉說明:
qgisMaximumVersion與supportsQt6的規則 - QGIS 發布時程表
- 外掛使用手冊