別再只會裝外掛！資深工程師手把手，帶你從零打造第一個 WordPress 神器

嘿，我是浪花科技的 Eric。身為一個整天跟 WordPress 程式碼打交道的工程師，我最常被問到的問題之一就是：「Eric，我想在網站上加一個 XXX 功能，有沒有推薦的外掛？」當然，WordPress 生態系最迷人的地方就是有成千上萬個外掛可以選。但你有沒有想過，如果找不到完全符合需求的外掛，或是裝了太多外掛，網站變得又慢又臃腫，該怎麼辦？

答案很簡單，但也很嚇人：自己寫一個！

先別急著關掉視窗！我知道「寫程式」聽起來很可怕，但相信我，WordPress 的外掛開發入門比你想像的要親民得多。今天，我就要帶你踏出第一步，從一個什麼都沒有的空白檔案，到一個真正在你網站上運作的小功能。這不只是篇教學，更像是一份邀請函，邀請你從「使用者」的角色，晉升為「創造者」。準備好了嗎？讓我們開始吧！

什麼是 WordPress 外掛？它真的不是黑魔法！

在我們動手寫第一行程式碼之前，得先搞懂一個核心觀念：WordPress 外掛到底是什麼？你可以把它想像成你手機上的 App。你的手機（WordPress 核心）本身就有通話、訊息等基本功能，但你想玩遊戲、叫外送、修圖，就得安裝不同的 App（外掛）。

外掛的精髓在於「擴充」而非「修改」。我們絕對、絕對、絕對不要去動到 WordPress 核心的檔案（那些 `wp-admin`, `wp-includes` 資料夾裡的東西）。為什麼？因為一旦 WordPress 更新，你做的所有修改都會被洗掉，到時候網站炸了可就欲哭無淚了。這是我剛入行時踩過的大地雷，相信我，你不會想體驗那種半夜被客戶 call 醒的感覺。

那 WordPress 是怎麼讓我們安全地擴充功能的呢？答案是 Hooks（鉤點）。

Hooks 是 WordPress 核心程式碼中預留的「掛鉤」，讓我們可以在特定的時間點「掛上」我們自己的程式碼。它主要分成兩種：

• Actions (動作)：當某個事件發生時，執行你的程式碼。例如，「當文章發佈時，自動寄一封通知信」。
• Filters (過濾器)：修改傳遞中的資料。例如，「在顯示文章標題前，在標題前面加上『HOT!』的字樣」。

搞懂 Hooks 的概念，你就掌握了 WordPress 開發的 80% 精髓。想更深入了解這兩兄弟的愛恨情仇，可以參考我之前寫的這篇解鎖 WordPress 的任督二脈：搞懂 Action & Filter Hooks，保證讓你功力大增。

開發前的準備：你的開發環境搞定了嗎？

俗話說，工欲善其事，必先利其器。在開始我們的 WordPress 外掛開發入門與實作之旅前，請確保你的「工作檯」是準備好的。

• 本地開發環境：千萬不要直接在正式上線的網站上開發！這就像在高速公路上邊開車邊修引擎一樣危險。你可以在自己的電腦上建立一個本地的 WordPress 網站，像是 MAMP、XAMPP 都是不錯的選擇。如果你想玩得更專業一點，強烈推薦使用 Docker，它可以完美複製線上環境，避免「在我電腦上明明可以跑」的窘境。對 Docker 不熟？可以看看這篇「在我電腦明明可以跑的?」WordPress Docker 容器化部署終極教學。
• 程式碼編輯器：記事本？拜託饒了我吧。一個好的程式碼編輯器能讓你事半功倍，像是 VS Code、Sublime Text 或 PhpStorm 都是業界主流，它們有語法高亮、自動完成等功能，能大大減少你打錯字的機率。
• 開啟除錯模式：這是最重要的步驟！打開你的 `wp-config.php` 檔案，找到 `define( ‘WP_DEBUG’, false );` 這一行，把它改成 `true`。

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // 建議一併開啟，會將錯誤訊息記錄到 wp-content/debug.log 檔案中

開啟除錯模式後，WordPress 就不會再對你「隱藏」錯誤訊息了。任何語法錯誤、警告都會直接顯示在畫面上，這對開發初期的抓蟲非常有幫助。

實戰開始：打造你的第一個「Hello World」外掛

理論講完了，我們來動手吧！我們的目標是做一個史上最簡單的外掛：在網站後台管理介面的頂端，顯示一行「哈囉，我的第一個外掛！」的文字。

步驟一：建立外掛的「身分證」- 檔案標頭

首先，到你的 WordPress 安裝目錄下的 `wp-content/plugins/` 資料夾，在裡面建立一個新的資料夾，例如 `my-first-plugin`。接著，在這個資料夾裡建立一個 PHP 檔案，檔名可以跟你資料夾一樣，例如 `my-first-plugin.php`。

用你的程式碼編輯器打開這個空白的 PHP 檔案，然後貼上以下這段「咒語」：

<?php
/**
 * Plugin Name:       我的第一個外掛
 * Plugin URI:        https://roamer-tech.com/
 * Description:       這是一個跟著浪花科技 Eric 教學寫出來的 WordPress 外掛。
 * Version:           1.0.0
 * Author:            你的名字
 * Author URI:        https://your-website.com/
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       my-first-plugin
 */

這段註解非常重要，它就是你外掛的「身分證」。WordPress 就是靠讀取這段資訊，才能在後台的「已安裝外掛」列表中正確顯示你的外掛名稱、描述、版本等資訊。少了這個，WordPress 根本不會把它當成一個外掛。

步驟二：啟用它！

儲存檔案後，回到你的 WordPress 後台，點擊「外掛」->「已安裝的外掛」。嘿！看看是誰在那裡？你應該能看到「我的第一個外掛」出現在列表裡了。勇敢地點下「啟用」吧！

啟用後… 沒錯，什麼事都沒發生。這是正常的！因為我們只給了它一張身分證，但還沒教它要做任何事情。

步驟三：讓外掛「說話」- 掛上第一個 Action Hook

接下來，我們要用前面提到的 Action Hook 來做事了。我們要掛上的 Hook 叫做 `admin_notices`，這個 Hook 會在後台管理頁面的頂部觸發。

在你的 `my-first-plugin.php` 檔案的標頭註解下方，加入以下程式碼：

// 避免非 WordPress 環境直接執行此檔案
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// 定義一個函式，用來顯示我們的訊息
function eric_display_hello_message() {
    echo '<div class="notice notice-success is-dismissible"><p>哈囉，我的第一個外掛！感謝浪花科技 Eric 大大！</p></div>';
}

// 將我們的函式掛到 'admin_notices' 這個 action 上
add_action( 'admin_notices', 'eric_display_hello_message' );

讓我們來分解一下這段程式碼：

• `if ( ! defined( ‘ABSPATH’ ) ) { exit; }`：這是一個安全措施，防止有人直接透過網址存取你的外掛檔案，算是一個標準起手式。
• `function eric_display_hello_message() { … }`：我們定義了一個 PHP 函式。函式名稱前面加上一個獨特的前綴（例如我的名字 `eric_`）是個好習慣，可以避免跟其他外掛或主題的函式名稱衝突。
• `add_action( ‘admin_notices’, ‘eric_display_hello_message’ );`：這就是整段程式碼的精華！我們使用 `add_action()` 函式，告訴 WordPress：「嘿！當你準備要執行 `admin_notices` 這個掛鉤的時候，麻煩順便執行一下我寫的 `eric_display_hello_message` 這個函式喔！」

儲存檔案，然後回到你的 WordPress 後台刷新頁面。看到了嗎？那條綠色的成功訊息！恭喜你，你已經成功完成了 WordPress 外掛開發入門與實作的第一步！

進階一點：用 Shortcode 打造一個自訂內容產生器

只在後台顯示訊息好像不太過癮，讓我們來做個更實用的功能：Shortcode (短代碼)。

Shortcode 是一種讓你在文章或頁面編輯器中，用一個簡單的標籤（例如 `[my_shortcode]`）來插入複雜 HTML 或動態內容的方法。這對非技術背景的網站編輯者來說非常方便。

我們的目標是建立一個 `[contact_info]` 的短代碼，當使用者在文章中輸入它時，會自動顯示公司的聯絡資訊。

註冊你的 Shortcode

繼續在我們的 `my-first-plugin.php` 檔案中加入以下程式碼：

function eric_contact_info_shortcode() {
    // 這裡的 HTML 內容可以更複雜
    $output = '<div class="contact-card">';
    $output .= '<h3>浪花科技 Roamer Tech</h3>';
    $output .= '<p>電話：(02) 1234-5678</p>';
    $output .= '<p>地址：台灣的某個地方</p>';
    $output .= '</div>';

    return $output; // Shortcode 函式必須用 return 回傳值，而不是 echo
}

add_shortcode( 'contact_info', 'eric_contact_info_shortcode' );

這裡的關鍵是 `add_shortcode()` 函式。它需要兩個參數：第一個是短代碼的名稱（`contact_info`），第二個是對應要執行的函式名稱。特別注意，處理 Shortcode 的函式必須使用 `return` 來回傳內容，而不是 `echo` 直接輸出，這是一個新手常犯的錯誤。

現在，去新增一篇文章或頁面，在編輯器中輸入 `[contact_info]`，然後預覽看看。神奇的事情發生了！你設定好的聯絡資訊就這樣出現了。

工程師的小囉嗦：寫出好外掛的幾個好習慣

恭喜你！你已經不只是個 WordPress 使用者，更是一位開發者了。但在你開始大展身手之前，讓我這個老鳥囉嗦幾句，這些是能讓你少走很多冤枉路的好習慣：

• 前綴、前綴、再前綴：WordPress 的環境是共享的，你的外掛會跟主題、其他外掛一起運作。為了避免函式、變數、CSS class 名稱衝突，請務必在所有東西前面加上一個獨特的前綴，例如 `roamer_tech_` 或 `rt_`。
• 安全第一：永遠不要相信使用者的輸入！任何來自使用者表單的資料，都必須經過驗證 (Validation) 和消毒 (Sanitization)。在處理表單提交時，記得使用 Nonces 來防止 CSRF 攻擊，想深入了解可以看看這篇你的表單安全嗎？揭開 WordPress Nonces 的神秘面紗。
• 程式碼標準：遵循 WordPress 官方的程式碼標準，這能讓你的程式碼更具可讀性，也更容易跟其他人協作。
• 保持學習：WordPress 不斷在進步，今天的教學只是個起點。多看看官方文件，多逛逛開發者社群，你的技能才會不斷提升。

從一個簡單的 `add_action` 到實用的 `add_shortcode`，你已經親手體驗了 WordPress 外掛開發的魔力。這扇大門已經為你敞開，門後有著無限的可能性，無論是打造客製化的文章類型 (CPT)、串接第三方 API，或是開發一套複雜的會員系統。希望今天的教學能點燃你心中的那把火，讓你從今天起，不再只是滿足於「安裝」，而是享受於「創造」。

推薦閱讀

• 解鎖 WordPress 的任督二脈：搞懂 Action & Filter Hooks，你的客製化功力瞬間爆發！
• 解鎖 WordPress 的隱藏力量：functions.php 終極實戰指南，讓你的網站秒變客製化神器！
• 別再把 WordPress 當部落格！資深工程師手把手 CPT 實戰，打造真正客製化的網站後台

如果你在開發路上遇到了瓶頸，或是有更複雜的客製化需求，需要專業團隊的協助，別忘了，浪花科技永遠是你最可靠的後盾。歡迎與我們聯繫，讓我們一起打造更強大的 WordPress 網站！