插件开发与 Hook 体系

这一课你将能做到

1. 从零写出规范插件骨架：主文件头注释、激活/停用/卸载钩子一个不缺
2. 区分 action 与 filter，用优先级和参数个数精准控制回调的执行顺序
3. 在文章保存、请求初始化等真实时机挂载自己的逻辑（如保存时自动打标签）

为什么要学

WordPress 的 80% 二次开发是通过 Hook（钩子）完成的：WP 在执行流程的关键节点「喊一声」，你的插件、主题响应它。不改核心、不碰模板，就能改变全站行为——这是 WP 生态繁荣的技术根基，也是面试必考题。

人话：把 WP 想象成流水线，Hook 是流水线上预留的插口。action 插口是「到这一步了，你去干件事」（发邮件、写日志）；filter 插口是「这个数据交给你加工，加工完必须还回来」（改标题、追加正文）。分不清这两点，插件开发寸步难行。

先建立图像

一次请求的执行顺序与主要插口：

请求进入
 → 加载 mu-plugins（必用插件，最先）
 → 按字母序加载 plugins            ← 你插件的 add_action 在这里注册
 → 加载主题 functions.php
 → plugins_loaded
 → init                           ← 常用：注册 CPT、_taxonomy
 → wp_loaded → 解析主查询
 → template_redirect / the_content(filter) / wp_enqueue_scripts
 → 渲染模板 → wp_footer → 输出

注册发生在「加载期」，执行发生在「运行期」——所以你可以在 init 之前安全地 add_action，但很多 WP 函数要等 init 之后才能用。

跟着做

步骤 1：插件骨架

wp-content/plugins/qrocmq-toolkit/ 下新建主文件 qrocmq-toolkit.php：

<?php
/**
 * Plugin Name:       QROCMQ Toolkit
 * Description:       课程站工具：保存文章自动追加来源说明。
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      8.2
 * Author:            qrocmq
 * Text Domain:       qrocmq-toolkit
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // 防止直接访问
}

保存后后台「插件」页应出现它——头注释就是插件的身份证明。ABSPATH 检查是安全底线。

步骤 2：第一个 action

在骨架下方追加：

add_action( 'admin_notices', function () {
    echo '<div class="notice notice-info"><p>QROCMQ Toolkit 已启用</p></div>';
} );

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'qrocmq-toolkit',
        plugin_dir_url( __FILE__ ) . 'assets/main.css',
        array(),
        '1.0.0'
    );
} );

激活插件，后台顶部出现提示条——你的第一段代码已进入 WP 执行流程。

步骤 3：filter 实战：改内容必须还数据

add_filter( 'the_content', function ( string $content ): string {
    if ( is_singular( 'post' ) ) {
        $content .= '<p class="source-note">本文首发于 QROCMQ 课程站</p>';
    }
    return $content;   // filter 的铁律：必须 return
}, 20 );               // 优先级 20：晚于默认的 10 执行

add_filter( 'the_title', function ( string $title, int $post_id ): string {
    return is_admin() ? $title : $title . '｜课程笔记';
}, 10, 2 );            // 第三个参数：接收 2 个参数