開發前的準備工作
在動手編寫程式碼之前，我們需要確保開發環境正確搭建，並理解 WordPress 外掛的基本結構。一個合適的本地開發環境是高效工作的基礎。
搭建本地开发环境
首先，你需要一個本地伺服器環境來執行 WordPress。推薦使用 XAMPP、MAMP 或 Local by Flywheel 等整合工具。安裝好 WordPress 後，你可以在 wp-content/plugins 目錄下開始你的外掛開發。這個目錄是存放所有外掛的地方，無論是你自己開發的還是從官方目錄安裝的。
理解外掛核心檔案
每個 WordPress 外掛都至少需要一個主檔案，這個檔案是外掛的“身份證”和“啟動器”，通常以外掛的功能命名，例如 my-first-plugin.php。這個主檔案頂部的註釋塊至關重要，它向 WordPress 系統描述了這個外掛的基本資訊。
推荐阅读 WordPress外掛開發從入門到精通：手把手教你打造第一個自定義外掛。
建立你的第一個外掛檔案
現在，讓我們從最基礎的部分開始，建立一個有實際功能的簡單外掛。
編寫外掛頭部註釋
关于 wp-content/plugins 目錄下，建立一個名為 my-first-plugin 的新資料夾。然後，在該資料夾內建立主檔案 my-first-plugin.php。在這個檔案的最頂部，你需要新增符合 WordPress 標準的外掛資訊頭部註釋。
<?php
/**
* Plugin Name: 我的第一个插件
* Plugin URI: https://yourwebsite.com/my-first-plugin
* Description: 这是一个用于学习的简单插件，用于在文章末尾添加自定义文本。
* Version: 1.0.0
* Author: 你的名字
* Author URI: https://yourwebsite.com
* License: GPL v2 or later
* Text Domain: my-first-plugin
*/這段程式碼告訴 WordPress 這是一個外掛，並定義了它在後臺管理介面中顯示的名稱、描述、版本等資訊。儲存檔案後，你登入 WordPress 後臺，進入“外掛”頁面，應該就能看到你的外掛出現在列表裡了。現在你可以啟用它，雖然它還沒有任何功能。
實現一個基本功能：過濾文章內容
啟用外掛後，我們需要讓它做點事情。一個常見的入門功能是修改文章內容。我們將使用 the_content 這個過濾器鉤子，在每篇文章的末尾自動新增一段自定義文字。
在主檔案 my-first-plugin.php 的頭部註釋下方，我們新增功能程式碼：
推荐阅读 怎样制作一个专业的 WordPress 主题：从零到上线的一步步指南。
// 在文章内容末尾添加自定义文本
function myfp_add_custom_text_to_content( $content ) {
// 确保只在主循环的单篇文章页面添加
if ( is_single() && in_the_loop() && is_main_query() ) {
$custom_text = '<p><strong>感谢阅读！本文由“我的第一个插件”提供支持。</strong></p>';
$content .= $custom_text;
}
return $content;
}
// 将我们的函数挂载到 ‘the_content’ 过滤器上
add_filter( 'the_content', 'myfp_add_custom_text_to_content' );這段程式碼定義了一個名為 myfp_add_custom_text_to_content 的函式。它接收文章內容 $content 作為引數，透過條件判斷確保只在網站前臺的單篇文章頁面新增文字，避免在其他頁面（如列表頁）也生效。然後，它將一段自定義的 HTML 段落追加到原文內容後面，並返回修改後的內容。最後，使用 add_filter() 函式將這個自定義函式“掛載”到 WordPress 核心的 the_content 過濾器上。這樣，每當 WordPress 準備輸出文章內容時，都會先執行我們的函式。
儲存檔案後，去網站前臺檢視任意一篇文章，你會發現頁面底部已經出現了我們新增的那段致謝文字。
為外掛新增管理選項
一個功能完善的外掛通常需要一些配置選項，允許使用者在後臺進行設定。我們將為剛才的“自定義文字”功能增加一個設定頁面。
建立外掛管理選單
首先，我們需要在 WordPress 後臺的管理側邊欄中新增一個新的選單項。這需要使用 WordPress 的 add_action() 函式和 admin_menu 鉤子。
// 添加管理菜单
function myfp_add_admin_menu() {
add_options_page(
'我的第一个插件设置', // 页面标题
'我的插件设置', // 菜单标题
'manage_options', // 权限要求
'my-first-plugin', // 菜单 slug
'myfp_options_page_html' // 显示设置页面的回调函数
);
}
add_action( ‘admin_menu’， ‘myfp_add_admin_menu’ );add_options_page() 函式會在“設定”主選單下建立一個子選單項。它需要幾個引數：頁面標題、選單標題、使用者許可權、唯一的選單識別符號（slug），以及一個用於輸出設定頁面 HTML 內容的回撥函式名 myfp_options_page_html。
構建設定頁面與儲存資料
接下來，我們需要定義回撥函式來渲染設定頁面，並處理使用者提交的資料。
推荐阅读 WordPress 插件开发教程：从零到一，构建你的第一个插件。
// 渲染设置页面的HTML
function myfp_options_page_html() {
// 检查用户权限
if ( !current_user_can( 'manage_options' ) ) {
return;
}
?>
<div class="“wrap”">
<h1></h1>
<form action="/zh-tw/“options.php”/" method="“post”" data-trp-original-action="“options.php”">
<?php
// 输出必要的安全字段
settings_fields( ‘myfp_settings’ );
// 输出设置区域
do_settings_sections( ‘my-first-plugin’ );
// 输出提交按钮
submit_button( ‘保存设置’ );
?>
<input type="hidden" name="trp-form-language" value="zh-tw"/></form>
</div>
<?php
}
// 注册设置、区域和字段
function myfp_settings_init() {
// 注册一个名为 ‘myfp_options’ 的选项数组
register_setting( ‘myfp_settings’， ‘myfp_options’ );
// 添加一个设置区域
add_settings_section(
‘myfp_section’，
‘自定义文本设置’，
null， // 区域描述的回调，这里不需要
‘my-first-plugin’
);
// 向该区域添加一个文本字段
add_settings_field(
‘myfp_field_custom_text’，
‘要在文章末尾添加的文本’，
‘myfp_field_custom_text_html’，
‘my-first-plugin’，
‘myfp_section’，
[ ‘label_for’ => ‘myfp_field_custom_text’ ]
);
}
add_action( ‘admin_init’， ‘myfp_settings_init’ );
// 渲染文本框的HTML
function myfp_field_custom_text_html() {
// 从数据库获取已保存的值
$options = get_option( ‘myfp_options’ );
$value = $options[‘myfp_field_custom_text’] ?? ‘’； // 使用空合并运算符，如果不存在则赋空值
?>
<input type="“text”"
id="“myfp_field_custom_text”"
name="“myfp_options[myfp_field_custom_text]”"
value="“NO NUMERIC NOISE KEY" 1000”
class="“regular-text”">
<?php
}這段程式碼透過 register_setting、add_settings_section 以及 add_settings_field 等一系列函式，利用 WordPress 的 Settings API 規範地建立了一個包含一個文字輸入框的設定頁面。使用者輸入的內容會安全地儲存到 wp_options 資料表的 myfp_options 記錄中。
最後，我們需要修改之前過濾文章內容的函式，讓它使用從資料庫獲取的文字，而不是硬編碼的文字。
function myfp_add_custom_text_to_content( $content ) {
if ( is_single() && in_the_loop() && is_main_query() ) {
$options = get_option( ‘myfp_options’ );
$custom_text = $options[‘myfp_field_custom_text’] ?? ‘’；
if ( ! empty( $custom_text ) ) {
$content .= ‘<p><strong>’ . esc_html( $custom_text ) . ‘</strong></p>’；
}
}
return $content;
}現在，使用者可以在“設定”->“我的外掛設定”頁面中輸入任何文字，儲存後，該文字就會顯示在網站所有文章的末尾。
外掛開發的進階實踐與釋出準備
當基礎功能完成後，我們需要考慮外掛的健壯性、可維護性以及如何分享給他人使用。
新增安全性與國際化支援
安全性是外掛開發的重中之重。在上面的例子中，我們已經使用了 esc_html() 以及 esc_attr() 等函式來對輸出進行轉義，防止 XSS 攻擊。在處理使用者輸入、執行資料庫查詢或引入外部檔案時，必須始終使用 WordPress 提供的安全函式，如 wpdb->prepare()、sanitize_text_field() 以及 check_admin_referer() 等等。
此外，為了讓外掛能被全世界的使用者使用，國際化（i18n）是必要的。我們需要將外掛中所有面向用戶的字串用 WordPress 的翻譯函式包裹起來。這需要修改我們之前的程式碼：
1. 在外掛頭部註釋中已指定 Text Domain: my-first-plugin。
2. 載入文字域。通常在主檔案底部新增：add_action( ‘plugins_loaded’， function() { load_plugin_textdomain( ‘my-first-plugin’， false， dirname( plugin_basename( FILE ) ) . ‘/languages/’ ); } );。
3. 包裹字串。例如，將設定區域的標題改為 ( ‘自定义文本设置’， ‘my-first-plugin’ )，將選單標題改為 ( ‘我的插件设置’， ‘my-first-plugin’ )。這樣，翻譯人員就可以透過 .po/.mo 檔案為這些字串提供其他語言版本。
準備外掛釋出到官方目錄
如果你希望將外掛提交到 WordPress.org 官方外掛目錄，你需要遵循一系列規範：
1. 程式碼規範：遵守 WordPress 編碼標準。
2. 檔案結構：除主檔案外，通常還需要 README.txt（描述外掛，用於目錄頁面）、uninstall.php（處理外掛解除安裝時的清理工作）等。
3. SVN 倉庫：官方目錄使用 Subversion (SVN) 進行版本管理，你需要將你的外掛程式碼提交到指定的 SVN 倉庫。
4. 元資料：README.txt 需要按照特定格式編寫，包含外掛名稱、描述、安裝方法、常見問題、更新日誌等。
总结
透過本教程，你完成了一個完整 WordPress 外掛的開發週期：從建立第一個檔案、編寫頭部註釋、利用動作鉤子和過濾器鉤子實現核心功能，到為外掛新增可配置的設定頁面，最後瞭解了安全、國際化及釋出準備等進階知識。這個在文章末尾新增自定義文字的外掛雖然簡單，但它涵蓋了外掛開發中最核心的概念和流程。掌握這些基礎知識後，你可以透過探索 WordPress 龐大的鉤子（Hooks）系統、短碼（Shortcode）、自定義文章型別（CPT）和 REST API 等，來構建功能越來越強大和複雜的外掛。記住，實踐是最好的學習方式，嘗試修改程式碼、新增新功能，是鞏固知識的關鍵。
常见问题解答（FAQ）
外掛主檔案必須叫什麼名字？
外掛主檔案的命名沒有強制要求，但必須以 .php 結尾。通常，為了清晰和唯一性，我們使用與外掛資料夾名相同或能描述外掛功能的名稱，例如 my-awesome-plugin.php。WordPress 是透過讀取該檔案頭部的特定註釋塊來識別外掛的。
為什麼我的外掛在後臺菜單中不顯示？
這通常是由幾個原因造成的。首先，請檢查外掛是否已成功啟用。其次，檢查 add_menu_page() 或類似函式中的使用者許可權引數（capability），確保當前登入的使用者擁有相應許可權（如 manage_options）。最後，檢查你的函式是否正確透過 add_action(‘admin_menu’， …) 掛載。任何 PHP 語法錯誤都可能導致整個外掛初始化失敗。
如何除錯外掛中的 PHP 錯誤？
在開發階段，建議開啟 WordPress 的除錯模式。開啟網站根目錄下的 wp-config.php 檔案，確保以下設定已啟用：
define( ‘WP_DEBUG’， true );
define( ‘WP_DEBUG_LOG’， true ); // 将错误记录到 /wp-content/debug.log
define( ‘WP_DEBUG_DISPLAY’， false ); // 不建议在页面上显示，以免破坏布局
這樣，錯誤資訊會被記錄到日誌檔案中，方便查詢問題。釋出外掛前，請務必關閉除錯模式。
外掛選項資料儲存在哪裡？
外掛使用 add_option() 或者 update_option() 函式儲存的資料，預設儲存在 WordPress 資料庫的 wp_options 表中（表字首可能不同）。使用 get_option() 函式可以讀取這些資料。對於更復雜的資料結構，有時也會建立自定義資料庫表，但這需要更謹慎的處理。
如何讓我的外掛支援多語言（國際化）？
你需要使用 WordPress 的翻譯函式來包裹所有面向用戶的字串。最常用的是 __(‘字符串’， ‘text-domain’) 以及 _e(‘字符串’， ‘text-domain’)。然後，使用 Poedit 這類工具提取這些字串，生成 .pot 模板檔案，並建立對應語言（如 zh_CN.po 以及 .mo）的翻譯檔案。最後，將語言檔案放在外掛目錄的 /languages/ 資料夾下，並在外掛初始化時使用 load_plugin_textdomain() 函式載入它們。
下一步，该怎么做呢？
延伸阅读与实用知识
下方列出的内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，然后逐步扩展到相关主题，这样效果通常会更好。