WordPress 動作鉤子詳解：add_action 與 do_action 完全指南

核心概念

WordPress 插件機制的核心是「鉤子系統」，分為動作與過濾器。本文專注於動作鉤子：

• add_action()：將回調函數掛載到指定動作點
• do_action()：在代碼中觸發動作點，執行所有掛載的回調

add_action() - 掛載動作

語法

add_action( string $hook, callable $function_to_add, int $priority = 10, int $accepted_args = 1 ): bool

參數詳解

返回值

始終返回 true。

實戰範例

1. 在 <head> 輸出 viewport meta 標籤

function my_theme_viewport_meta() {
    echo '<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0" />';
}
add_action('wp_head', 'my_theme_viewport_meta');

2. 文章發布後發送通知郵件（接收文章 ID）

function notify_on_publish(int $post_id) {
    $post = get_post($post_id);
    if ($post->post_status === 'publish') {
        wp_mail('admin@example.com', '新文章發布', $post->post_title);
    }
}
// save_post 動作傳遞 $post_id，$accepted_args 必須 >= 1
add_action('save_post', 'notify_on_publish', 10, 1);

3. 使用匿名函數與優先級控制順序

add_action('wp_footer', function() {
    echo '<!-- Footer injected at priority 5 -->';
}, 5); // 比默認 10 更早執行

do_action() - 觸發動作

語法

do_action( string $hook, mixed ...$args ): void

參數詳解

• $hook：動作名稱（必須與 add_action 的 $hook 一致）
• ...$args：任意數量參數，將透傳給所有掛載的回調函數

特點

• 無返回值：純粹觸發副作用（輸出、寫入、發送郵件等）
• 與 apply_filters() 的區別：apply_filters 有返回值，用於數據修改；do_action 無返回值，用於事件通知

實戰範例

1. 自定義動作點：主題模板加載前

// functions.php 或插件中定義
function my_theme_before_template() {
    do_action('my_theme_before_template', get_queried_object_id());
}

// 模板文件 page.php 頂部調用
my_theme_before_template();

2. 插件掛載自定義動作

add_action('my_theme_before_template', function($post_id) {
    // 記錄頁面瀏覽統計
    update_post_meta($post_id, 'view_count', get_post_meta($post_id, 'view_count', true) + 1);
}, 10, 1);

3. 核心動作點示例：init 初始化

// WordPress 核心在 wp-settings.php 中調用
do_action('init'); // 無參數

// 常見掛載：註冊自定義文章類型、分類法、腳本樣式
add_action('init', 'my_register_post_types');

常用核心動作鉤子速查表

最佳實踐與避坑指南

1. 優先級規劃：核心功能用 1-9，業務邏輯用 10-20，晚期修飾用 30+。避免極大數值（如 9999）導致難以調試。
2. 參數聲明：$accepted_args 必須 ≥ 實際使用的參數數，否則回調接收不到後續參數。
3. 命名空間：自定義鉤子建議加前綴 myplugin/action_name 防衝突。
4. 移除掛載：remove_action($hook, $function, $priority) 需精確匹配優先級。
5. 匿名函數無法移除：需移除時請使用具名函數或類靜態方法。
6. 不要在動作中直接輸出 HTML 除非是輸出類鉤子（如 wp_head），否則可能破壞 JSON/AJAX 響應。

文件位置

兩個函數均定義於 wp-includes/plugin.php，核心實現約 50 行，建議閱讀源碼深入理解 WP_Hook 類機制。