主页/知识/ワードプレス/内容详情

從零開始學習 WordPress 插件開發：構建你的第一個自定義功能

3 分钟阅读时间
2026-03-14
2026-06-03
2,906
當您透過下方連結購物時，我會獲得佣金，而您無需支付額外费用。.

掌握 WordPress 插件開發是擴展網站功能、實現個性化需求的核心技能。與修改主題 functions.php 文件相比，使用插件能確保功能獨立於主題，便於遷移、管理和維護。本文將引導你從零開始，創建一個結構完整、符合 WordPress 編碼標準的插件。

准备工作与环境搭建

在編寫第一行代碼之前，你需要一個合適的開發環境和對 WordPress 架構有基本的理解。

開發環境配置

一個標準的本地開發環境是高效開發的基石。推薦使用 XAMPP、MAMP 或 Local by Flywheel 等工具，它們能一鍵安裝 Apache、MySQL/Nginx、PHP 和 WordPress。此外，確保你的文本編輯器或 IDE（如 VS Code、PhpStorm）支持 PHP 語法高亮和代碼提示，這將大大提升開發效率。

推荐阅读 深入解析 WordPress 插件開發：從零入門到高效定製。

理解 WordPress 插件架構

WordPress 插件本質上是一個或多個 PHP 文件，存放在 wp-content/plugins/ 目錄下。它的核心原理是“鉤子”機制。插件通過“動作鉤子”在特定時間點執行代碼，或通過“過濾器鉤子”修改其他函數輸出的數據。理解 add_action 以及 add_filter 這兩個函數是插件開發的入門鑰匙。

UltaHost WordPress 主機
30天退款保證，無限帶寬與數據庫，免費的 DDoS 防護，購買3年優惠50%
UltaHost LOGO 访问页面

創建你的第一個插件：問候小工具

我們將創建一個名爲“每日問候”的簡單插件。它會在網站的管理後臺儀表盤顯示一個自定義的歡迎小工具。

建立插件主文件

首先，在 wp-content/plugins/ 目錄下創建一個新文件夾，命名爲 my-first-greeting-plugin。在該文件夾內，創建主插件文件 my-first-greeting-plugin.php。

每個插件都必須以標準的插件頭部註釋開始，這是 WordPress 識別插件信息的標識。打開主文件，輸入以下代碼：

<?php
/**
 * Plugin Name: 每日问候
 * Plugin URI:  https://www.yourwebsite.com/my-first-greeting-plugin
 * Description: 这是一个示例插件，用于在仪表盘显示个性化问候。
 * Version:     1.0.0
 * Author:      Your Name
 * Author URI:  https://www.yourwebsite.com
 * License:     GPL v2 or later
 * Text Domain: my-first-greeting
 */

保存文件後，進入 WordPress 後臺的“插件”頁面，你應該能看到“每日問候”插件出現在列表中，並可以激活它。目前它還沒有任何功能。

推荐阅读 WordPress外掛開發終極指南：從零到一構建你的第一個外掛。

爲儀表盤添加小工具

接下來，我們將使用 WordPress 的 wp_dashboard_setup 動作鉤子來添加一個自定義的儀表盤小工具。在主文件的頭部註釋下方，繼續添加以下代碼：

// 添加仪表盘小工具
function mfgp_add_dashboard_widget() {
    wp_add_dashboard_widget(
        'mfgp_dashboard_widget',          // 小工具唯一ID
        '每日问候',                       // 小工具标题
        'mfgp_dashboard_widget_content'  // 显示内容的回调函数
    );
}
add_action( 'wp_dashboard_setup', 'mfgp_add_dashboard_widget' );

// 定义小工具内容
function mfgp_dashboard_widget_content() {
    $user = wp_get_current_user();
    $hour = date('G'); // 获取当前小时（24小时制）

if ( $hour &gt;= 5 &amp;&amp; $hour < 12 ) {
        $greeting = '早上好';
    } elseif ( $hour >= 12 &amp;&amp; $hour &lt; 18 ) {
        $greeting = &#039;下午好&#039;;
    } else {
        $greeting = &#039;晚上好&#039;;
    }

echo &#039;<p>' . sprintf( esc_html__( '%s，%s！欢迎回来。', 'my-first-greeting' ), $greeting, esc_html( $user-&gt;display_name ) ) . '</p>';
    echo '<p>' . esc_html__( '这是你的第一个插件创建的问候小工具。', 'my-first-greeting' ) . '</p>';
}

這段代碼做了兩件事：首先，它定義了一個函數 mfgp_add_dashboard_widget使用 wp_add_dashboard_widget 函數註冊一個小工具。然後，定義了 mfgp_dashboard_widget_content 函數來生成小工具的內容，它會根據一天中的不同時間顯示不同的問候語，並稱呼當前登錄的用戶名。注意我們使用了 esc_html__() 以及 esc_html() 函數進行翻譯準備和輸出轉義，這是確保安全性和國際化的重要實踐。

激活插件後，刷新儀表盤頁面，你就能看到“每日問候”小工具了。

hosting.com 共享主机
高性能配置，搭载 AMD EPYC 处理器、NVMe SSD 存储及 LiteSpeed 技术，提供全天候 24 小时专家内部支持，具备 SSL、暴力破解、恶意软件及 DDoS 防护等高级安全措施，节省成本高达 73%。
ホスティング.comのロゴ 访问页面

插件功能增強與安全實踐

一個基礎的插件已經完成，但要使其更健壯、更專業，我們需要關注安全、可維護性和用戶配置。

添加插件設置頁面

讓用戶能自定義問候語會更有用。我們將爲插件創建一個簡單的設置頁面。

首先，使用 admin_menu 動作鉤子添加一個子菜單頁：

推荐阅读 WordPress插件開發入門指南：從零開始構建你的第一個自定義插件。

// 添加设置菜单
function mfgp_add_admin_menu() {
    add_options_page(
        '每日问候设置',                // 页面标题
        '每日问候',                    // 菜单标题
        'manage_options',             // 所需权限
        'my-first-greeting-plugin',   // 菜单slug
        'mfgp_settings_page_content' // 回调函数
    );
}
add_action( 'admin_menu', 'mfgp_add_admin_menu' );

然後，創建設置頁面的內容、註冊設置選項和處理表單保存：

// 设置页面内容
function mfgp_settings_page_content() {
    ?&gt;
    <div class="wrap">
        <h1></h1>
        <form action="/zh-hant/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            settings_fields( 'mfgp_settings_group' ); // 输出安全字段
            do_settings_sections( 'my-first-greeting-plugin' ); // 输出设置区块
            submit_button(); // 输出提交按钮
            ?>
        <input type="hidden" name="trp-form-language" value="zh-hant"/></form>
    </div>
    <?php
}

// 初始化设置
function mfgp_settings_init() {
    register_setting(
        'mfgp_settings_group', // 选项组名
        'mfgp_custom_message', // 选项名
        array( 'sanitize_callback' => 'sanitize_text_field' ) // 清理回调
    );

add_settings_section(
        'mfgp_section', // 区块ID
        '自定义问候设置', // 区块标题
        null, // 区块描述回调（无）
        'my-first-greeting-plugin' // 所属页面
    );

add_settings_field(
        'mfgp_field',
        '自定义问候语前缀',
        'mfgp_field_callback', // 输出字段HTML的回调
        'my-first-greeting-plugin',
        'mfgp_section'
    );
}
add_action( 'admin_init', 'mfgp_settings_init' );

// 设置字段的回调函数
function mfgp_field_callback() {
    $value = get_option( 'mfgp_custom_message', '祝您有愉快的一天，' );
    echo '<input type="text" name="mfgp_custom_message" value="' . esc_attr( $value ) . '" class="regular-text" />';
    echo '<p class="description">这段文字将添加到问候语之前。</p>';
}

最後，修改小工具內容函數，使用戶的自定義設置生效：

InterServer 共享主机服务
共享主机每月价格为 $2.50 美元，首月优惠价为 $0.1 美元，优惠码为 tryinterserver，提供 461 个云应用脚本，可一键安装。
InterServer 로고 访问页面 
// 更新小工具内容函数，使用自定义消息
function mfgp_dashboard_widget_content() {
    $user = wp_get_current_user();
    $hour = date('G');
    $custom_msg = get_option( 'mfgp_custom_message', '祝您有愉快的一天，' );

if ( $hour &gt;= 5 &amp;&amp; $hour < 12 ) {
        $greeting = '早上好';
    } elseif ( $hour >= 12 &amp;&amp; $hour &lt; 18 ) {
        $greeting = &#039;下午好&#039;;
    } else {
        $greeting = &#039;晚上好&#039;;
    }

echo &#039;<p>' . esc_html( $custom_msg ) . sprintf( esc_html__( '%s，%s！', 'my-first-greeting' ), $greeting, esc_html( $user-&gt;display_name ) ) . '</p>';
}

現在，在 WordPress 後臺的“設置”菜單下會出現“每日問候”選項頁，管理員可以保存一段自定義的問候前綴。

遵循安全與編碼標準

在開發過程中，必須遵循 WordPress 安全實踐：對所有來自用戶或數據庫的、即將輸出的數據使用適當的轉義函數（如 esc_html, esc_attr, esc_url）；對所有用戶輸入進行驗證和清理（如使用 sanitize_text_field）；使用 wp_kses_post 或者 wp_kses 來允許安全的 HTML。同時，建議遵循 WordPress 官方 PHP 編碼標準，以確保代碼的清晰和一致。

插件國際化與發佈準備

爲了讓你的插件能被全球用戶使用，國際化是必不可少的步驟。同時，爲發佈到官方目錄做準備也需要遵循一些規範。

實現插件國際化

我們在代碼中已經使用了 esc_html__() 來包裝需要翻譯的字符串。要完成國際化，你需要在插件目錄下創建一個 languages 文件夾。然後，在主文件頭部註釋後添加以下代碼，加載文本域：

// 加载文本域以实现国际化
function mfgp_load_textdomain() {
    load_plugin_textdomain( 'my-first-greeting', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}
add_action( 'plugins_loaded', 'mfgp_load_textdomain' );

之後，你可以使用如 Poedit 這樣的工具，掃描插件代碼中的翻譯字符串，生成 .pot 模板文件，併爲不同語言（如中文 zh_CN）創建 .po 以及编译后的内容 .mo 文件，放入 languages 文件夾。

準備發佈到官方目錄

如果你計劃將插件提交到 WordPress.org 插件目錄，需要確保代碼質量，幷包含必要的元數據文件。例如，創建一個 readme.txt 文件，其格式必須符合 WordPress 的特定規範，包含插件名稱、描述、安裝步驟、常見問題、更新日誌等。此外，考慮添加一個卸載鉤子，用於在用戶刪除插件時清理數據庫中的選項：

// 插件卸载时清理选项
function mfgp_uninstall_hook() {
    delete_option( 'mfgp_custom_message' );
}
register_uninstall_hook( __FILE__, 'mfgp_uninstall_hook' );

总结

通過構建這個“每日問候”插件，我們完整走過了 WordPress 插件開發的核心流程：從建立基礎文件結構、利用動作鉤子添加功能，到創建管理界面、實現安全規範和國際化準備。關鍵在於理解並熟練運用 WordPress 的鉤子系統，並始終將安全性和代碼標準放在首位。這個簡單的例子是你插件開發之旅的起點，你可以在此基礎上探索更復雜的短代碼、自定義文章類型、REST API 端點等功能，開發出功能強大的專業插件。

常见问题解答（FAQ）

插件必須放在哪個目錄？

WordPress 插件必須放置在網站的 wp-content/plugins/ 目錄下。每個插件可以是一個獨立的 PHP 文件，但更常見的是一個以插件命名的文件夾，裏面包含主文件和其他資源。

爲什麼我的插件在後臺列表中不顯示？

請檢查主插件文件的頭部註釋（Plugin Name, Description 等）格式是否正確且完整。確保文件位於正確的目錄，並且 WordPress 有權限讀取該文件。此外，檢查 PHP 代碼開頭是否沒有多餘的空格或字符。

如何調試插件中的 PHP 錯誤？

于 wp-config.php 文件中将 WP_DEBUG 常量設置爲 true。這將允許 WordPress 在頁面上顯示 PHP 錯誤、警告和通知。請注意，僅在開發環境中啓用此功能，上線前務必將其關閉。

插件與主題的 functions.php 文件有何區別？

关于这个主题的 functions.php 中添加的功能與該主題綁定。當切換主題時，這些功能可能會失效。而插件提供的功能獨立於主題，無論使用哪個主題，只要插件被激活，功能就始終可用。對於通用性功能，開發插件是更優的選擇。

如何讓其他開發者擴展我的插件？

你可以通過提供自定義的“動作鉤子”和“過濾器鉤子”來讓其他開發者擴展你的插件。使用 do_action() 創建動作鉤子，在他們需要注入代碼的地方“做動作”。使用 apply_filters() 創建過濾器鉤子，允許他們修改你插件中的某些數據值。這是 WordPress 生態中插件間協作的通用模式。

接下来，我该怎么做呢？

如果你正在搭建或优化WordPress网站，建议接下来继续阅读关于性能优化、插件配置和主题定制的相关内容。

延伸阅读与实用知识

以下内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，之后再逐步扩展到相关主题，这样通常效果会更好。

标签：