wp-performance

WP 性能（仅后端）

适用场景

在以下情况使用此技能：

• WordPress 网站、页面或端点响应缓慢（前端 TTFB、管理后台、REST、WP-Cron）
• 需要制定性能分析计划并获得工具建议（WP-CLI profile/doctor、Query Monitor、Xdebug/XHProf、APM）
• 需要优化数据库查询、自动加载的选项、对象缓存、定时任务或远程 HTTP 调用

此技能假设 Agent 无法使用浏览器 UI。优先使用 WP-CLI、日志和 HTTP 请求。

所需输入

• 环境和安全限制：开发、预发布或生产环境；是否有任何限制（禁止写入、禁止安装插件）。
• 如何定位安装：
  • WordPress 根目录 --path=<path>
  • （多站点／站点定位）--url=<url>
• 性能问题及范围：
  • 涉及的 URL、REST 路由或管理后台页面
  • 发生时间（始终发生还是偶发；已登录还是未登录）

流程

0) 安全守则：先测量，避免高风险操作

1. 确认是否允许执行写操作（安装插件、修改配置、清除缓存）。
2. 选择可复现的目标（URL 或 REST 路由），并记录基线：
   • 尽可能使用 curl 测量 TTFB／耗时
   • 如果可用，使用 WP-CLI 进行性能分析

阅读：

• references/measurement.md

1) 生成仅后端的性能报告（确定性）

运行：

• node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]

此脚本会检测：

• WP-CLI 是否可用，以及核心版本
• wp doctor／wp profile 是否可用
• 自动加载的选项大小（如果可测量）
• 是否存在对象缓存 drop-in

2) 快速见效：深入分析前先运行诊断

如果可以使用 WP-CLI，优先运行：

• wp doctor check

它能发现常见的生产环境隐患（自动加载内容膨胀、SAVEQUERIES/WP_DEBUG、插件数量、更新）。

阅读：

• references/wp-cli-doctor.md

3) 深入分析（无需浏览器）

优先顺序：

1. 使用 wp profile stage 查看耗时分布（bootstrap/main_query/template）。
2. 使用 wp profile hook（可选添加 --url=）查找耗时较长的钩子／回调。
3. 使用 wp profile eval 分析目标代码路径。

阅读：

• references/wp-cli-profile.md

4) Query Monitor（仅后端使用）

Query Monitor 通常通过 UI 使用，但也可通过 REST API 响应头和 _envelope 响应进行无界面使用：

• 进行身份验证（nonce 或 Application Password）。
• 请求 REST 响应并检查响应头（x-qm-*），和／或使用 ?_envelope 时检查 qm 属性。

阅读：

• references/query-monitor-headless.md

5) 按类别修复（选择主要瓶颈）

根据性能分析结果，选择一个主要瓶颈类别：

• 数据库查询 → 减少查询次数、修复 N+1 模式、改进索引、避免代价高昂的元数据查询。
  • references/database.md
• 自动加载的选项 → 找出体积最大的自动加载选项，并停止自动加载大型数据块。
  • references/autoload-options.md
• 对象缓存未命中 → 引入缓存或修复缓存键／组的用法；酌情添加持久化对象缓存。
  • references/object-cache.md
• 远程 HTTP 调用 → 添加超时、缓存和批处理；避免每次请求都调用远程 API。
  • references/http-api.md
• 定时任务 → 减少到期任务集中触发造成的峰值、去重事件，并将繁重任务移出请求处理路径。
  • references/cron.md

6) 验证（重复相同的测量）

• 重新运行相同的 wp profile／wp doctor／REST 请求。
• 确认性能变化，并确保行为未改变。
• 如果修复风险较高，尽可能通过功能开关或分阶段发布来上线。

WordPress 6.9 性能改进

进行性能分析时，请注意 6.9 中的这些变更：

经典主题按需加载 CSS：

• 现在经典主题也支持按需加载 CSS（此前只有区块主题支持）。
• 仅加载页面上实际使用的区块样式，可减少 30-65% 的 CSS 资源。
• 如果你正在分析经典主题的性能，这项改进应该已经生效。

区块主题不再有阻塞渲染的资源：

• 不定义自定义样式表的区块主题（例如 Twenty Twenty-Three/Four）现在可以在没有任何阻塞渲染的 CSS 的情况下加载。
• 样式来自全局样式（theme.json）和单独的区块样式，并全部内联。
• 这能显著改善 LCP（最大内容绘制）。

提高内联 CSS 上限：

• 提高了内联小型样式表的阈值，减少了阻塞渲染的资源。

参考：https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/

验证

• 已记录基准数据与改进后的数据（环境和 URL/路由相同）。
• 适用时，wp doctor check 检查结果正常（或有所改善）。
• 日志中没有新增 PHP 错误或警告。
• 正确性不依赖清理缓存（清理缓存应作为最后手段）。

故障情形／调试

• 修改代码后“没有变化”：
  • 测量的是其他 URL/站点（--url 不匹配）、缓存掩盖了结果，或操作码缓存已过期
• 性能分析数据波动较大：
  • 排除后台任务的干扰，使用预热后的缓存进行测试，并运行多次采样
• SAVEQUERIES/Query Monitor 会带来额外开销：
  • 除非获得明确批准，否则不要在生产环境中运行

升级处理

• 如果这是生产环境，且你没有获得明确批准，请勿：
  • 安装插件、启用 SAVEQUERIES、运行负载测试，或在流量期间清理缓存
• 如果需要进行系统级性能分析（APM、PHP 性能分析扩展），请与运维／托管服务团队协调。