外掛要上架官方外掛庫
授權、
外掛在自己和同事的電腦上用得很順,想放上 QGIS 官方外掛庫(plugins.qgis.org),讓任何人都能從 外掛管理員 Plugin Manager 直接安裝。第一次上傳常見的結果是:
- 上傳時 metadata 驗證失敗,被退回。
- 上傳成功但一直沒出現在外掛管理員,不知道卡在哪一關。
- 被拒絕,理由是首頁連結不對、程式庫不公開,或含有二進位檔。
官方外掛庫的規則不多,但每一條都會被實際檢查。
- 一支已經能正常運作的外掛(03 外掛骨架),且已完成 04 QGIS 4 遷移(若要支援 QGIS 4)。
- 一個公開的程式碼庫(例如 GitHub、GitLab),內容與要上傳的 zip 一致,並開啟 issue 追蹤。
- 一個 OSGeo ID(在 OSGeo 的網站申請),用來登入官方外掛庫。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
補齊
metadata.txt。除了必填欄位,上架時實際會檢查的還有:homepage:要能說明外掛功能的頁面;沒有專屬網頁就填程式庫或 README 的網址。tracker:程式庫的 issue 頁面。repository:公開、可直接瀏覽程式碼的程式庫(不能只是 zip 下載點)。changelog:更新版本時要寫。version:每次上傳都必須是新的版本號。tags:選有資訊量的標籤,避免「vector」這類太籠統的字。
-
放
LICENSE檔:純文字、檔名就是LICENSE、沒有副檔名。授權必須與 GPLv2 或更新版本相容,外掛用到的函式庫與素材也要遵守各自的授權。 -
打包 zip:
- zip 裡外掛要在自己的資料夾內(
your_plugin/metadata.txt,而不是 metadata.txt 直接在 zip 最上層)。 - 資料夾名稱只用 ASCII 英文字母、數字、底線、連字號,不能以數字開頭。
- 必要檔案:
metadata.txt、__init__.py、LICENSE;建議附 README 與圖示。 - 不要放:二進位檔、自動產生的
ui_*.py、resources_rc.py、.git、__pycache__等隱藏或暫存資料夾。 - 壓縮檔大小不超過 25MB。
- zip 裡外掛要在自己的資料夾內(
-
登入 plugins.qgis.org,按 Upload a plugin,選 zip 上傳。metadata 會自動讀取與驗證。
-
等待兩段檢查:
- 上傳確認:會收到 email,此時版本還看不到、也不能下載。
- 自動安全掃描:涵蓋程式碼品質、機密資訊偵測、可疑檔案分析等。全部通過才進入人工審核;有嚴重問題時該版本會被擋下,要上傳修正版。結果在該版本頁的 Security 分頁。
-
等人工審核。審核通常每天進行、週末除外,週五到週日上傳的多半要等到週一,從幾分鐘到幾天都有可能。核准後會收到通知,外掛就會出現在外掛管理員裡。
為什麼要 GPL 相容
Section titled “為什麼要 GPL 相容”官方外掛庫要求外掛授權與 GPLv2 或更新版本相容。背景是 QGIS 本身以 GPL 授權,而 Python 外掛在執行時直接 import QGIS 的模組、與 QGIS 一起運作(這是本站對規則背景的說明,不是官方條文)。實務上這代表外掛的原始碼必須能公開、別人可以修改再散布。不想公開原始碼的工具,就不適合放官方外掛庫,可以自建外掛庫(外掛管理員可以加入自訂的外掛庫網址)。
審核看什麼、不看什麼
Section titled “審核看什麼、不看什麼”審核的重點是「這個外掛的資訊是真的、可以追溯、不會弄壞使用者的 QGIS」,不是審查功能好不好用:
| 檢查項目 | 依據 |
|---|---|
| metadata 完整、連結都能開 | 首頁不描述外掛功能、連結失效,會被拒絕 |
| 程式碼在公開程式庫 | 只提供 zip 下載會被拒絕 |
| 不含二進位檔 | 認為非用不可,要先到 QGIS 開發者郵件論壇或向 QGIS PSC 說明 |
| 能安裝、不會讓 QGIS 當掉 | 審核者會隨機抽測,預期在 Unix 類系統與 Windows 都能用 |
| 更新版本有 changelog、版本號是新的 | 每次更新都會重新檢查連結 |
信任作者與快速核准
Section titled “信任作者與快速核准”有 can_approve 權限的使用者,自己上傳的版本可以在通過自動掃描後直接發布(上傳時勾選一個預設未勾的選項)。這個權限屬於「上傳者」本人:接手更新一支已核准的外掛,不會自動得到快速核准。沒有這個權限的人上傳新版本,該版本一律回到未核准狀態等待審核。
外掛名稱要唯一,名稱裡不要重複「plugin」這個字;與現有類似外掛的差別寫在 about。升級到 QGIS 4 時不要為了標示版本去改外掛名稱,官方外掛庫已有「QGIS 4 Ready」分類與 qgis4 標籤。外掛選單放在合適的位置(向量、網格、網路、資料庫),分析類工具可以考慮做成 Processing 提供者,讓使用者能放進模型與批次。
| 症狀 | 原因 | 解法 |
|---|---|---|
| 上傳時 metadata 驗證失敗 | 缺必填欄位、metadata.txt 非 UTF-8,或 changelog 內容造成解析錯誤 |
逐一對照必填欄位;有作者記錄過 changelog 中的裸百分比符號造成問題,改寫成「percent」或拿掉 |
| 版本號重複被拒 | version 與已上傳的版本相同 |
每次上傳都遞增版本號 |
| 審核被拒:連結無效 | homepage/tracker 指向不存在的頁面或與外掛無關的網站 |
改成程式庫 README 與 issue 頁面 |
| 安全掃描擋下 | 程式碼含疑似機密字串、可疑檔案,或靜態檢查發現嚴重問題 | 看版本頁 Security 分頁的細節,修正後上傳新版本 |
| 解壓後外掛管理員顯示錯誤 | zip 最上層就是 metadata.txt,沒有外掛資料夾 |
重新打包,讓 zip 內第一層是外掛資料夾 |
本單元目前沒有對應影片。
- 檢查自己外掛的
metadata.txt,列出缺少的必填欄位與上架會檢查的欄位(homepage、tracker、repository、changelog)。- 檢查方式:每個網址都能在無痕視窗打開,且頁面內容確實是這支外掛。
- 用 Git 的
git archive或手動壓縮,做出符合規則的 zip,再解壓到空資料夾檢查結構。- 檢查方式:解壓後只有一個外掛資料夾,裡面沒有
__pycache__、.git、ui_*.py、resources_rc.py。
- 檢查方式:解壓後只有一個外掛資料夾,裡面沒有
- 讀一支官方外掛庫上已核准外掛的 metadata(例如 06 讀一支真實外掛 的範例),比對自己的寫法。
- 檢查方式:能說出對方的
changelog、tags、category寫法與自己的差別。
- 檢查方式:能說出對方的
- How to publish plugins(plugins.qgis.org):打包規則、25MB 上限、GPLv2 相容授權
- Approval process(plugins.qgis.org):審核標準、安全掃描、審核時間、快速核准
- PyQGIS Developer Cookbook:Releasing your plugin:OSGeo ID、metadata 建議、打包、信任作者(撰寫時對應 QGIS 3.44)
- Migrate your plugin to QGIS 4