Action vs. Filter 徹底解剖：你真的懂 WordPress Hooks 的『執行』與『修改』嗎？

嗨，我是浪花科技的 Eric。身為一個整天跟 WordPress 程式碼打交道的工程師，我最常被問到的問題之一就是：「欸 Eric，那個 Action 和 Filter 到底差在哪？我什麼時候該用哪個？」

這問題問得太好了。如果你想從一個只會裝外掛、改版型的人，進階到能真正客製化、打造彈性功能的 WordPress 開發者，那麼搞懂 Hooks，尤其是 WordPress Hook 與 Filter 差異與應用，就是你非過不可的『新手村最終 Boss』。很多人覺得它們很像，用起來也差不多，但這誤會可大了。用錯了，輕則功能沒反應，重則整個網站畫面空白，客戶半夜 call 你，那可不是開玩笑的。

今天，就讓我這個資深工程師，帶你徹底解剖這兩個 WordPress 的靈魂核心，保證你看完之後，不只分得清，還能用得嚇嚇叫！

什麼是 WordPress Hooks？不動核心的客製化魔法

在我們深入探討 Action 和 Filter 之前，你得先理解什麼是「Hook（鉤子）」。

想像一下 WordPress 是一個正在運行的龐大工廠流水線，從初始化、處理請求、查詢資料庫、到最後輸出 HTML 畫面，每個環節都依序進行。而 WordPress 的核心開發者們非常聰明，他們在流水線的各個關鍵節點上，都預留了很多「鉤子」。

這些鉤子就像是預留的插座，讓你可以把自己寫的功能「掛」上去，在特定的時間點執行特定的任務，或是「攔截」流水線上的零件（資料）來加工一下。這就是 WordPress 的核心哲學：「Don’t Hack the Core」。你不需要去修改 WordPress 的原始碼，就能透過這些鉤子來擴充或修改它的功能，這讓你的客製化程式碼能安全地存活在佈景主題的 `functions.php` 或你自己的外掛裡，就算 WordPress 核心更新了，你的功能也不會被蓋掉。

而這些鉤子，主要就分成兩大類：Action Hooks 和 Filter Hooks。

事件的廣播站：Action Hooks (執行某件事)

我喜歡把 Action Hook 形容成一個「廣播站」或「事件觸發器」。它的運作邏輯非常單純：「當某件事發生的時候，請幫我『執行』這些額外的動作。」

舉個例子，當 WordPress 準備在頁面最下方輸出 `` 標籤之前，它會廣播一下：「嘿！我要結束頁面了喔！」這個廣播的代號就是 `wp_footer`。你可以寫一個函式，然後用 `add_action()` 告訴 WordPress：「聽到 `wp_footer` 這個廣播時，麻煩幫我執行一下我這個函式！」

• 核心功能：在特定時間點觸發一個或多個函式。
• 關鍵字：執行 (Do)、觸發 (Trigger)。
• 返回值：它不期望你回傳任何東西。你做完你的事就好，拍拍屁股走人，流水線會繼續往下走。

實戰演練：在網站頁尾加入 Google Analytics 追蹤碼

這是最經典的 Action Hook 應用了。你總不希望手動去改每個頁面的 `footer.php` 吧？我們只需要把追蹤碼掛在 `wp_footer` 這個鉤子上就行。

打開你佈景主題的 `functions.php` 檔案，加入以下程式碼：

<?php
// 將我們的函式掛到 'wp_footer' 這個 action hook 上
add_action( 'wp_footer', 'roamer_add_ga_tracking_code' );

function roamer_add_ga_tracking_code() {
    // 這段只是示意，請換成你自己的 GA 追蹤碼
    ?>
    <script async src="https://www.googletagmanager.com/gtag/js?id=YOUR_TRACKING_ID"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());

      gtag('config', 'YOUR_TRACKING_ID');
    </script>
    <?php
}
?>

看到了嗎？`roamer_add_ga_tracking_code` 這個函式做的事情就是 `echo` 出一段 JavaScript。它不需要 `return` 任何東西。當 WordPress 執行到頁尾時，就會乖乖地把這段程式碼印出來。

資料的加工廠：Filter Hooks (修改某個值)

如果說 Action 是廣播站，那 Filter Hook 就是一個「加工廠」或「攔截點」。它的邏輯是：「當我有個資料準備要被使用前，我先把它交給你，看你要不要『修改』它。修改完之後，請務必還給我，我好繼續接下來的工序。」

舉個例子，當 WordPress 準備要顯示一篇文章內容時，它會先把文章內容（一個長長的字串）通過一個叫做 `the_content` 的 Filter。你可以寫一個函式，用 `add_filter()` 告訴 WordPress：「嘿！`the_content` 的資料先別急著印出來，先拿來給我，我要在文章後面加個簽名檔，加完再還你。」

• 核心功能：接收一個值，對它進行修改，然後回傳它。
• 關鍵字：修改 (Modify)、過濾 (Filter)、更改 (Change)。
• 返回值：它「必須」回傳一個值！ 這點超級重要，我得講三次。你把資料拿去加工，最後一定要把成品（即使沒做任何修改，也要把原來的還回去）交回來，不然流水線到你這邊就斷了！

實戰演練：在每篇文章結尾自動加上作者版權宣告

這是一個非常常見的需求，我們可以用 `the_content` 這個 Filter Hook 輕鬆達成。

同樣在 `functions.php` 檔案中，加入以下程式碼：

<?php
// 將我們的函式掛到 'the_content' 這個 filter hook 上
add_filter( 'the_content', 'roamer_add_signature_to_content' );

function roamer_add_signature_to_content( $content ) {
    // 我們只希望在文章頁面（非首頁、彙整頁）加上簽名檔
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $signature = '<hr><p><em>本文由浪花科技 Eric 撰寫，轉載請註明出處。</em></p>';
        // 將簽名檔附加到原始內容的後面
        return $content . $signature;
    }

    // 如果不是文章頁，務必將原始內容原封不動地回傳！
    return $content;
}
?>

注意到了嗎？我們的函式接收了一個參數 `$content`，這就是 WordPress 遞過來的原始文章內容。我們加工完（或是不加工），最後都一定要 `return $content;`。如果你忘了這行 `return`，會發生什麼事？你的文章內容會直接變成空白！這可是新手最常踩的坑，沒有之一！忘了 `return`，你的資料就石沉大海，畫面直接空白，這種災難一次就夠了。

終極對決：Action vs. Filter 一張圖看懂差異

好了，理論跟實作都講了，我們來做個總結。如果你還是有點模糊，下面這個表格應該可以幫助你釐清所有觀念。

Action Hook 與 Filter Hook 核心差異

• 目的：
  • Action：執行一個動作 (Side Effect)，例如發送 email、寫入 log、輸出 HTML。
  • Filter：修改一個資料 (Data Transformation)，例如更改文字、增減陣列元素。
• 參數：
  • Action：可以接收參數（例如文章 ID），但主要是作為執行動作的參考資訊。
  • Filter：第一個參數必定是「要被過濾的資料」，後續可以有其他參考資訊。
• 回傳值：
  • Action：不需要回傳任何值。
  • Filter：必須回傳修改後（或原始）的資料。
• 核心函式：
  • Action：`add_action()` / `do_action()`
  • Filter：`add_filter()` / `apply_filters()`
• 生活化比喻：
  • Action：鬧鐘響了（事件發生），你起床刷牙（執行動作）。
  • Filter：你拿到一杯白開水（原始資料），你加入檸檬片（修改），變成一杯檸檬水（回傳修改後的資料）。

進階課題：如何像個專家一樣使用 Hooks

搞懂了基本差異，你已經贏過 80% 的人了。但要成為真正的高手，你還需要知道這幾件事。

1. 控制執行順序：優先權 (Priority)

`add_action()` 和 `add_filter()` 其實還有第三個參數：`$priority`（優先權），它是一個數字，預設是 10。數字越小，你的函式就越早被執行。

這在多個函式掛在同一個 hook 上時非常重要。例如，有兩個函式都掛在 `wp_footer`，一個 priority 是 10，一個是 20，那 priority 10 的會先執行。

// 這個會先執行
add_action( 'wp_footer', 'my_first_function', 10 );

// 這個會後執行
add_action( 'wp_footer', 'my_second_function', 20 );

2. 接收更多資訊：參數數量 (Accepted Args)

第四個參數是 `$accepted_args`，預設是 1。它決定你的函式要接收幾個從 hook 傳來的參數。

有些 hook 會提供多個參考資訊，例如 `save_post` 這個 Action Hook，除了文章 ID，還會傳遞整個文章物件 `WP_Post`。如果你想用到它，就必須把 `$accepted_args` 設為 2 (或更多)。

// 告訴 WordPress 我的函式要接收 2 個參數
add_action( 'save_post', 'my_save_post_function', 10, 2 );

function my_save_post_function( $post_id, $post ) {
    // 這裡就可以同時使用 $post_id 和 $post 物件了
}

3. 如何尋找可用的 Hooks？工程師的偵探技巧

你可能會問：「Eric，你怎麼知道有 `wp_footer`、`the_content` 這些鉤子？」

• 官方文件：WordPress Code Reference 是你的好朋友，所有核心的 Hooks 都有詳細說明。
• 直接看原始碼：這最直接，也是最硬核的方式。在 WordPress 核心或外掛程式碼中搜尋 `do_action(` 和 `apply_filters(`，就能找到所有可用的鉤子。
• 使用外掛：像 Query Monitor 這種開發者工具，可以幫你列出當前頁面執行了哪些 Hooks，非常方便。

結語：Hooks 是你通往 WordPress 大師的鑰匙

看到這裡，相信你對 WordPress Hook 與 Filter 差異與應用 已經有了非常深刻的理解。它們是 WordPress 最偉大的設計之一，也是整個生態系如此靈活、強大的基石。

記住這個心法：

• 想在某個時間點「做」一件事，就用 Action。
• 想在某個資料被使用前「改」它一下，就用 Filter。

當你不再滿足於現成的外掛，想要打造真正符合需求的客製化功能時，熟練地運用 Action 和 Filter 將是你最強大的武器。這不只是寫寫程式碼，更是一種架構思維的體現。

如果你在 WordPress 開發上遇到了更複雜的挑戰，或是有客製化系統、API 串接的需求，不知道該如何下手？別擔心，浪花科技的團隊擁有多年的實戰經驗，能協助你打造高效、穩定且可擴展的 WordPress 解決方案。

推薦閱讀

• 解鎖 WordPress 的隱藏力量：functions.php 終極實戰指南，讓你的網站秒變客製化神器！
• 不只會用，更要會『造』！WordPress Hooks 終極實戰：從自訂 Action/Filter 到打造可擴展外掛架構
• 別再只會裝外掛！資深工程師手把手，帶你從零打造第一個 WordPress 神器

👉 歡迎點擊這裡，填寫表單與我們聯繫，讓我們一起聊聊你的專案，將你的想法變成現實！