开发工作流与调试

这一课你将能做到

1. 用 @wordpress/env（wp-env）一键拉起「WP + MySQL + 测试环境」，并挂载你自己的插件目录
2. 打开标准调试组合（WP_DEBUG / SCRIPT_DEBUG / SAVEQUERIES），用 Query Monitor 定位慢查询与钩子问题
3. 用 wp_enqueue_* 规范加载脚本样式，并用 PHP_CodeSniffer 对齐 WordPress 编码规范

为什么要学

写代码只占开发的一半，另一半是「改得快、找得到错、发得出去」。WP 项目出问题最常见的死法：改了没反应（缓存）、报错看不见（调试没开）、样式互相覆盖（没走 enqueue 体系）。这一课把这三件事一次治好。

人话：wp-env 之于 WP，相当于你熟悉的 Docker Compose 之于 Spring Boot 项目——一条命令起全套环境，还专门针对插件/主题开发做了热更新。

先建立图像

开发闭环：

写代码(src) → wp-env 本地站即时预览 → Query Monitor 排错
   ↑                                        ↓
git 提交 ← phpcs 规范检查 ← npm run build(产物)
   ↓
打包 zip / git pull 到测试环境 → 验证 → 上生产

跟着做

步骤 1：wp-env 起环境

前置：Node 20+ 与 Docker Desktop。在你的插件项目根目录创建 .wp-env.json：

{
    "core": "WordPress/WordPress",
    "plugins": [ "." ],
    "themes": [ "./wp-content/themes/tt25-child" ],
    "config": {
        "WP_DEBUG": true,
        "WP_DEBUG_LOG": true,
        "WP_DEBUG_DISPLAY": false,
        "SCRIPT_DEBUG": true
    }
}

执行：

npx wp-env start

默认站点在 http://localhost:8888，后台 http://localhost:8888/wp-admin，账号密码均为 admin/password（仅本地）。你的插件目录已被挂载为已启用插件——改 PHP 保存即生效。

步骤 2：调试图鉴——三种问题的三种开关

在 wp-config.php（或上面 config 节点）中：

define( 'WP_DEBUG', true );          // PHP 报错进日志
define( 'WP_DEBUG_LOG', true );      // 落盘 wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // 不直接吐到页面
define( 'SCRIPT_DEBUG', true );      // 核心加载未压缩 JS/CSS，前端调试必开
define( 'SAVEQUERIES', true );       // 记录每条 SQL 与耗时（仅本地！）

对应关系：PHP 白屏看日志；JS 行为诡异开 SCRIPT_DEBUG；页面慢开 SAVEQUERIES + Query Monitor。

步骤 3：Query Monitor 排错三连

后台插件页搜索安装 Query Monitor 并启用。页脚出现图标后点开：

• Overview：当前页耗时、查询数、内存——性能基线
• Queries：慢 SQL 按耗时排序，能定位到调用栈（哪个函数查的）
• Hooks & Actions：列出全部注册回调与优先级——「钩子没执行」一查便知
• PHP Errors：警告、废弃函数及其来源插件

步骤 4：资源加载的正规军写法

主题 functions.php 或插件中：

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'qrocmq-main',
        plugin_dir_url( __FILE__ ) . 'assets/main.css',
        array(),                      // 依赖句柄
        filemtime( plugin_dir_path( __FILE__ ) . 'assets/main.css' ) // 内容指纹破缓存
    );
    wp_enqueue_script(
        'qrocmq-app',
        plugin_dir_url( __FILE__ ) . 'assets/app.js',
        array( 'wp-element' ),        // 依赖 Gutenberg 的 React
        '1.0.0',
        array( 'in_footer' => true, 'strategy' => 'defer' )
    );
    // 把 PHP 数据安全传给前端 JS
    wp_localize_script( 'qrocmq-app', 'QROCMQ_CFG', array(
        'restUrl'   => esc_url_raw( rest_url( 'qrocmq/v1' ) ),
        'nonce'     => wp_create_nonce( 'wp_rest' ),
    ) );
} );