跳到內容

外掛要上架官方外掛庫

授權、metadata 與審核各要準備什麼

M10專業約 40 分鐘

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

外掛在自己和同事的電腦上用得很順,想放上 QGIS 官方外掛庫(plugins.qgis.org),讓任何人都能從 外掛管理員 Plugin Manager 直接安裝。第一次上傳常見的結果是:

  • 上傳時 metadata 驗證失敗,被退回。
  • 上傳成功但一直沒出現在外掛管理員,不知道卡在哪一關。
  • 被拒絕,理由是首頁連結不對、程式庫不公開,或含有二進位檔。

官方外掛庫的規則不多,但每一條都會被實際檢查。

  • 一支已經能正常運作的外掛(03 外掛骨架),且已完成 04 QGIS 4 遷移(若要支援 QGIS 4)。
  • 一個公開的程式碼庫(例如 GitHub、GitLab),內容與要上傳的 zip 一致,並開啟 issue 追蹤。
  • 一個 OSGeo ID(在 OSGeo 的網站申請),用來登入官方外掛庫。
  1. 補齊 metadata.txt。除了必填欄位,上架時實際會檢查的還有:

    • homepage:要能說明外掛功能的頁面;沒有專屬網頁就填程式庫或 README 的網址。
    • tracker:程式庫的 issue 頁面。
    • repository:公開、可直接瀏覽程式碼的程式庫(不能只是 zip 下載點)。
    • changelog:更新版本時要寫。
    • version:每次上傳都必須是新的版本號。
    • tags:選有資訊量的標籤,避免「vector」這類太籠統的字。
  2. 放 LICENSE 檔:純文字、檔名就是 LICENSE、沒有副檔名。授權必須與 GPLv2 或更新版本相容,外掛用到的函式庫與素材也要遵守各自的授權。

  3. 打包 zip:

    • zip 裡外掛要在自己的資料夾內(your_plugin/metadata.txt,而不是 metadata.txt 直接在 zip 最上層)。
    • 資料夾名稱只用 ASCII 英文字母、數字、底線、連字號,不能以數字開頭。
    • 必要檔案:metadata.txt、__init__.py、LICENSE;建議附 README 與圖示。
    • 不要放:二進位檔、自動產生的 ui_*.py、resources_rc.py、.git、__pycache__ 等隱藏或暫存資料夾。
    • 壓縮檔大小不超過 25MB。
  4. 登入 plugins.qgis.org,按 Upload a plugin,選 zip 上傳。metadata 會自動讀取與驗證。

  5. 等待兩段檢查:

    • 上傳確認:會收到 email,此時版本還看不到、也不能下載。
    • 自動安全掃描:涵蓋程式碼品質、機密資訊偵測、可疑檔案分析等。全部通過才進入人工審核;有嚴重問題時該版本會被擋下,要上傳修正版。結果在該版本頁的 Security 分頁。
  6. 等人工審核。審核通常每天進行、週末除外,週五到週日上傳的多半要等到週一,從幾分鐘到幾天都有可能。核准後會收到通知,外掛就會出現在外掛管理員裡。

官方外掛庫要求外掛授權與 GPLv2 或更新版本相容。背景是 QGIS 本身以 GPL 授權,而 Python 外掛在執行時直接 import QGIS 的模組、與 QGIS 一起運作(這是本站對規則背景的說明,不是官方條文)。實務上這代表外掛的原始碼必須能公開、別人可以修改再散布。不想公開原始碼的工具,就不適合放官方外掛庫,可以自建外掛庫(外掛管理員可以加入自訂的外掛庫網址)。

審核的重點是「這個外掛的資訊是真的、可以追溯、不會弄壞使用者的 QGIS」,不是審查功能好不好用:

檢查項目 依據
metadata 完整、連結都能開 首頁不描述外掛功能、連結失效,會被拒絕
程式碼在公開程式庫 只提供 zip 下載會被拒絕
不含二進位檔 認為非用不可,要先到 QGIS 開發者郵件論壇或向 QGIS PSC 說明
能安裝、不會讓 QGIS 當掉 審核者會隨機抽測,預期在 Unix 類系統與 Windows 都能用
更新版本有 changelog、版本號是新的 每次更新都會重新檢查連結

有 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 內第一層是外掛資料夾

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

  1. 檢查自己外掛的 metadata.txt,列出缺少的必填欄位與上架會檢查的欄位(homepage、tracker、repository、changelog)。
    • 檢查方式:每個網址都能在無痕視窗打開,且頁面內容確實是這支外掛。
  2. 用 Git 的 git archive 或手動壓縮,做出符合規則的 zip,再解壓到空資料夾檢查結構。
    • 檢查方式:解壓後只有一個外掛資料夾,裡面沒有 __pycache__、.git、ui_*.py、resources_rc.py。
  3. 讀一支官方外掛庫上已核准外掛的 metadata(例如 06 讀一支真實外掛 的範例),比對自己的寫法。
    • 檢查方式:能說出對方的 changelog、tags、category 寫法與自己的差別。