准备工作与环境搭建
在開始編寫程式碼之前，你需要一個合適的開發環境。這包括一個本地的 WordPress 安裝、一個程式碼編輯器以及一些基本的 PHP 知識。本地開發環境推薦使用 XAMPP、MAMP 或 Local by Flywheel 等工具，它們可以快速在本地計算機上搭建包含 PHP 和 MySQL 的伺服器環境。
建立外掛的基礎目錄與檔案
每個 WordPress 外掛都必須擁有一個主檔案，這個檔案是外掛的入口點。首先，你需要在 WordPress 的 wp-content/plugins 在目录下创建一个新文件夹，例如 my-first-plugin。然後，在該資料夾內建立一個主 PHP 檔案，通常與資料夾同名，即 my-first-plugin.php。
這個主檔案的開頭必須包含一個標準的外掛資訊頭部註釋，WordPress 透過讀取這些資訊來在後臺管理介面中識別和展示你的外掛。
推荐阅读 零基础入门：手把手教你掌握WordPress插件开发的核心技巧。
<?php
/**
* Plugin Name: 我的第一个插件
* Plugin URI: https://example.com/my-first-plugin
* Description: 这是一个用于学习 WordPress 插件开发的示例插件。
* Version: 1.0.0
* Author: 你的名字
* Author URI: https://example.com
* License: GPL v2 or later
* Text Domain: my-first-plugin
* Domain Path: /languages
*/理解 WordPress 外掛開發的基本結構
一個功能完整的外掛通常不止一個檔案。除了主檔案，你還可能擁有 JavaScript、CSS、圖片等資原始檔，以及用於國際化的語言檔案。合理的目錄結構有助於程式碼的組織和維護。
一個推薦的結構如下：
- my-first-plugin/ (外掛根目錄)
- my-first-plugin.php (主檔案)
- includes/ (存放核心功能類或函式檔案)
- admin/ (存放後臺管理介面相關程式碼)
- public/ (存放前端展示相關程式碼)
- assets/ (存放 CSS, JavaScript, 圖片等資源)
- languages/ (存放國際化翻譯檔案)
核心 PHP 程式碼編寫
外掛的所有功能邏輯都透過 PHP 程式碼實現。WordPress 提供了大量的动作钩子以及过滤器钩子，這是外掛與 WordPress 核心進行互動的基石。
實現一個簡單的短程式碼功能
短程式碼是讓使用者方便地在文章或頁面中嵌入外掛功能的強大工具。我們來實現一個簡單的短程式碼，它在頁面上顯示一條問候語。
在你的主檔案 my-first-plugin.php 的頭部註釋下方，新增以下函式和鉤子：
推荐阅读 深入解析 WordPress 外掛開發：從零到一建構你的第一個功能擴充套件。
// 注册短代码
function mfp_greeting_shortcode( $atts ) {
// 使用 shortcode_atts 设置默认参数并合并用户传入的参数
$atts = shortcode_atts( array(
'name' => '访客',
), $atts, 'mfp_greeting' );
// 返回要显示的内容
return '<p>你好，' . esc_html( $atts['name'] ) . '！欢迎使用我的第一个插件。</p>';
}
add_shortcode( 'mfp_greeting', 'mfp_greeting_shortcode' );現在，使用者可以在文章編輯器中輸入 [mfp_greeting name=“小明”]，前端就會顯示“你好，小明！歡迎使用我的第一個外掛。”
新增一個設定選項到後臺
為了讓外掛功能可配置，我們通常需要新增一個設定頁面。這裡演示如何向“設定”選單新增一個子選單頁。
首先，我們使用 add_action 鉤子在管理員初始化時註冊設定。
// 初始化插件设置
function mfp_settings_init() {
// 注册一个新的设置 section
add_settings_section(
'mfp_settings_section', // section ID
'我的插件设置', // 标题
'mfp_settings_section_callback', // 回调函数，用于输出 section 描述
'general' // 显示在哪个设置页，这里是“常规”设置页
);
// 在 section 内注册一个字段
add_settings_field(
'mfp_default_greeting', // 字段 ID
'默认问候人名', // 字段标题
'mfp_default_greeting_callback', // 渲染字段输入框的回调函数
'general', // 设置页面
'mfp_settings_section' // 所属 section
);
// 在 WordPress 的 `option` 表中注册这个设置
register_setting( 'general', 'mfp_default_greeting' );
}
add_action( 'admin_init', 'mfp_settings_init' );然後，定義上面用到的兩個回撥函式來渲染介面：
// Section 描述的回调函数
function mfp_settings_section_callback() {
echo '<p>在这里配置我的第一个插件的相关选项。</p>';
}
// 字段输入框的回调函数
function mfp_default_greeting_callback() {
// 从数据库获取已保存的值，如果没有则使用默认值
$option = get_option( 'mfp_default_greeting', 'WordPress 用户' );
// 输出一个输入框
echo '<input type="text" name="mfp_default_greeting" value="' . esc_attr( $option ) . '" />';
}現在，你可以在 WordPress 後臺的“設定 -> 常規”頁面底部看到這個設定選項。
前端資源管理與 Ajax 互動
現代外掛通常需要自己的樣式和互動邏輯。WordPress 提供了標準的方式來安全地註冊和載入 CSS 與 JavaScript 檔案。
推荐阅读 從零開始：為何要選擇 WordPress 外掛開發。
安全地載入 CSS 和 JavaScript
永遠不要直接在你的 PHP 檔案中透過 <link> 或者 <script> 標籤硬編碼資源路徑。應該使用 wp_enqueue_style 以及 wp_enqueue_script 函数。
// 注册并加载前端资源
function mfp_enqueue_public_assets() {
// 加载一个 CSS 文件
wp_enqueue_style(
'mfp-public-style', // 样式表句柄
plugin_dir_url( __FILE__ ) . 'assets/css/public-style.css', // 样式表 URL
array(), // 依赖项
'1.0.0' // 版本号，可用于清除缓存
);
// 加载一个 JavaScript 文件
wp_enqueue_script(
'mfp-public-script', // 脚本句柄
plugin_dir_url( __FILE__ ) . 'assets/js/public-script.js', // 脚本 URL
array( 'jquery' ), // 依赖项，这里依赖 jQuery
'1.0.0',
true // 是否在页面底部加载
);
// 重要：将 PHP 变量安全地传递到 JavaScript
wp_localize_script(
'mfp-public-script',
'mfp_ajax_object', // 在 JS 中访问的对象名
array(
'ajax_url' => admin_url( 'admin-ajax.php' ),
'nonce' => wp_create_nonce( 'mfp_ajax_nonce' ),
'default_name' => get_option( 'mfp_default_greeting', 'WordPress 用户' )
)
);
}
// 在前端页面加载资源
add_action( 'wp_enqueue_scripts', 'mfp_enqueue_public_assets' );
// 在后台管理页面加载资源（如果需要）
// add_action( 'admin_enqueue_scripts', 'mfp_enqueue_admin_assets' );實現一個簡單的 Ajax 請求
Ajax 允許在不重新整理頁面的情況下與伺服器互動。WordPress 有內建的 Ajax 處理器。
首先，在前端 JavaScript 檔案 public-script.js 中傳送請求：
jQuery(document).ready(function($) {
$('#my-button').on('click', function(e) {
e.preventDefault();
$.post(
mfp_ajax_object.ajax_url, // WordPress 提供的 Ajax URL
{
action: 'mfp_get_server_time', // 触发的 PHP 钩子标识
nonce: mfp_ajax_object.nonce, // 安全随机数
},
function(response) {
if (response.success) {
$('#result-container').html('服务器时间：' + response.data);
} else {
alert('请求失败：' + response.data);
}
}
);
});
});然後，在 PHP 端處理這個請求。需要為登入使用者和未登入使用者分別（或同時）註冊處理函式。
// 处理 Ajax 请求的函数
function mfp_ajax_get_server_time() {
// 验证 nonce，防止 CSRF 攻击
check_ajax_referer( 'mfp_ajax_nonce', 'nonce' );
// 处理逻辑
$server_time = current_time( 'mysql' );
// 返回成功响应（JSON 格式）
wp_send_json_success( $server_time );
}
// 为登录用户注册处理函数
add_action( 'wp_ajax_mfp_get_server_time', 'mfp_ajax_get_server_time' );
// 为未登录用户注册处理函数（如果功能允许）
add_action( 'wp_ajax_nopriv_mfp_get_server_time', 'mfp_ajax_get_server_time' );外掛國際化與釋出準備
為了讓你的外掛能被全世界的 WordPress 使用者使用，國際化（i18n）是必不可少的步驟。同時，在釋出前進行充分的測試和最佳化也至關重要。
使用 gettext 函式實現文字翻譯
WordPress 使用 GNU gettext 框架進行翻譯。你需要將所有面向用戶的字串用特定的函式包裹起來。
修改之前的短程式碼函式，使其支援翻譯：
function mfp_greeting_shortcode_i18n( $atts ) {
$atts = shortcode_atts( array(
'name' => __( '访客', 'my-first-plugin' ), // 默认值也可翻译
), $atts, 'mfp_greeting' );
// 使用 sprintf 和 __ 函数组合翻译字符串
return '<p>' . sprintf( __( '你好，%s！欢迎使用我的第一个插件。', 'my-first-plugin' ), esc_html( $atts['name'] ) ) . '</p>';
}
add_shortcode( 'mfp_greeting', 'mfp_greeting_shortcode_i18n' );你需要使用 Poedit 等工具，掃描外掛中所有類似 __(‘文本’, ‘my-first-plugin’) 的字串，生成 .pot 模板檔案，然後為每種語言（如中文）建立對應的 .po 和编译后的 .mo 檔案，並放入 /languages 目录。
進行最終測試與程式碼清理
在釋出外掛之前，請務必進行以下檢查：
1. 功能測試：在全新的 WordPress 安裝上啟用外掛，測試所有功能（短程式碼、設定、Ajax等）是否按預期工作。
2. 程式碼審查：檢查所有使用者輸入是否都使用了 esc_html, esc_attr, wp_kses_post 等函式進行安全轉義。所有資料庫查詢是否使用 $wpdb 類進行準備語句以防止 SQL 注入。
3. 效能檢查：確保指令碼和樣式只在需要的頁面載入（可以使用條件標籤如 is_admin(), is_single() 進行判斷）。避免在每次頁面載入時執行不必要的資料庫查詢。
4. 檔案清理：刪除開發過程中使用的除錯程式碼、多餘的註釋和未使用的檔案。
5. README 檔案：建立一個詳細的 readme.txt 檔案，其格式必須符合 WordPress.org 的要求，包含描述、安裝步驟、常見問題等。這是將外掛提交到官方目錄的必需檔案。
总结
透過本指南，你完成了從一個空白檔案到構建一個具備短程式碼、後臺設定、前端資源載入、Ajax互動及國際化支援的完整 WordPress 外掛的旅程。核心步驟包括：搭建環境並建立帶有標準頭部的主檔案；利用動作鉤子和過濾器鉤子注入功能；安全地管理資原始檔；實現前後端非同步通訊；以及為全球釋出做好翻譯和測試準備。記住，安全（轉義、驗證、nonce）、效能（按需載入）和標準（遵循 WordPress 編碼規範）是開發高質量外掛的三大支柱。持續學習和實踐更高階的 API，如自定義文章型別、REST API 和 Blocks 編輯器開發，將使你的外掛更加強大。
常见问题解答（FAQ）
外掛開發必須使用面向物件程式設計嗎
不一定。對於簡單外掛，使用程序式程式設計（一組函式）是完全可行的，而且更簡單直接。然而，對於中大型複雜外掛，採用面向物件程式設計（OOP）和類結構可以更好地組織程式碼，實現封裝和複用，減少命名衝突，是更推薦的做法。
如何除錯 WordPress 外掛中的問題
首先，確保在 wp-config.php 檔案中開啟 WP_DEBUG 以及 WP_DEBUG_LOG 常量，這樣錯誤資訊會記錄到 /wp-content/debug.log 檔案中，而不會顯示給使用者。其次，可以使用 error_log() 函式輸出變數值到日誌。對於 Ajax 或複雜邏輯，瀏覽器開發者工具中的“網路”和“控制檯”面板是必不可少的除錯工具。
我的外掛如何與主題或其他外掛相容
保持相容性的最佳實踐是：嚴格遵循 WordPress 官方 API 和編碼標準；為你的函式、類、動作鉤子名稱新增唯一字首（如字首 mfp_）以避免衝突；在使用任何全域性變數或函式前，檢查其是否存在（使用 function_exists() 或者 class_exists()）；並清晰地在文件中說明你的外掛建立的資料庫表、选项或者 用户元数据。
外掛提交到 WordPress.org 目錄需要什麼條件
你需要擁有一個 WordPress.org 賬號，並確保外掛完全符合官方的要求。這包括：程式碼符合 GPL 相容許可證（通常就是 GPLv2+）；外掛必須 100% 開源且不依賴外部付費服務才能執行核心功能；包含標準格式的 readme.txt 檔案；程式碼中沒有惡意或垃圾內容；以及透過人工稽核團隊的檢查。提交前請仔細閱讀官方的外掛開發手冊和提交指南。
下一步，该怎么做呢？
延伸阅读与实用知识
下方列出的内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，然后逐步扩展到相关主题，这样效果通常会更好。