开发工作流与调试

这一课你将能做到

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' ),
    ) );
} );

版本号用 filemtime（文件修改时间），改文件缓存立刻失效——比手写 '1.0.0' 聪明。

步骤 5：规范检查（phpcs）

composer require --dev wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer
./vendor/bin/phpcs --standard=WordPress --extensions=php src/ -n

-n 先屏蔽 warning，把 error 清零再逐步收紧。团队协作时把这条命令放进 pre-commit。

步骤 6：打包交付

npm run build                 # 区块/插件前端产物
zip -r qrocmq-toolkit.zip qrocmq-toolkit/ -x "*/node_modules/*" "*/.git/*" "*/src/*"

把 zip 装进另一个干净环境验证——「本地能跑」和「装得进别人的站」是两回事。

讲清楚要点

1. enqueue 体系解决三件事：去重（同句柄只加载一次）、依赖（先 React 后你的代码）、缓存失效（$ver 参数拼在 URL 上）。
2. SCRIPT_DEBUG 的价值：WP 核心与大部分库有未压缩版本，压缩后断点全是乱码——调试前端必开。
3. SAVEQUERIES 有代价：它把每条 SQL 存进内存，生产绝不能开；Query Monitor 的查询面板依赖它。
4. wp-env vs Local 的分工：wp-env 面向插件/区块开发（可脚本化、CI 可用）；Local 面向整站体验（图形化、邮件捕获、一键克隆）。
5. 规范即协作成本：WPCS（WordPress Coding Standards）规定了缩进、Yoda 条件、命名等，phpcs 自动化执行，Code Review 少一半争吵。

你可能会懵的地方

• 为什么不能在 header.php 里直接写 <script> 标签？ 失去去重与依赖管理，可能被加载两次或早于依赖；也无法利用 defer/strategy 与版本参数。

• wp_localize_script 和直接 echo JSON 有什么区别？ 前者把数据转成合法 JS 对象注入页面，自动处理转义；手工 echo 极易造成 XSS 与语法错误。

• phpcs 报了几百个错，正常吗？ 正常。它按核心规范全量扫描，先处理 error、忽略 warning，历史代码逐步收敛。

• debug.log 不生成？ 检查三点：三个常量是否都定义、wp-content 目录可写、配置写在 /* That's all... */ 停止注释之前。

• 改了不生效，到底清哪层缓存？ 按顺序排查：浏览器强刷 → 页面缓存（插件/CDN）→ 对象缓存 → OPcache。第 11 课有完整方法论。

错法对照

错法	问题	正解
版本号写死 '1.0' 不更新	用户浏览器缓存旧文件	filemtime 或构建 hash 作 $ver
生产环境开 SAVEQUERIES	内存暴涨、页面变慢	仅本地调试使用
把 node_modules 打进插件包	包巨大且可能带恶意脚本	打包时排除，只带 build/dist
在 wp_head 直接 echo 样式	顺序失控、无法去重	统一走 wp_enqueue_style
WP_DEBUG 开着发版	泄露路径与配置	上线前关闭，留日志与监控

卡点急救

1. wp-env start 失败：确认 Docker Desktop 在运行、8888/8889 端口空闲；首次要拉镜像，网络需畅通。
2. Query Monitor 不显示：检查是否以管理员登录、主题是否调用了 wp_footer（区块主题自动有）。
3. phpcs 报 command not found：用项目内 ./vendor/bin/phpcs，别依赖全局安装。

面试常问

• 生产环境出白屏，你的排查步骤？ 先看 PHP 错误日志与 wp-content/debug.log 定位文件行号；回滚最近变更；无日志则临时开 WP_DEBUG_LOG 收集；同时检查最近升级的核心/插件与内存限制。

• wp_enqueue 体系解决了哪些问题？ 依赖顺序、去重、版本化缓存失效、位置（头/尾）、以及 localize 向前端安全传数据。

• WP 有哪些主要调试常量？ WP_DEBUG 总开关、WP_DEBUG_LOG 日志、WP_DEBUG_DISPLAY 屏显、SCRIPT_DEBUG 未压缩资源、SAVEQUERIES 记录 SQL——前三管 PHP 后两管前端/性能。

自测三问

1. wp_enqueue_script 的第 4、5 个参数分别是什么？$ver 的作用机制？
2. SCRIPT_DEBUG 和 SAVEQUERIES 各解决什么问题，为什么不能上生产？
3. Query Monitor 的哪个面板能确认「钩子是否注册、优先级是否冲突」？

小结一句话

wp-env 让环境一条命令起步，三大调试常量 + Query Monitor 让问题无处遁形，enqueue 体系与 phpcs 让代码装得快、跑得稳——工作流的工业化，是个人项目与专业交付的分界线。

延伸

• wp-env 官方文档
• WP 调试官方指南
• 下一课：WordPress 里的 PHP——The Loop、条件标签与次级查询的正确姿势。