WordPress 作為全球最流行的內容管理系統，其強大的可擴充套件性主要歸功於外掛。透過開發外掛，你可以為網站新增任何自定義功能，而無需修改核心程式碼。本指南將引導你完成構建第一個功能外掛的全過程，涵蓋從環境準備、程式碼編寫到釋出測試的每一個關鍵步驟。
准备工作与环境搭建
在編寫第一行程式碼之前，你需要一個合適的開發環境。這不僅能提高效率，還能避免在真實網站上除錯可能帶來的風險。
搭建本地开发环境
推薦使用本地伺服器軟體包，如 XAMPP、MAMP 或 Laragon。它們能一鍵安裝 Apache、MySQL 和 PHP，完美模擬線上環境。確保你的 PHP 版本與目標 WordPress 版本相容，通常 WordPress 官網會提供最新的版本要求。
推荐阅读 《WordPress 插件开发完全指南：从零开始打造你的第一个功能插件》。
安裝 WordPress 與程式碼編輯器
在本地伺服器中安裝一個全新的 WordPress 站點，用於外掛開發與測試。同時，選擇一個功能強大的程式碼編輯器，如 Visual Studio Code 或 PhpStorm。這些編輯器對 PHP 語法高亮、程式碼提示和除錯支援良好，能顯著提升編碼體驗。
建立你的第一個外掛檔案
一個最基本的 WordPress 外掛可以只由一個檔案構成。我們將從一個簡單的“Hello World”外掛開始，瞭解外掛的結構。
外掛主檔案的結構
首先，在 WordPress 的 wp-content/plugins 目錄下，建立一個新的資料夾，例如 my-first-plugin。在該資料夾內，建立主外掛檔案，通常以外掛名命名，如 my-first-plugin.php。
每個外掛必須在檔案頭部包含特定的外掛資訊註釋，這是 WordPress 識別外掛的關鍵。以下是一個最基礎的示例：
<?php
/**
* Plugin Name: 我的第一个插件
* Plugin URI: https://example.com/my-first-plugin
* Description: 这是一个用于学习的简单功能插件。
* Version: 1.0.0
* Author: 你的名字
* License: GPL v2 or later
* Text Domain: my-first-plugin
*/儲存檔案後，進入 WordPress 後臺的“外掛”頁面，你就能看到這個外掛並可以啟用它。雖然它現在沒有任何功能，但你已經成功建立了一個合規的外掛框架。
推荐阅读 手把手教你从零开始掌握 WordPress 插件开发。
為外掛新增基本功能
啟用外掛後，讓我們為其新增一個簡單功能：在網站頁尾新增一行自定義文字。我們將使用 WordPress 的 wp_footer 鉤子。
在外掛資訊註釋下方，新增以下程式碼：
// 在网站页脚输出自定义文本
function myfp_add_footer_text() {
echo '<p style="text-align: center;">感谢使用我的第一个插件！</p>';
}
add_action( 'wp_footer', 'myfp_add_footer_text' );儲存檔案並重新整理網站前端，你會在頁面底部看到這行居中的文字。這個例子演示瞭如何使用 add_action() 函式將你的自定義函式“掛載”到 WordPress 的核心執行點上。
實現一個實用的管理功能
一個完整的外掛通常需要在 WordPress 管理後臺提供配置介面。接下來，我們將為外掛新增一個簡單的設定頁面，允許管理員自定義在頁尾顯示的文字。
建立管理選單頁面
我們需要在後臺“設定”選單下新增一個子選單頁。這需要用到 add_options_page() 函数。
首先，建立一個函式來渲染設定頁面的 HTML 內容，並將其掛載到 admin_menu 鉤子上。
推荐阅读 從零開始：為何要選擇 WordPress 外掛開發。
// 添加插件设置页面到后台菜单
function myfp_add_admin_menu() {
add_options_page(
'我的插件设置', // 页面标题
'我的插件', // 菜单标题
'manage_options', // 权限（管理员）
'my-first-plugin', // 菜单slug
'myfp_settings_page' // 用于输出页面内容的回调函数
);
}
add_action( 'admin_menu', 'myfp_add_admin_menu' );
// 设置页面的HTML内容
function myfp_settings_page() {
?>
<div class="wrap">
<h1>我的第一个插件设置</h1>
<form method="post" action="/zh-tw/options.php/" data-trp-original-action="options.php">
<?php
settings_fields( 'myfp_settings_group' ); // 设置字段组
do_settings_sections( 'my-first-plugin' ); // 设置区域
submit_button(); // 提交按钮
?>
<input type="hidden" name="trp-form-language" value="zh-tw"/></form>
</div>
<?php
}註冊設定、欄位與資料儲存
僅有頁面還不夠，我們需要使用 WordPress 設定 API 來安全地註冊、驗證和儲存選項。這涉及三個核心函式：register_setting(), add_settings_section() 以及 add_settings_field()。
// 初始化插件设置
function myfp_settings_init() {
// 注册一个新的设置项到数据库的 `wp_options` 表
register_setting( 'myfp_settings_group', 'myfp_footer_text' );
// 在设置页面添加一个区域
add_settings_section(
'myfp_section',
'页脚文字设置',
null, // 区域描述回调函数，这里不需要
'my-first-plugin'
);
// 在刚添加的区域里创建一个字段
add_settings_field(
'myfp_field_footer',
'显示的文本',
'myfp_field_footer_cb', // 用于输出字段HTML的回调函数
'my-first-plugin',
'myfp_section'
);
}
add_action( 'admin_init', 'myfp_settings_init' );
// 渲染文本输入字段的回调函数
function myfp_field_footer_cb() {
$text = get_option( 'myfp_footer_text', '感谢使用我的第一个插件！' ); // 获取已保存的值
echo '<input type="text" name="myfp_footer_text" value="' . esc_attr( $text ) . '" class="regular-text">';
echo '<p class="description">这里输入的文字将显示在网站页脚。</p>';
}更新功能以使用儲存的設定
最後，修改我們之前寫的 myfp_add_footer_text 函式，使其從資料庫讀取管理員設定的值。
function myfp_add_footer_text() {
$footer_text = get_option( 'myfp_footer_text', '感谢使用我的第一个插件！' );
if ( ! empty( $footer_text ) ) {
echo '<p style="text-align: center;">' . esc_html( $footer_text ) . '</p>';
}
}
add_action( 'wp_footer', 'myfp_add_footer_text' );現在，進入 WordPress 後臺的“設定”->“我的外掛”，你可以修改頁尾文字並儲存。重新整理網站前端，即可看到自定義內容生效。
外掛安全、最佳化與釋出準備
一個合格的外掛必須考慮安全性、效能和國際化的最佳實踐。
實現資料驗證與轉義
永遠不要信任使用者輸入或直接從資料庫輸出的資料。在上面的例子中，我們使用了 esc_attr() 在輸入欄位中轉義屬性，使用 esc_html() 在前端轉義輸出。對於更復雜的場景，應使用 sanitize_text_field() 來清理輸入，使用 wp_kses_post() 來允許安全的 HTML 輸出。
新增國際化支援
為了讓外掛能被全球使用者使用，需要為所有面向用戶的字串做好翻譯準備。這需要使用 __() 以及 _e() 等函式，並宣告文字域。
更新外掛頭部的註釋，確保 Text Domain 與後續呼叫一致。然後修改程式碼中的字串，例如：
// 在设置字段描述中使用国际化函数
echo '<p class="description">' . esc_html__( '这里输入的文字将显示在网站页脚。', 'my-first-plugin' ) . '</p>';
// 在输出函数中使用
$default_text = __( '感谢使用我的第一个插件！', 'my-first-plugin' );
$footer_text = get_option( 'myfp_footer_text', $default_text );之後，你可以使用 Poedit 等工具建立 .pot 模板檔案，供翻譯者建立 .po 以及 .mo 翻譯檔案。
進行最終測試與打包
在釋出前，需要在不同環境（如不同 PHP 版本、不同 WordPress 版本）下測試外掛的功能。確保啟用、停用、設定儲存、資料刪除等操作不會引發錯誤或留下冗餘資料。你可以編寫一個解除安裝清理函式，透過 register_uninstall_hook() 在使用者刪除外掛時清理資料庫選項。
最後，將你的外掛資料夾壓縮為 .zip 檔案。這個壓縮包可以直接透過 WordPress 後臺的“上傳外掛”功能安裝，也符合提交到 WordPress 官方外掛目錄的格式要求。
总结
透過本指南，你完成了從零開始構建一個功能完整的 WordPress 外掛的全過程。你學會了如何建立外掛基礎檔案、使用動作鉤子新增功能、利用 WordPress 設定 API 構建後臺管理介面，並瞭解了安全、國際化和打包等關鍵知識。這個簡單的頁尾文字外掛雖然基礎，但它所蘊含的外掛結構、鉤子機制和設定 API 是開發任何複雜外掛的基石。接下來，你可以嘗試探索短程式碼（Shortcode）、自定義文章型別、REST API 端點等更高階的功能，逐步提升你的外掛開發技能。
常见问题解答（FAQ）
開發 WordPress 外掛必須掌握 PHP 嗎？
是的，PHP 是 WordPress 及其外掛開發的核心程式語言。你需要掌握 PHP 的基礎語法、函式、陣列和麵向物件程式設計概念。同時，對 HTML、CSS 和基礎的 JavaScript 也有助於開發包含使用者介面的外掛。
外掛的主檔名可以任意取嗎？
可以，但必須與外掛資料夾內的主 PHP 檔名保持一致。通常，為了清晰起見，主檔案會與外掛資料夾同名或命名為 index.php。最重要的是，檔案頭部必須包含正確的外掛資訊註釋塊，WordPress 正是透過解析這個註釋塊來識別外掛的。
為什麼我的外掛設定儲存後不生效？
請按以下步驟排查：首先，確保你的設定欄位已透過 register_setting() 正確註冊，且 settings_fields() 函式呼叫中的設定組名稱與之匹配。其次，檢查表單的 action 屬性是否指向 options.php。最後，在前端輸出時，確認你使用的是 get_option() 函式，並且傳入的選項名稱與註冊時完全一致。
如何讓我的外掛在停用時清理資料？
您可以使用 register_uninstall_hook() 函式來註冊一個解除安裝鉤子。在這個鉤子的回撥函式中，你可以使用 delete_option() 函式來刪除外掛建立的所有資料庫選項。請注意，此操作不可逆，僅應在使用者明確選擇“刪除”外掛時執行，而不是“停用”時。
可以將免費外掛提交到 WordPress 官方目錄嗎？
是的，WordPress 官方鼓勵開發者將符合標準的免費外掛提交到其外掛目錄。這需要你擁有一個 WordPress.org 賬號，並仔細閱讀其外掛提交指南。你的程式碼需要遵循一定的編碼標準，並且不能包含惡意程式碼或違反許可證要求。成功提交後，使用者將可以直接從 WordPress 後臺搜尋並安裝你的外掛。
下一步，该怎么做呢？
延伸阅读与实用知识
下方列出的内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，然后逐步扩展到相关主题，这样效果通常会更好。