Performance Optimization Zh

---
name: performance-optimization-zh
description: 性能优化、先测量再优化、Core Web Vitals、N+1 查询、索引与执行计划、连接池、缓存设计、包体积、React 重渲染、回归防护。当用户说「页面太慢」「接口 P95 太高」「LCP 不达标」「这个查询要不要加索引」「连接池耗尽」「要不要加缓存」「怎么防性能回退」时使用。流程：测量（合成 + 真实用户）→ 按症状树定位瓶颈 → 修常见反模式（N+1、无界抓取、索引不匹配查询形状、连接池、图片、重渲染、包体积、缓存的层/键/失效/雪崩）→ 验证（同法重测、一次一改、超过噪声才算；中性即回退；记录所有尝试含回退的）→ 守护（CI 预算 + 真实用户监控）。也覆盖「系统地优化」「加个索引就行」「所有端点一起变慢」这类说法。改编自 addyosmani/agent-skills 的 performance-optimization（MIT）。
author: Captain
version: 0.1.1
display_name: "性能优化（先测量再优化）"
display_name_en: "Performance Optimization (zh)"
description_zh: "测量→定位→修→验证→守护：Web Vitals 目标、症状树、N+1/索引形状/连接池/缓存键与雪崩/包体积/重渲染的修法；中性改动一律回退并记录尝试台账。"
description_en: "Measure → identify → fix → verify → guard: Web Vitals targets, a symptom tree, fixes for N+1, index shape, pool exhaustion, cache keys and stampedes, bundles and re-renders; neutral changes are reverted and every attempt is logged."
tags:
  - "性能优化"
  - "performance"
  - "Core Web Vitals"
  - "N+1"
  - "缓存"
  - "索引优化"
examples_zh:
  - "首页 LCP 4 秒，帮我系统地优化"
  - "这个查询慢，是不是加个索引就行"
  - "接口在高峰期所有端点一起变慢，怎么查"
examples_en:
  - "Homepage LCP is 4s, optimize it systematically"
  - "This query is slow, should I just add an index"
  - "All endpoints slow down together at peak, how do I investigate"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "⚡" } }
---

# 性能优化（先测量再优化）

没有测量的性能工作是猜，猜会变成过早优化——加复杂度却不改善要紧的东西。先剖析、找真瓶颈、修、再测；只优化测量证明重要的部分。没有问题证据之前不要优化。

## 何时用
页面或接口有具体变慢的症状（LCP/INP 不达标、P95 涨了、查询变慢、高峰期集体变慢）时用；没有测量数据、只是「感觉可能慢」时，先测量拿到数字再回来。不用于没有症状的预防性调优——那是过早优化。

## Core Web Vitals 目标
LCP ≤ 2.5s 好 / ≤ 4.0s 需改进 / > 4.0s 差；INP ≤ 200ms / ≤ 500ms / > 500ms；CLS ≤ 0.1 / ≤ 0.25 / > 0.25。

## 工作流：测量 → 定位 → 修 → 验证 → 守护

### 1. 测量
两条腿都要：**合成**（Lighthouse、DevTools Performance、可复现，适合 CI 回归与隔离问题）与 **RUM**（web-vitals 库、CrUX，真实用户真实条件，验证修复是否真的改善体验的唯一依据）。后端：响应时间日志、APM、带耗时的查询日志、简单计时。
**按症状决定先测什么**：首屏慢 → 包大？服务端响应慢（TTFB：DNS → preconnect；TCP/TLS → HTTP/2、边缘、keep-alive；服务端等待 → 剖析后端查询与缓存）？渲染阻塞资源？交互卡 → 主线程长任务 > 50ms、受控组件重渲染、布局抖动；导航后慢 → API 瀑布、客户端渲染 N+1 抓取；后端 → 单端点慢查查询与索引、全端点慢查连接池/内存/CPU、间歇慢查锁竞争/GC/外部依赖。

### 2. 定位瓶颈
前端：LCP 慢 ← 大图、阻塞资源、慢服务端；CLS 高 ← 无尺寸图片、晚加载内容、字体换行；INP 差 ← 主线程重 JS、大 DOM 更新；首载慢 ← 大包、请求多。后端：接口慢 ← N+1、缺索引、烂查询；内存涨 ← 泄漏引用、无界缓存、大载荷；CPU 尖峰 ← 同步重计算、正则回溯；高时延 ← 缺缓存、重复计算、网络跳数。

### 3. 修常见反模式
- **N+1**：循环里逐条查关联 → 一次带 include/join 的查询。**无界抓取**：取全表 → 分页 + 排序 + 上限。
- **查询没用上索引**："加索引"是猜，执行计划是测量：`EXPLAIN ANALYZE`。看三样：大表 Seq Scan 而你期望走索引 → 没有可用索引；估计行数与实际差一个数量级 → 统计信息陈旧；扫描之上有 Sort 节点 → 索引覆盖了过滤没覆盖 ORDER BY。**按查询形状建索引**，复合索引等值列在前、范围/排序列在后。索引无效的情况：低选择性查主流值（95% 是 active 就查 active，顺序扫描更便宜；查稀有值用部分索引）；前导通配 `LIKE '%x'`（要 trigram/全文）；列上套函数（要表达式索引）；写多的表（每个索引都是每次写的税）。加完再跑 EXPLAIN，计划没变就回退——它仍在每次写时收费。
- **连接池耗尽**：特征是**所有**端点同时变慢、慢在等连接而不是执行、数据库显示多数会话空闲。修法：每进程一个池、按数据库上限定大小、连接超时快速失败；**更大不是更快**——池超过数据库并发执行能力只是把队列挪到更看不见的地方；实例数无界（无服务器/自动扩缩）时用连接复用代理（pgbouncer / RDS Proxy）而不是调大 max。
- **图片**：写宽高、首屏 LCP 图 `fetchpriority=high` + picture/srcset 做艺术方向与分辨率切换、AVIF/WebP；首屏外 `loading=lazy decoding=async`。
- **React 重渲染**：渲染中新建对象导致子组件重渲染 → 稳定引用；昂贵组件 memo；昂贵计算 useMemo；到处 memo 和到处不 memo一样糟。
- **包体积**：现代打包器对 ESM + `sideEffects:false` 的依赖自动摇树，改 import 风格前先剖析；真正的收益来自路由级代码分割与懒加载。
- **缓存**：只缓存生产贵且读远多于改的东西；缓存本来就快的查询只多了网络跳、陈旧 bug 和淘汰策略。**选层**：进程内（单实例、小而热、各实例独立漂移）/ 共享（Redis，多实例一致，多一个服务）/ CDN（公开且按 URL 相同，失效最难）。**键决定正确性**：影响响应的每个输入（租户、语言、权限、开关）都进键，漏了查看者就是把一个用户的数据端给另一个。**失效策略选一种**：TTL（接受陈旧窗口并明说）/ 事件或标签（写时新鲜但写方要知道缓存拓扑）/ 版本键（永不失效只换键，占内存到淘汰）。**防雪崩**：热键过期时并发请求一起穿透，源站瞬间满载——stale-while-revalidate 或把并发 miss 合并到一个在途请求。**不缓存**：陈旧即错的数据（余额、权限、结账库存）、未含用户标识的键下的用户数据。

### 4. 验证：保留还是回退
修复在重测前只是假设。**同法重测**：同命令、同条件、同预算（冷缓存基线对热缓存结果测的是缓存不是你的改动）。**一次一改**：三项优化一起上只得一个数字，无法归因。**超过噪声不只是均值**：±5% 噪声里的 3% 不是收益。决定：超过阈值且测试绿 → 保留并把前后数字写进提交；噪声内 → **回退**；更差 → 回退；改善但测试红 → 回退（披着收益外衣的回归）。**中性是回退不是保留**——已经写好了扔掉觉得可惜，于是未测量就落地，代码库积累永远不买单的复杂度。**正确性门控指标**：靠删掉产品需要的工作赢来的（跳过校验、缓存必须新鲜的东西、去掉承重的 await）是回归。
**记录每次尝试，含回退的**：回退的工作在 git 里没痕迹，所以同一个死主意下季度又被试一遍。留一张台账（想法 / 基线→结果 / 保留或回退 / 原因），放 PR 描述或 `PERF.md`。

### 5. 守护回归
守用户真正感受的那个指标（LCP、INP、p95），两层：**CI 合成预算**（重复噪声测量或比中位数/趋势，别让门禁变抖动检查）；**真实用户监控**（RUM p75 有意义的移动就告警，用带归因的 web-vitals 定位）。触发就回到第 1 步重建基线。预算示例：JS 首载 < 200KB gzip、CSS < 50KB、首屏图 < 200KB、API p95 < 200ms、TTI < 3.5s（4G）、Lighthouse ≥ 90；CI 里跑 bundlesize 与 Lighthouse CI。

## 合理化借口对照

| 借口 | 现实 |
|---|---|
| "以后再优化" | 性能债复利；现在修明显的反模式，推迟微优化 |
| "我机器上很快" | 你的机器不是用户的；在代表性硬件与网络上剖析 |
| "这个优化很明显" | 没测量就不知道；先剖析 |
| "用户感觉不到 100ms" | 研究表明 100ms 影响转化 |
| "框架处理了性能" | 框架防不了 N+1 和大包 |
| "查询慢，加索引" | 先读计划；索引可能存在但用不上，而且每个索引永远向写收税 |
| "加个缓存" | 缓存便宜的调用一无所获还添陈旧 bug |
| "连接不够，把池调大" | 比数据库能服务的更大的池只是把队列挪到看不见的地方 |
| "没帮多少但也不坏" | 中性改动是回退；你永远为它付维护费 |
| "都写好了，留着吧" | 沉没成本；测量不在乎你花了多久 |
| "改善很明显，不用重测" | 那重测很便宜且能证明；未测量的收益就是中性复杂度落地的方式 |

## 红灯
没有剖析数据的优化；N+1；加索引没有前后执行计划；缓存键漏了响应依赖的输入；缓存没有陈旧窗口与失效策略；耗尽就调大池而不找谁占着连接；列表无分页；图片无尺寸/懒加载/响应式；包体积无人评审地增长；生产无性能监控；到处 memo；未重测就保留的优化；多项优化捆成一次测量；靠改/跳/删测试赢来的"收益"；同一个失败的优化被重复尝试因为没人记录。

## 验收
```
- [ ] 有前后具体数字　- [ ] 与基线同法重测　- [ ] 改善超过运行间方差　- [ ] 没打败基线的已回退　- [ ] 尝试台账含回退项
- [ ] 具体瓶颈已识别处理　- [ ] Web Vitals 在"好"区间　- [ ] 包体积未明显增长　- [ ] 新代码无 N+1　- [ ] 新索引有前后计划且考虑写成本
- [ ] 新缓存写明键与失效　- [ ] 该指标有 CI 预算或真实用户监控　- [ ] 现有测试通过
```

---
改编自 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) 的 `performance-optimization`（MIT）。改动见 ATTRIBUTION.md。