告別複製貼上！資深工程師手把手帶你打造第一個 WordPress 短代碼 (Shortcode) 外掛

Hi，我是浪花科技的 Eric。身為一個整天跟程式碼打交道的工程師，我最看不慣的就是「重複」這件事。看到客戶或同事在文章編輯器裡，一次又一次地複製貼上同樣版型、同樣風格的 HTML 程式碼，我的工程師魂就在吶喊：「這不科學啊！」這種作法不僅浪費時間，還容易出錯，未來要修改更是場災難。

今天，我就要帶你終結這種低效率的作法，用 WordPress 內建的超強力武器——短代碼 (Shortcode)——來打造你的第一個外掛。這不只是篇教學，更是一場思維的升級，讓你從「網站使用者」蛻變為「網站創造者」。準備好了嗎？我們開始吧！

為什麼要自己寫外掛？`functions.php` 不香嗎？

「Eric，我把程式碼丟進佈景主題的 `functions.php` 也可以啊！」我知道，我知道，這大概是每個 WordPress 開發新手的必經之路。但聽我這個老司機一句勸，把所有東西都塞進 `functions.php` 就像是你家的雜物間，什麼都往裡塞，短期很方便，長期下來就是一場災難。

把功能性的程式碼放在 `functions.php` 有幾個致命缺點：

• 主題依賴性： 你的所有客製化功能都跟著佈景主題走，哪天你想換個新主題，很抱歉，你的功能就全部掰了。這超慘的，等於你的網站被主題綁架了。
• 管理混亂： 隨著功能越加越多，`functions.php` 會變得越來越肥，幾千行程式碼擠在一起，半年後回來看，你可能連自己都看不懂當初在寫什麼。這就是所謂的「技術債」。
• 可攜性差： 假設你開發了一個超棒的功能，想把它用在另一個網站上？你得手動去 `functions.php` 裡大海撈針，找出相關的程式碼片段，然後再複製貼上。這過程不僅超沒效率，還很容易漏掉東西。

把功能模組化成一個獨立的外掛，才是專業且具備長遠眼光的做法。它乾淨、好管理、可重複使用，而且與你的佈景主題完全脫鉤。這才是我們工程師追求的「高內聚、低耦合」的美學！

動手前的準備：磨刀不誤砍柴工

在我們一頭栽進程式碼的世界之前，請確保你的裝備都準備好了。這不是在玩遊戲，裝備不好可是會卡關的。

• 一個本地開發環境： 拜託，我求你了，千萬不要在正式上線的網站上直接寫程式碼！這跟在高速公路上邊開車邊修引擎一樣危險。你隨時可能搞垮整個網站。請使用 Docker、MAMP、XAMPP 或 Local by Flywheel 等工具在你的電腦上架設一個本地 WordPress 環境。
• 一個好的程式碼編輯器： VS Code、Sublime Text、PHPStorm… 隨便你選一個順手的。但拜託，別再用 Windows 內建的記事本了，那會讓你的程式碼看起來像一場災難。
• 基礎的 PHP 知識： 你至少要知道變數、函式、陣列這些基本概念。這篇文章不是從零教你 PHP，而是教你如何在 WordPress 這個強大的框架下，運用你的 PHP 技能來解決問題。

WordPress 外掛的「身分證」：Plugin Header

WordPress 怎麼知道你的 PHP 檔案是個外掛，而不是什麼阿貓阿狗的檔案？答案就在檔案最上面的註解區塊，我們稱之為「外掛標頭 (Plugin Header)」。這就像是外掛的身分證，上面清楚記載了它的名字、作者、版本等重要資訊。沒有這個，WordPress 壓根不會理你。

一個基本的外掛標頭長這樣：

<?php
/**
 * Plugin Name:       我的第一個短代碼外掛
 * Plugin URI:        https://roamer-tech.com/
 * Description:       這是我學習 WordPress 外掛開發所做的第一個短代碼外掛。
 * Version:           1.0.0
 * Author:            Eric @ Roamer Tech
 * Author URI:        https://roamer-tech.com/
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       my-greeting-shortcode
 */

實戰開始：打造你的第一個「問候語」短代碼

理論說完了，來點實際的吧！我們的目標是建立一個簡單的短代碼 `[greeting]`，當你在文章中插入它時，它會自動顯示「你好，歡迎來到浪花科技！」。

Step 1. 建立外掛檔案結構

首先，打開你的 WordPress 安裝資料夾，找到 `wp-content/plugins/`。在這裡，建立一個新的資料夾，用來存放我們的外掛。資料夾名稱最好是獨一無二且有意義的，例如 `my-greeting-shortcode`。然後，在這個資料夾裡，建立一個同名的 PHP 檔案 `my-greeting-shortcode.php`。

Step 2. 寫入 Plugin Header

打開剛建立的 `my-greeting-shortcode.php` 檔案，把上面那段 Plugin Header 程式碼貼進去，並修改成你自己的資訊。

Step 3. 撰寫短代碼的「大腦」——PHP 函式

接著，我們要撰寫一個 PHP 函式，這個函式就是短代碼的核心邏輯，它負責產生我們想要顯示的內容。

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

// 短代碼處理函式
function rh_greeting_shortcode_handler() {
    return "你好，歡迎來到浪花科技！";
}

這裡我加了一個安全檢查 `if ( ! defined( ‘ABSPATH’ ) )`，這是個好習慣，可以防止有人直接透過網址存取你的 PHP 檔案。另外，我用了 `rh_` 當作函式的前綴，這是為了避免跟其他外掛或主題的函式名稱衝突，待會會再囉嗦一下。

Step 4. 註冊短代碼，讓 WordPress 認識它

有了函式還不夠，你得告訴 WordPress：「嘿！當你看到 `[greeting]` 這個標籤時，要去執行我剛剛寫的 `rh_greeting_shortcode_handler` 函式喔！」這個「告訴」的動作，我們用 `add_shortcode()` 這個函式來完成。

add_shortcode('greeting', 'rh_greeting_shortcode_handler');

把這行加到你的函式下方。第一個參數 `’greeting’` 是短代碼的標籤，第二個參數 `’rh_greeting_shortcode_handler’` 是要對應執行的函式名稱。現在，整個外掛檔案的內容應該是這樣：

<?php
/**
 * Plugin Name:       我的第一個短代碼外掛
 * Description:       這是我學習 WordPress 外掛開發所做的第一個短代碼外掛。
 * Version:           1.0.0
 * Author:            Eric @ Roamer Tech
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

function rh_greeting_shortcode_handler() {
    return "你好，歡迎來到浪花科技！";
}
add_shortcode('greeting', 'rh_greeting_shortcode_handler');

恭喜！你已經完成了你的第一個外掛！現在到 WordPress 後台的「外掛」頁面，你應該能看到它了，啟用它，然後到任何文章或頁面編輯器中輸入 `[greeting]`，預覽看看，神奇的事情就發生了！

技能升級：讓你的短代碼更「客製化」——屬性 (Attributes)

只會顯示固定的文字太無聊了，我們來讓它變得更聰明。如果我們希望可以客製化問候的對象，例如輸入 `[greeting name=”Eric”]` 就會顯示「你好，Eric！歡迎來到浪花科技！」，該怎麼做呢？這就要用到「屬性 (Attributes)」。

我們需要修改一下 `rh_greeting_shortcode_handler` 函式，讓它可以接收參數。WordPress 會將短代碼中的所有屬性打包成一個陣列，傳遞給我們的處理函式。

function rh_greeting_shortcode_handler($atts) {
    $atts = shortcode_atts( array(
        'name' => '訪客',
    ), $atts, 'greeting' );

    return "你好，" . esc_html($atts['name']) . "！歡迎來到浪花科技！";
}

這裡有兩個重點：

• `shortcode_atts()`: 這是 WordPress 提供的一個超方便的函式。它會幫你合併預設值和使用者傳入的值。像上面這段，我設定了 `name` 的預設值是「訪客」，如果使用者沒有在短代碼中提供 `name` 屬性，就會使用這個預設值。
• `esc_html()`: 安全第一！這個函式會「跳脫」使用者輸入的內容，把潛在的惡意 HTML 標籤轉換成純文字，防止 XSS (跨站腳本) 攻擊。永遠不要相信使用者的輸入！

終極進化：包覆內容的短代碼

短代碼還有更酷的玩法，就是包覆內容。例如，我們想做一個可以將文字加上螢光筆效果的短代碼，用法是 `[highlight]這段文字很重要[/highlight]`。

要做到這點，我們的處理函式需要接收第二個參數 `$content`，它會儲存被短代碼包住的內容。

function rh_highlight_shortcode_handler($atts, $content = null) {
    return '<span style="background-color: yellow; padding: 2px 5px;">' . esc_html($content) . '</span>';
}
add_shortcode('highlight', 'rh_highlight_shortcode_handler');

你看，我們 просто把傳入的 `$content` 用一個帶有黃色背景樣式的 `` 標籤包起來，然後回傳。同樣地，別忘了用 `esc_html()` 處理內容，確保安全。

工程師的囉嗦：寫出好 Code 的習慣

程式碼能動只是基本要求，寫出「好」的程式碼才是專業的體現。請容我再囉嗦幾句：

• 加上獨一無二的前綴 (Prefix)： WordPress 的函式庫是個全域的大染缸，你定義的函式 `do_something()` 很有可能跟其他成千上萬個外掛或主題的 `do_something()` 打架，導致網站崩潰。所以，永遠、永遠、永遠要為你的函式、類別、常數加上一個獨特的前綴，像我習慣用的 `rh_` (Roamer Tech)。這是生存法則，不是建議！
• 安全！安全！安全！ 重要的事情講三遍。從使用者來的一切都不可信，包括短代碼的屬性和內容！處理輸出時，請務必使用 `esc_html()`, `esc_attr()`, `esc_url()` 等 WordPress 提供的跳脫函式，這是你的責任，也是職業道德。
• 保持程式碼乾淨： 適當地加上註解，解釋你的程式碼在幹嘛、為什麼這麼寫。幾個月後回來看程式碼的你，會跪謝現在的自己。

搞砸了怎麼辦？啟用除錯模式

寫程式不可能一帆風順，遇到「死亡白畫面 (White Screen of Death)」是家常便飯。這時候千萬別慌，WordPress 有內建的除錯模式可以救你。

打開你 WordPress 根目錄下的 `wp-config.php` 檔案，找到 `define( ‘WP_DEBUG’, false );` 這一行，把它改成：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // 強烈建議！會把錯誤訊息記錄到 wp-content/debug.log 檔案中
define( 'WP_DEBUG_DISPLAY', false ); // 在正式站上建議設為 false，避免把錯誤訊息直接顯示給訪客看

這樣 WordPress 就會把詳細的錯誤訊息記錄下來，告訴你問題出在哪個檔案的第幾行。這是每個 WordPress 開發者都必須學會的救命仙丹。

結論

今天，你從零到一打造了自己的第一個 WordPress 外掛，學會了短代碼的基本用法、如何使用屬性增加彈性，以及如何處理包覆性內容。這只是 WordPress 開發世界的敲門磚，後面還有更廣闊的世界等著你，像是 Hooks (Action & Filter)、Custom Post Type、REST API 等等。

不要害怕犯錯，動手去寫、去嘗試，把你的想法變成實際的程式碼。每解決一個 bug，你的功力就會更上一層樓。希望這篇文章能為你的 WordPress 外掛開發之路點亮一盞燈。

如果你在開發過程中遇到更複雜的問題，或是需要為你的企業打造更專業、更穩定的客製化 WordPress 解決方案，別忘了，浪花科技的團隊永遠是你最可靠的後盾。

相關閱讀

• 解鎖 WordPress 的隱藏力量：functions.php 終極實戰指南，讓你的網站秒變客製化神器！
• 解鎖 WordPress 的任督二脈：搞懂 Action & Filter Hooks，你的客製化功力瞬間爆發！
• 網站又掛了？別再瞎猜！資深工程師的 WordPress 偵錯終極指南，從「死亡白畫面」到效能瓶頸全搞定！

覺得自己動手太複雜，或是有更進階的客製化需求嗎？

浪花科技提供專業的 WordPress 顧問與開發服務，從效能調校、金流串接到企業級的系統整合，我們都有豐富的實戰經驗。讓我們幫你把時間花在刀口上，專注於你的核心業務！

立即聯繫我們，預約免費諮詢