WordPress插件開發從入門到精通：手把手教你打造第一個自定義插件

為什麼學習 WordPress 插件開發

WordPress 之所以成為全球最受歡迎的內容管理系統，其強大的可擴展性功不可沒。這種可擴展性的核心正是插件。通過開發自定義插件，你可以為網站添加任何你想象得到的功能，而無需修改 WordPress 核心代碼。這不僅保證了核心更新的安全性，也讓你的功能模塊化，易於管理和遷移。

學習插件開發能夠讓你從 WordPress 的“使用者”轉變為“創造者”。無論是為客户定製獨特的功能，解決特定業務需求，還是將你的創意打包成產品在市場上銷售，掌握這項技能都為你打開了無限可能。更重要的是，理解插件開發的工作流程，能讓你在使用其他插件時，具備更好的調試和二次開發能力。

一個標準的 WordPress 插件在結構上是一個包含主 PHP 文件的文件夾。這個主文件通過特定的註釋頭部信息，向 WordPress 系統宣告自己的存在。所有業務邏輯，無論是添加一個新的小工具、創建一個自定義文章類型，還是處理表單數據，都通過 WordPress 提供的各種“鈎子”來掛載和執行。

推荐阅读 WordPress插件开发从入门到精通：手把手教你打造专属功能。

搭建你的第一個插件項目

開始開發前，你需要一個本地開發環境。我們推薦使用 XAMPP、MAMP、Local by Flywheel 或 Docker 等工具來搭建一個包含 PHP、MySQL 和 Apache/Nginx 的本地服務器。在本機 WordPress 安裝上進行開發，可以避免對線上網站造成影響。

UltaHost WordPress 主機

30天退款保證，無限帶寬與數據庫，免費的 DDoS 防護，購買3年優惠50%

访问页面

創建插件的基本文件結構

一個最簡單的插件可以只包含一個文件。在你的 WordPress 安裝目錄下，進入 wp-content/plugins 文件夾，創建一個新的文件夾，例如 my-first-plugin。然後，在此文件夾內創建一個主 PHP 文件，文件名通常與文件夾名一致，即 my-first-plugin.php。

編寫插件的元信息頭部

在插件主文件中，文件頂部的註釋塊至關重要。它告訴 WordPress 這個插件的名稱、描述、版本、作者等信息。一個標準的頭部如下所示：

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个用于学习 WordPress 插件开发的自定义插件。
 * Version:           1.0.0
 * Author:            你的名字
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       my-first-plugin
 * Domain Path:       /languages
 */

保存文件後，登錄你的 WordPress 後台，進入“插件”頁面，你應該能看到“我的第一個插件”出現在插件列表中，並可以激活它。至此，一個“空”但有效的插件就創建完成了。它目前沒有任何功能，但結構是正確的。

探索 WordPress 核心機制：鈎子與過濾器

WordPress 插件開發的核心在於理解並運用其“鈎子”系統。鈎子分為兩種：動作鈎子和過濾器鈎子。它們是 WordPress 允許你在特定時間點“注入”自定義代碼或修改數據的機制。

推荐阅读 WordPress插件開發入門指南：從零構建您的第一個功能擴展。

理解動作鈎子的運作方式

動作鈎子允許你在 WordPress 執行流程的特定時刻運行你的函數。例如，當頁面加載完畢時，或當一篇文章發佈時。使用 add_action() 函數可以將你的自定義函數掛載到一個鈎子上。其基本語法是：add_action( ‘hook_name’， ‘your_function_name’ );。

讓我們實現一個功能：在網站前台的頁面底部顯示一條自定義信息。我們會用到 wp_footer 这种动作很危险。

function my_custom_footer_message() {
    echo '<p style="text-align: center; color: #666;">感谢您访问本站！这是一个自定义插件添加的页脚信息。</p>';
}
add_action( 'wp_footer’, 'my_custom_footer_message’ );

將這段代碼添加到你的插件主文件 my-first-plugin.php 中，保存並刷新網站前台頁面，你會在頁腳看到這行文字。

hosting.com 共享主机

高性能配置，搭载 AMD EPYC CPU、NVMe SSD 存储和 LiteSpeed 技术，提供全天候 24 小时专业内部支持，具备 SSL、暴力破解、恶意软件及 DDoS 防护等高级安全措施，节省成本高达 73%。

访问页面

運用過濾器修改默認內容

過濾器鈎子用於修改 WordPress 在處理過程中產生的數據。與動作鈎子不同，過濾器函數必須返回一個值。使用 add_filter() 函數來掛載過濾器。例如，修改文章標題的默認內容：

function modify_post_title( $title ) {
    if ( is_single() ) {
        return '【精选】’ . $title;
    }
    return $title;
}
add_filter( ‘the_title’, 'modify_post_title’ );

這個函數會在文章單頁的標題前加上“【精選】”前綴，而其他頁面（如首頁、列表頁）的標題則保持不變。通過組合使用動作和過濾器，你可以控制 WordPress 的幾乎每一個環節。

構建一個實用的後台管理頁面

為了讓插件用户能夠配置選項，我們通常需要為其創建一個後台管理頁面。這涉及 WordPress 的管理菜單 API。

推荐阅读 WordPress插件開發從入門到精通：構建高自定義功能模塊的完整指南。

添加一個新的管理菜單項

使用 （注：此处"使用"指的是某种产品或服务的使用情况） add_menu_page() 或者 add_options_page() 等函數，可以將一個新的頁面添加到 WordPress 後台的左側菜單中。我們以在“設置”子菜單下添加一個頁面為例。

首先，創建一個函數來渲染管理頁面的 HTML 內容。

InterServer 共享主机

虚拟主机每月价格为 1TB + 5TB，费用为 2.50 美元，首月优惠价为 1TB + 5TB，价格为 0.1 美元。优惠码为 "tryinterserver"，支持一键安装 461 款云应用脚本。

访问页面

function my_plugin_settings_page_html() {
    // 检查用户权限
    if ( ! current_user_can( ‘manage_options’ ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1></h1>
        <form action="/zh-hk/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 输出设置字段和安全字段
            settings_fields( ‘my_plugin_settings’ );
            do_settings_sections( ‘my_plugin_settings’ );
            submit_button( ‘保存设置’ );
            ?>
        <input type="hidden" name="trp-form-language" value="zh-hk"/></form>
    </div>
    &lt;?php
}

註冊設置、區塊和字段

WordPress 提供了 register_setting(), add_settings_section() 以及 add_settings_field() 這一套 API 來規範化地處理設置。這能自動處理安全驗證（Nonce）和選項的保存/讀取。

接下來，我們需要一個函數來初始化這些設置。這個函數應該掛載到 admin_init 鱼钩上。

function my_plugin_settings_init() {
    // 注册一个新的设置选项组
    register_setting( ‘my_plugin_settings’, ‘my_plugin_options’ );

// 在页面中添加一个新的区块
    add_settings_section(
        ‘my_plugin_section_1’,
        ‘基础设置’,
        null, // 回调函数，用于输出区块描述，可为空
        ‘my_plugin_settings’
    );

// 在区块内添加一个字段
    add_settings_field(
        ‘my_plugin_field_text’,
        ‘欢迎语’,
        ‘my_plugin_field_text_cb’,
        ‘my_plugin_settings’,
        ‘my_plugin_section_1’,
        [
            ‘label_for’ => ‘my_plugin_field_text’,
            ‘class’ => ‘my_plugin_row’,
        ]
    );
}
add_action( ‘admin_init’, ‘my_plugin_settings_init’ );

// 字段的回调函数，用于输出字段的 HTML
function my_plugin_field_text_cb( $args ) {
    $options = get_option( ‘my_plugin_options’ );
    ?>
    <input type="text" id="<?php echo esc_attr( $args[‘label_for’] ); ?>"
           name="my_plugin_options[<?php echo esc_attr( $args[‘label_for’] ); ?>]"
           value="<?php echo esc_attr( $options[ $args[‘label_for’] ] ?? ‘’ ); ?>">
    <p class="“description”">这段文字将显示在网站首页。</p>
    &lt;?php
}

將頁面鏈接添加到菜單

最後，使用 add_options_page() 將我們創建的這個頁面添加到“設置”菜單下。

function my_plugin_add_settings_page() {
    add_options_page(
        ‘我的插件设置’, // 页面标题
        ‘我的插件’, // 菜单标题
        ‘manage_options’, // 所需能力
        ‘my-plugin-settings’, // 菜单别名
        ‘my_plugin_settings_page_html’ // 渲染页面的回调函数
    );
}
add_action( ‘admin_menu’, ‘my_plugin_add_settings_page’ );

現在，激活插件後，你可以在 WordPress 後台的“設置”菜單下找到“我的插件”選項，點擊進入即可看到一個包含一個文本字段的設置頁面，你可以輸入並保存歡迎語。之後，你可以通過 get_option( ‘my_plugin_options’ ) 在前台獲取並使用這個值。

實現插件的前台功能與安全考慮

在插件中實現前台功能時，安全是首要考慮因素。永遠不要相信用户輸入的數據，必須進行驗證、清理和轉義。

假設我們要使用在後台設置中保存的“歡迎語”，並將其顯示在網站首頁的頂部。首先，我們需要從數據庫獲取這個選項，然後安全地輸出。

function display_frontend_greeting() {
    // 1. 获取数据
    $options = get_option( ‘my_plugin_options’ );
    $greeting = $options[‘my_plugin_field_text’] ?? ‘’;

// 2. 如果内容为空，则不输出任何东西
    if ( empty( $greeting ) ) {
        return;
    }

// 3. 在输出前进行清理和转义
    $safe_greeting = esc_html( $greeting );

// 4. 输出到前端（这里假设只在首页显示）
    if ( is_front_page() ) {
        echo ‘<div class="“my-plugin-greeting”"><p>’ . $safe_greeting . ‘</p></div>’;
    }
}
add_action( ‘wp_body_open’, ‘display_frontend_greeting’ );

這裏我們用了 esc_html() 函數來轉義 HTML 字符，防止跨站腳本攻擊（XSS）。我們還檢查了數據是否為空，並使用條件標籤 is_front_page() 來控制輸出的位置。將函數掛載到 wp_body_open 鈎子，可以確保內容在頁面 body 標籤開始後立即顯示。

此外，在插件開發中，國際化也是一項重要實踐。通過使用 __() 以及 _e() 等翻譯函數，並正確設置插件的文本域（Text Domain），可以讓你的插件被翻譯成任何語言。在前面的插件頭部元信息中，我們已經定義了 Text Domain: my-first-plugin。在代碼中，應該這樣使用：

echo esc_html__( ‘Hello, World!’, ‘my-first-plugin’ );

总结

通過本文的實踐，我們完成了一個完整但簡單的 WordPress 插件開發流程。我們從創建插件的基礎文件結構和元信息開始，逐步深入到 WordPress 的核心機制——鈎子系統，利用動作和過濾器來控制程序流和修改數據。隨後，我們構建了一個帶有自定義字段的後台管理頁面，讓用户可以配置插件選項，並最終將這些選項安全地輸出到網站前台。

這個過程涵蓋了插件開發的幾個關鍵方面：文件組織、鈎子運用、後台界面創建、選項管理以及前端數據安全處理。記住，優秀的插件不僅功能強大，更應該是安全、高效且易於維護的。接下來，你可以嘗試為插件添加更多功能，比如自定義文章類型、短代碼、小工具或者 REST API 端點，不斷深化你對 WordPress 插件開發的理解。

常见问题解答（FAQ）

一個插件可以只包含一個 PHP 文件嗎？

是的，一個最簡單的 WordPress 插件可以只由一個 PHP 文件構成，只要該文件包含正確的插件頭部註釋。但對於功能複雜的插件，建議將代碼組織在不同的文件中，例如將後台功能、前台功能和公共函數分別存放，以提高代碼的可讀性和可維護性。

如何調試自己開發的插件？

推薦開啓 WordPress 的調試模式。在站點根目錄的 wp-config.php 文件中，将…… WP_DEBUG 常量被设置为： true。這樣，PHP 錯誤、警告和通知都會顯示出來。同時，可以結合使用 error_log() 函數將調試信息寫入服務器的錯誤日誌，或者使用瀏覽器開發者工具的控制枱進行 JavaScript 調試。

開發插件時，有哪些必須遵守的安全規範？

首要原則是：永遠不要信任任何用户輸入。對所有從 $_GET、$_POST、$_COOKIE 獲取的數據進行驗證和清理。在將數據輸出到 HTML 時，使用 esc_html()、esc_attr()、esc_url() 等函數進行轉義。在構造數據庫查詢時，務必使用 $wpdb->prepare() 方法來防止 SQL 注入攻擊。此外，檢查當前用户的權限（如 current_user_can()）也是必不可少的步驟。

如何將我的插件提交到官方的 WordPress 插件目錄？

首先，確保你的插件完全遵循 WordPress 的編碼標準和 GPL 許可證。你需要訪問 WordPress.org 並創建一個賬號，然後在插件提交頁面提交你的插件壓縮包。官方團隊會進行人工審核，檢查代碼質量、安全性、文檔和合規性。審核通過後，你的插件就會被列入官方目錄，獲得自動更新支持，並可以被全球用户搜索和安裝。