wp-performance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Performance (backend-only)

WordPress后端性能优化（仅后端）

When to use

适用场景

Use this skill when:

a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls

This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.

在以下场景使用本技能：

WordPress站点/页面/接口响应缓慢（前端TTFB、后台、REST接口、WP-Cron）
你需要性能分析方案和工具推荐（WP-CLI profile/doctor、Query Monitor、Xdebug/XHProf、APMs）
你正在优化数据库查询、自动加载选项、对象缓存、Cron任务或远程HTTP调用

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

Inputs required

所需输入

Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
How to target the install:
- WP root
```
--path=<path>
```
- (multisite/site targeting)
```
--url=<url>
```
The performance symptom and scope:
- which URL/REST route/admin screen
- when it happens (always vs sporadic; logged-in vs logged-out)

环境与安全限制：开发/预发布/生产环境，任何限制条件（禁止写入操作、禁止安装插件）。
WordPress实例定位方式：
- WP根目录路径
```
--path=<path>
```
- （多站点/站点定位）
```
--url=<url>
```
性能问题症状与范围：
- 具体哪个URL/REST路由/后台页面
- 问题出现时机（持续出现还是偶发；登录状态还是未登录状态）

Procedure

操作步骤

0) Guardrails: measure first, avoid risky ops

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

Confirm whether you may run write operations (plugin installs, config changes, cache flush).
Pick a reproducible target (URL or REST route) and capture a baseline:
- TTFB/time with
```
curl
```
  if possible
- WP-CLI profiling if available

Read:

```
references/measurement.md
```

确认是否允许执行写入操作（安装插件、修改配置、刷新缓存）。
选择一个可复现的目标（URL或REST路由）并捕获基准数据：
- 若可能，使用
```
curl
```
  获取TTFB/响应时间
- 若可用，使用WP-CLI进行性能分析

参考文档：

```
references/measurement.md
```

1) Generate a backend-only performance report (deterministic)

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

Run:

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

This detects:

WP-CLI availability and core version
whether
```
wp doctor
```
/
```
wp profile
```
are available
autoloaded options size (if possible)
object-cache drop-in presence

执行命令：

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

该命令会检测：

WP-CLI的可用性及WordPress核心版本
```
wp doctor
```
/
```
wp profile
```
是否可用
自动加载选项的大小（若可能）
对象缓存drop-in是否存在

2) Fast wins: run diagnostics before deep profiling

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

If you have WP-CLI access, prefer:

```
wp doctor check
```

It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).

Read:

```
references/wp-cli-doctor.md
```

若你有权限使用WP-CLI，优先执行：

```
wp doctor check
```

它能发现常见的生产环境问题（自动加载数据膨胀、SAVEQUERIES/WP_DEBUG开启、插件数量、更新情况）。

参考文档：

```
references/wp-cli-doctor.md
```

3) Deep profiling (no browser required)

3) 深度性能分析（无需浏览器）

Preferred order:

```
wp profile stage
```
to see where time goes (bootstrap/main_query/template).
```
wp profile hook
```
(optionally with
```
--url=
```
) to find slow hooks/callbacks.
```
wp profile eval
```
for targeted code paths.

Read:

```
references/wp-cli-profile.md
```

推荐执行顺序：

```
wp profile stage
```
查看时间消耗分布（bootstrap/main_query/template阶段）。
```
wp profile hook
```
（可搭配
```
--url=
```
参数）找出缓慢的钩子/回调函数。
```
wp profile eval
```
针对特定代码路径进行分析。

参考文档：

```
references/wp-cli-profile.md
```

4) Query Monitor (backend-only usage)

4) Query Monitor（仅后端使用方式）

Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and

_envelope

responses:

Authenticate (nonce or Application Password).
Request REST responses and inspect headers (
```
x-qm-*
```
) and/or the
```
qm
```
property when using
```
?_envelope
```
.

Read:

```
references/query-monitor-headless.md
```

Query Monitor通常是UI驱动的，但也可以通过REST API响应头和

_envelope

响应进行无界面使用：

进行身份验证（nonce或应用密码）。
请求REST响应并检查响应头（
```
x-qm-*
```
），或在使用
```
?_envelope
```
参数时查看
```
qm
```
属性。

参考文档：

```
references/query-monitor-headless.md
```

5) Fix by category (choose the dominant bottleneck)

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

Use the profile output to pick one primary bottleneck category:

DB queries → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
- ```
references/database.md
```
Autoloaded options → identify the biggest autoloaded options and stop autoloading large blobs.
- ```
references/autoload-options.md
```
Object cache misses → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
- ```
references/object-cache.md
```
Remote HTTP calls → add timeouts, caching, batching; avoid calling remote APIs on every request.
- ```
references/http-api.md
```
Cron → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
- ```
references/cron.md
```

根据性能分析结果选择一个主要瓶颈类别进行修复：

数据库查询 → 减少查询次数，修复N+1查询问题，优化索引，避免昂贵的元查询。
- 参考文档：
```
references/database.md
```
自动加载选项 → 找出体积最大的自动加载选项，停止自动加载大体积数据块。
- 参考文档：
```
references/autoload-options.md
```
对象缓存未命中 → 引入缓存或修复缓存键/分组的使用；在合适的场景添加持久化对象缓存。
- 参考文档：
```
references/object-cache.md
```
远程HTTP调用 → 添加超时设置、缓存、批量处理；避免在每次请求时都调用远程API。
- 参考文档：
```
references/http-api.md
```
Cron任务 → 减少即时触发的任务峰值，去重事件，将重负载任务移出请求处理路径。
- 参考文档：
```
references/cron.md
```

6) Verify (repeat the same measurement)

6) 验证（重复相同度量操作）

Re-run the same
```
wp profile
```
/
```
wp doctor
```
/ REST request.
Confirm the performance delta and that behavior is unchanged.
If the fix is risky, ship behind a feature flag or staged rollout when possible.

重新运行相同的
```
wp profile
```
/
```
wp doctor
```
/ REST请求。
确认性能提升，且功能行为未发生变化。
若修复操作存在风险，尽可能通过功能标志或分阶段发布来部署。

WordPress 6.9 performance improvements

WordPress 6.9性能改进

Be aware of these 6.9 changes when profiling:

On-demand CSS for classic themes:

Classic themes now get on-demand CSS loading (previously only block themes had this).
Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
If you're profiling a classic theme, this should already be helping.

Block themes with no render-blocking resources:

Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
Styles come from global styles (theme.json) and separate block styles, all inlined.
This significantly improves LCP (Largest Contentful Paint).

Inline CSS limit increased:

The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.

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

在进行性能分析时，请注意WordPress 6.9的以下变化：

经典主题的按需加载CSS：

经典主题现在支持按需加载CSS（此前仅区块主题支持该功能）。
通过仅加载页面实际使用的区块样式，将CSS体积减少30-65%。
若你正在分析经典主题的性能，该功能应该已经在发挥作用。

无渲染阻塞资源的区块主题：

未定义自定义样式表的区块主题（如Twenty Twenty-Three/Four）现在可以实现零渲染阻塞CSS加载。
样式来自全局样式（theme.json）和独立的区块样式，全部内联到页面中。
这显著提升了LCP（最大内容绘制）指标。

内联CSS限制提高：

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

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

Verification

验证标准

Baseline vs after numbers are captured (same environment, same URL/route).
```
wp doctor check
```
is clean (or improved) when applicable.
No new PHP errors or warnings in logs.
No cache flush is required for correctness (cache flush should be last resort).

已捕获基准数据与优化后的对比数据（相同环境、相同URL/路由）。
适用时，
```
wp doctor check
```
结果无问题（或得到改善）。
日志中无新增PHP错误或警告。
无需刷新缓存即可保证功能正确性（刷新缓存应作为最后手段）。

Failure modes / debugging

故障模式与调试

“No change” after code changes:
- you measured a different URL/site (
```
--url
```
  mismatch), caches masked results, or opcode cache is stale
Profiling data is noisy:
- eliminate background tasks, test with warmed caches, run multiple samples
```
SAVEQUERIES
```
/Query Monitor causes overhead:
- don’t run in production unless explicitly approved

代码修改后‘无变化’：
- 你度量的是不同的URL/站点（
```
--url
```
  参数不匹配），缓存掩盖了结果，或者操作码缓存已过期
性能分析数据噪音大：
- 消除后台任务，在缓存预热后测试，运行多次采样
```
SAVEQUERIES
```
/Query Monitor导致性能开销：
- 除非明确获批，否则不要在生产环境中运行

Escalation

升级处理

If this is production and you don’t have explicit approval, do not:
- install plugins, enable
```
SAVEQUERIES
```
  , run load tests, or flush caches during traffic
If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

若处于生产环境且未获得明确批准，请勿执行以下操作：
- 安装插件、开启
```
SAVEQUERIES
```
  、运行负载测试，或在流量高峰时刷新缓存
若需要系统级性能分析（APM、PHP分析器扩展），请与运维/主机服务商协调。