[WordPress] WordPress.org 外掛上架完全攻略 – 從提交到維護的實戰指南

本篇文章更新時間：2026/03/03
如有資訊過時或語誤之處，歡迎使用 Contact 功能通知或向一介資男的 LINE 社群反應。
如果本站內容對你有幫助，歡迎贊助支持 。

本系列文參考自 WordPress.org 官方外掛開發文件 - WordPress.org 的繁體中文版本，並加入作者實務開發經驗補充。

WordPress 外掛上架到 WordPress.org 官方目錄，是每位外掛開發者的重要里程碑。當你的外掛通過審核、出現在全球數百萬使用者都能搜尋到的目錄中，不僅代表程式碼品質獲得認可，更開啟了與全球社群互動的大門。本篇將完整介紹從準備到上架、從審核到維護的實戰攻略，幫助你順利完成外掛上架的最後一哩路。

上架前的準備

在提交外掛之前，請確認已完成以下清單中的每一項。準備得越充分，審核通過的機率就越高，等待時間也會越短。

基本要求清單

• WordPress.org 帳號：前往 WordPress.org 註冊帳號。這個帳號將會是你的外掛作者身份，也會用於 SVN 提交，請謹慎選擇使用者名稱。
• 閱讀外掛指南：詳細閱讀 Detailed Plugin Guidelines，這是審核的標準依據。每一條規範都可能是退件的原因。
• GPL 相容授權：你的外掛必須使用 GPL v2 或與 GPL 相容的授權條款。所有程式碼、圖片、CSS 和 JavaScript 都必須符合此要求。
• readme.txt 檔案：必須包含符合 WordPress 標準格式的 readme.txt（下一節會詳細說明）。
• 安全性驗證：確保所有使用者輸入都經過適當的 Sanitize、Validate 與 Escape 處理（參考：[WordPress] 外掛開發的資安驗證基礎）。
• 國際化支援：使用 __()、_e() 等函數處理所有面向使用者的字串（參考：[WordPress] 外掛國際化（i18n）教學 - 讓外掛支援多國語言）。
• 使用 WordPress 原生 API：使用 wp_remote_get()、wp_remote_post() 取代 cURL；使用 $wpdb 取代直接的 MySQL 操作；使用 WordPress 內建的排隊機制載入 CSS 和 JavaScript。
• 外掛 Header 資訊：主檔案中的 Plugin Header 必須完整且正確，包含 Plugin Name、Description、Version、Author、License 等欄位。
• 測試：在不同版本的 WordPress（至少包含最新穩定版）和 PHP 版本上測試過你的外掛。

資源準備

• 外掛 Banner 圖片：建議準備 772x250（標準）和 1544x500（高解析度）兩種尺寸，格式為 PNG 或 JPG。
• 外掛圖示：建議準備 128x128（標準）和 256x256（高解析度）兩種尺寸，或者提供一張 SVG 圖示。
• 螢幕截圖：準備外掛功能的截圖，用於展示外掛的主要畫面與操作流程。

readme.txt 撰寫格式

readme.txt 是你的外掛在 WordPress.org 目錄上的門面。使用者在安裝前會先看到這個檔案呈現的內容，因此它的品質直接影響下載量。以下是標準格式的範本：

=== My Plugin Name ===
Contributors: your-username
Donate link: https://example.com/donate
Tags: tag1, tag2, tag3
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Here is a short description of the plugin. This is displayed in search results and should be no more than 150 characters.

== Description ==

This is the long description. You can use markdown-like formatting here.

**Features:**

* Feature one
* Feature two
* Feature three

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/my-plugin-name` directory, or install through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress.
3. Use the Settings->My Plugin screen to configure the plugin.

== Frequently Asked Questions ==

= How do I configure the plugin? =

Go to Settings > My Plugin in your WordPress admin panel.

= Does this plugin work with WooCommerce? =

Yes, it is fully compatible with WooCommerce.

== Screenshots ==

1. This is the first screenshot description.
2. This is the second screenshot description.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release of the plugin.

各區塊說明

• Header 區塊：Contributors 必須填寫 WordPress.org 的使用者名稱（不是顯示名稱）；Tags 最多 5 個標籤；Stable tag 必須與你實際發布的版本號一致。
• Short Description：Header 區塊下方的那行文字，限制 150 個字元以內，會顯示在搜尋結果中，要簡潔有力。
• Description：詳細介紹外掛功能，支援類似 Markdown 的語法。這是說服使用者安裝的主要區域。
• Installation：安裝步驟，通常包含手動上傳和後台搜尋安裝兩種方式。
• FAQ：常見問題，使用 = 問題 = 的格式。可以預先回答使用者最可能問的問題。
• Screenshots：截圖說明，編號對應 assets 目錄中的 screenshot-1.png、screenshot-2.png 等檔案。
• Changelog：版本更新紀錄，按版本號從新到舊排列。這是使用者判斷外掛是否有在維護的重要依據。
• Upgrade Notice：升級通知，會顯示在 WordPress 後台的更新提示中，告知使用者此次更新的重點。

你可以使用 WordPress 官方提供的 readme.txt 驗證工具 來檢查格式是否正確。

提交審核流程

當你準備好所有必要的檔案後，就可以開始提交流程了。

Step 1：提交外掛

前往 Plugin Submission 頁面，上傳你的外掛 ZIP 檔案。ZIP 檔案中必須包含你的外掛資料夾，裡面至少有主程式檔案和 readme.txt。

Step 2：等待審核

提交後，WordPress.org 的外掛審核團隊會人工審查你的程式碼。審核時間通常為 1 至 7 個工作天，但在繁忙時期可能會更長。在等待期間：

• 不要重複提交同一個外掛。
• 定期檢查你的電子郵件，包含垃圾郵件資料夾。
• 審核團隊可能會回信指出需要修改的問題，請盡快回覆並修正。

Step 3：審核結果

審核通過後，你會收到一封包含 SVN 存取資訊的電子郵件。信中會提供：

• 你的外掛 SVN Repository URL（例如：https://plugins.svn.wordpress.org/your-plugin-slug/）
• 你的外掛在 WordPress.org 上的頁面 URL
• SVN 使用說明

如果審核未通過，信中會說明退件原因。修正後回覆該郵件即可重新進入審核流程，不需要重新提交。

Step 4：上傳程式碼

收到核准通知後，你需要在 14 天內透過 SVN 上傳你的程式碼。如果超過期限未上傳，你的外掛 Slug 可能會被回收。

SVN 版本控制

WordPress.org 使用 SVN（Subversion）來管理外掛程式碼。即使你平時使用 Git，上傳到 WordPress.org 時仍需透過 SVN。

目錄結構

每個外掛的 SVN Repository 有以下標準結構：

my-plugin/
├── trunk/          # 開發中的最新版本
│   ├── my-plugin.php
│   ├── readme.txt
│   └── ...
├── tags/           # 已發佈的版本標籤
│   ├── 1.0.0/
│   │   ├── my-plugin.php
│   │   ├── readme.txt
│   │   └── ...
│   └── 1.1.0/
│       └── ...
└── assets/         # 外掛頁面的圖片資源
    ├── banner-772x250.png
    ├── banner-1544x500.png
    ├── icon-128x128.png
    ├── icon-256x256.png
    ├── icon.svg
    ├── screenshot-1.png
    └── screenshot-2.png

• trunk/：放置你的外掛開發版本程式碼。每次更新都先提交到 trunk。
• tags/：每次正式發佈版本時，從 trunk 複製一份到 tags/版本號/ 目錄下。readme.txt 中的 Stable tag 必須指向這裡的某個版本號，WordPress.org 會根據這個設定來決定使用者下載哪個版本。
• assets/：放置外掛頁面上顯示的 Banner、Icon 和截圖。這些檔案不會被包含在外掛的下載 ZIP 中。

基本 SVN 操作

以下是常用的 SVN 指令，以外掛 Slug 為 my-plugin 為例：

首次 Checkout

# 將遠端 Repository 下載到本地
svn checkout https://plugins.svn.wordpress.org/my-plugin/ my-plugin-svn
cd my-plugin-svn

上傳程式碼到 trunk

# 將你的外掛檔案複製到 trunk 目錄
cp -r /path/to/your/plugin/* trunk/

# 新增新檔案到版本控制
svn add trunk/* --force

# 檢查狀態
svn status

# 提交變更（會要求輸入 WordPress.org 帳號密碼）
svn commit -m "Initial commit of version 1.0.0"

建立版本標籤（Tag）

# 從 trunk 建立版本標籤
svn copy trunk tags/1.0.0

# 提交標籤
svn commit -m "Tagging version 1.0.0"

更新版本

# 1. 更新 trunk 中的程式碼
# 2. 更新 trunk/readme.txt 中的 Stable tag 為新版本號
# 3. 更新主檔案中的 Version 為新版本號
svn commit -m "Update to version 1.1.0"

# 4. 建立新的版本標籤
svn copy trunk tags/1.1.0
svn commit -m "Tagging version 1.1.0"

上傳 Assets

# 將圖片檔案放到 assets 目錄
cp banner-772x250.png assets/
cp icon-128x128.png assets/

svn add assets/* --force
svn commit -m "Add plugin banner and icon"

刪除不需要的檔案

# 如果需要移除某個檔案
svn delete trunk/old-file.php
svn commit -m "Remove deprecated file"

提示：如果你習慣使用 Git 開發，可以搭配工具如 wp-plugin-deploy 或 GitHub Actions 來自動化 SVN 部署流程，避免每次手動操作 SVN。

常見退件原因與對策

以下整理了外掛審核中最常見的退件原因，以及對應的修正方式。了解這些可以大幅提高你一次通過審核的機率。

1. 使用 cURL 而非 HTTP API

WordPress 外掛不應直接使用 PHP 的 curl_* 函數或 file_get_contents() 發送 HTTP 請求。

// 錯誤做法
$response = file_get_contents( 'https://api.example.com/data' );
$ch = curl_init( 'https://api.example.com/data' );

// 正確做法
$response = wp_remote_get( 'https://api.example.com/data' );
if ( ! is_wp_error( $response ) ) {
    $body = wp_remote_retrieve_body( $response );
}

2. 缺少資料清理與跳脫

所有使用者輸入必須經過 Sanitize，所有輸出必須經過 Escape。這是最常見的退件原因之一。

// 錯誤做法
echo $_POST['user_input'];
$wpdb->query( "SELECT * FROM {$wpdb->posts} WHERE post_title = '{$_GET['title']}'" );

// 正確做法
echo esc_html( sanitize_text_field( wp_unslash( $_POST['user_input'] ) ) );
$wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->posts} WHERE post_title = %s",
        sanitize_text_field( wp_unslash( $_GET['title'] ) )
    )
);

3. 呼叫外部服務未揭露

如果你的外掛會連線到外部伺服器（API、CDN、追蹤服務等），必須在 readme.txt 的 Description 中清楚說明：

• 連線到哪個服務
• 什麼情況下會發送請求
• 傳送了哪些資料
• 該服務的隱私權政策連結

4. 包含混淆程式碼

WordPress.org 禁止包含任何經過混淆（Obfuscated）的程式碼，包括 base64 編碼、加密或壓縮後無法閱讀的程式碼。所有程式碼都必須是人類可閱讀的。壓縮過的 JavaScript 或 CSS（minified）是允許的，但必須同時提供未壓縮的原始碼。

5. GPL 授權不相容

外掛的所有組成部分（包括第三方函式庫、圖片、CSS、JavaScript）都必須與 GPL v2 相容。常見問題包括：

• 引用了使用 MIT 或 Apache 授權的函式庫但未正確標註（這兩者與 GPL 相容，但需標註）
• 使用了非 GPL 相容授權的字型或圖示
• 包含了專有授權（Proprietary License）的程式碼片段

6. 自行修改核心資料表

外掛不應直接修改 WordPress 核心資料表的結構，也不應在非自己建立的資料表中新增欄位。如果需要儲存額外資料，請使用 WordPress 提供的 Meta API（Post Meta、User Meta 等）或建立自己的資料表。

7. 在 WordPress.org 上的行為規範

其他常見問題還包括：

• 外掛名稱中包含 "WordPress" 一詞（不允許使用 "WordPress" 或 "WP" 作為外掛名稱的開頭）
• 外掛 Slug 與已存在的知名品牌或外掛名稱過於相似
• 在後台注入過多的廣告或推廣訊息
• 預設追蹤使用者行為且未取得明確同意

上架後的維護

外掛上架只是開始，持續維護才是建立使用者信任的關鍵。以下是上架後需要注意的事項。

版本更新策略

• 遵循語意化版本號（Semantic Versioning）：主版本號.次版本號.修訂版本號（例如 1.2.3）。修正 Bug 增加修訂號，新增功能增加次版本號，重大不相容變更增加主版本號。
• 每次 WordPress 大版本更新後：測試你的外掛是否相容，並更新 readme.txt 中的 Tested up to 欄位。即使外掛功能沒有變動，更新這個欄位也能讓使用者知道你有在維護。
• 保持更新頻率：過長時間沒有更新（超過兩年）的外掛可能會被 WordPress.org 標記為「已關閉」或在搜尋結果中降權。

使用者支援

• 回覆支援論壇：WordPress.org 會為每個外掛自動建立支援論壇。定期回覆使用者的問題，不僅能幫助使用者，也會影響外掛的搜尋排名。
• 處理問題回報：當使用者回報 Bug 時，盡快確認問題並提供修正時程。即使無法立即修復，回覆一句「已收到，正在處理」也比沉默好得多。
• 善用 Changelog：每次更新都詳細記錄變更內容，讓使用者知道你在做什麼。這也是展現專業度的好方式。

監控與安全

• 定期檢查外掛的安全性，特別是在 WordPress 核心或 PHP 版本更新時。
• 如果你的外掛有安全漏洞被通報，WordPress.org 可能會暫時關閉你的外掛，直到你修復問題。請務必留意來自外掛審核團隊的郵件。
• 考慮加入自動化測試（PHPUnit）與靜態分析工具（PHPStan、PHPCS 搭配 WordPress Coding Standards），在每次提交前自動檢查程式碼品質。

行銷與曝光

• 撰寫清楚的外掛描述，善用 Tags 提高搜尋能見度。
• 準備高品質的 Banner 和 Screenshot，第一印象很重要。
• 鼓勵滿意的使用者留下好評，評分是影響排名的重要因素。
• 在你的網站、部落格或社群媒體上推廣你的外掛。

實務建議

身為有多次上架經驗的開發者，以下分享幾點實務建議：

Slug 的選擇至關重要。外掛的 Slug（網址路徑名稱）一旦核准就無法更改。選擇一個簡短、好記、且能反映外掛功能的 Slug。同時，Slug 也是你的外掛在搜尋結果中被找到的關鍵之一。延伸閱讀：外掛的市場行銷 - Slug 的選擇策略。

安全性是不可妥協的底線。外掛審核團隊對安全性問題零容忍。提交前請務必仔細檢查每一處使用者輸入的處理方式。延伸閱讀：[WordPress] 外掛開發的資安驗證基礎。

國際化是進入全球市場的門票。即使你的外掛目前只有英文版，使用國際化函數包裝字串可以讓全球志工協助翻譯你的外掛。WordPress.org 有完整的翻譯平台（translate.wordpress.org）會自動處理翻譯的分發。延伸閱讀：[WordPress] 外掛國際化（i18n）教學 - 讓外掛支援多國語言。

先從小外掛開始練習。如果你是第一次上架外掛，建議先從一個功能單純的小外掛開始。熟悉整個流程後，再挑戰較複雜的專案。這樣可以減少審核來回修改的時間成本。

善用 GitHub Actions 自動化部署。建立一個從 GitHub 自動部署到 WordPress.org SVN 的工作流程，可以大幅減少手動操作的出錯機率。社群有許多現成的 GitHub Actions 可以使用，例如 10up/action-wordpress-plugin-deploy。

readme.txt 就是你的銷售頁。花時間把 readme.txt 寫好，清楚說明外掛的價值主張、功能特色和使用方式。一份好的 readme.txt 可以顯著提升下載量。

---

本文是「WordPress 外掛開發完整指南」系列的最後一篇（第 15 篇）。

上一篇：[WordPress] 外掛開發之隱私權該注意的設計方法

回到系列總覽：WordPress 外掛開發完整指南