fox-optimize

Fox Optimize 🦊

狐狸不会笨重地穿过森林。它行动迅捷精准，在树木之间找出最快的路径。有什么拖慢了狩猎，它会立刻察觉。它悄然追踪问题，将其隔离，然后出击。狐狸经过后，森林的运转更加顺畅。

何时启用

• 用户要求“优化一下”或“让它更快”
• 用户说“它很慢”或“有性能问题”
• 用户调用 /fox-optimize 或提到 fox/性能
• 页面加载时间无法接受
• 数据库查询缓慢
• 包体积过大
• 检测到内存泄漏
• 动画卡顿
• API 响应时间过长

搭配使用： bloodhound-scout，用于查找运行缓慢的代码路径

---

狩猎

STALK → PINPOINT → STREAMLINE → CATCH → CELEBRATE
   ↓         ↲           ↲           ↓          ↓
Watch for  Find the    Optimize   Capture   Enjoy the
Slowness   Bottleneck  Hot Paths  Gains     Win

阶段 1：潜行

狐狸悄无声息地靠近，观察哪些地方行动太慢……

在修改任何内容之前，先建立基线指标。

• 确定感觉缓慢的环节：首次加载、交互、滚动、数据加载，还是过渡效果？
• 使用合适的工具进行测量——用 Lighthouse 测量页面核心指标，用包可视化工具检查体积，用 DevTools 检查 CPU/内存
• 设定目标指标和基线，以便进行对比

参考： 加载 references/measurement-tools.md，查看 Lighthouse 命令、包分析配置、数据库查询分析、DevTools 指南和性能目标值

脚本： 运行 scripts/measure-bundle.sh，记录所有应用的基线包体积。优化后再次运行，即可自动对比前后结果。

参考： 加载 references/performance-toolkit.md，查看 Grove 专用测量命令——跨全部 3 个数据库进行 D1 查询分析、KV 缓存模式、Workers 专用并行化方法，以及性能报告模板

输出： 定义基线指标和目标

---

阶段 2：精确定位

耳朵竖起。狐狸精确找出猎物藏身之处……

通过证据找出具体的瓶颈。

• 服务端生命周期：检查 hooks/middleware 是否存在顺序等待、Promise.all 批处理、跳过条件不满足的工作、边缘缓存标头、DO 冷启动
• 前端：检查长任务、布局抖动、阻塞式 JS、未优化的图片、大型包
• 数据库：运行 EXPLAIN QUERY PLAN，检查是否使用 SCAN 而不是 SEARCH，识别 N+1 模式
• API：检查响应时间、并行化机会和缺失的缓存
• 内存：获取堆快照，对比用户操作前后的情况，检查堆是否持续增长

80/20 法则：在 SSR 应用中，先检查 TTFB——如果服务端很慢，客户端优化也无济于事。然后检查图片、索引、缓存和 JS 包体积。

参考： 加载 references/optimization-patterns.md，查看诊断决策树——它会根据症状列出可能的原因

输出： 通过证据确定具体瓶颈

---

阶段 3：精简优化

狐狸在灌木丛中找到最快的路径……

针对性地优化——修复瓶颈，而不是其他无关部分。

• 图片：转换为 WebP/AVIF，添加延迟加载，并为不同尺寸添加 srcset
• JS：拆分大型组件的代码，进行导入摇树优化，延迟加载首屏以下的内容
• 数据库：添加复合索引，通过联接修复 N+1 查询，并行执行相互独立的查询
• 缓存：使用 KV 缓存开销较大的读取，为静态资源添加 cache-control 标头
• 动画：仅使用 transform/opacity（由 GPU 合成），避免使用会触发布局的属性
• 内存：确保在 onDestroy 中进行清理，移除事件监听器

参考： 加载 references/optimization-patterns.md，查看所有优化模式的完整代码示例：图片、代码拆分、N+1 修复、并行查询、KV 缓存、记忆化、虚拟滚动、动画性能和内存泄漏修复

输出： 在尽量缩小改动范围的前提下完成优化

---

阶段 4：CATCH

狐狸猛地咬合双颚——速度已被捕获……

必须：确认优化没有造成问题：

pnpm install
gw ci --affected --fail-fast --diagnose

如果验证失败：狐狸跑得太快，弄坏了某些东西。阅读诊断信息，修复回归问题，然后重新运行验证。速度若无法保证正确性，就毫无价值。

CI 通过后，衡量改进效果：

lighthouse https://yoursite.com
npm run build && npm run analyze

记录优化前后的数据，以便撰写报告。

输出： 已记录的优化成果，并通过验证

---

阶段 5：CELEBRATE

狐狸欢快地叫了一声，狩猎圆满结束……

报告成果，防止性能回退。

• 撰写性能报告：目标、发现的瓶颈、实施的优化、优化前后的指标
• 在 CI 中添加性能预算，防止优化成果悄然消失
• 如果尚未启用 Real User Monitoring（RUM），请启用

输出： 已提交报告，并已设置监控

---

参考资料路由表

阶段	参考资料	加载时机
STALK	references/measurement-tools.md	始终加载（优化前必须先测量）
STALK	references/performance-toolkit.md	Grove 专用：D1 性能分析、KV 缓存、包体积跟踪
STALK	scripts/measure-bundle.sh	运行脚本，自动获取并比较包体积基线
PINPOINT	references/optimization-patterns.md	使用决策树找出原因
STREAMLINE	references/optimization-patterns.md	应用合适的修复模式
STREAMLINE	references/performance-toolkit.md	Grove 专用：Workers 并行化、缓存头
CELEBRATE	references/performance-toolkit.md	使用性能报告模板

---

狐狸守则

速度

狐狸行动迅速。别把几周时间花在微优化上。先找出收益最大的优化。

精准

针对实际瓶颈进行优化。先分析性能，再进行优化。不要猜测。

平衡

速度再快，功能坏了也毫无价值。每次优化后都要验证功能。

沟通

使用狩猎隐喻：

• “正在追踪缓慢路径……”（识别问题）
• “正在锁定猎物……”（找出瓶颈）
• “正在优化路线……”（进行优化）
• “已成功捕获……”（确认改进）

---

反模式

狐狸不会：

• 未经测量就进行优化
• 为了微小收益牺牲可读性
• 为了微不足道的改进增加复杂性
• 忘记在更改后进行测试
• 过早地优化所有内容

---

狩猎示例

用户：“仪表板加载很慢”

狐狸的流程：

1. 🦊 STALK — “测量结果：FCP 为 3.2s，LCP 为 5.1s。目标：FCP < 1.8s”

2. 🦊 PINPOINT — “Lighthouse：存在阻塞渲染的 JS、图片未优化且未启用缓存。数据库：获取组件数据时存在 N+1 查询。”

3. 🦊 STREAMLINE — “延迟加载非关键 JS，将图片转换为 WebP，添加数据库索引，并实现 KV 缓存”

4. 🦊 CATCH — “FCP：3.2s → 1.4s。LCP：5.1s → 2.2s。测试通过。”

5. 🦊 CELEBRATE — “已在 CI 中添加性能预算，并启用 RUM 监控”

---

快速决策指南

症状	可能原因	快速修复
TTFB 较高（>500ms）	hooks/middleware 中的 await 按顺序执行	使用 Promise.all 或 Promise 提前创建来实现并行处理
未登录用户也觉得慢	SSR 页面未启用边缘缓存	添加 Cache-Control + CDN-Cache-Control 请求头
仅登录后变慢	认证或功能相关的额外查询	为匿名访客跳过不必要的工作
首次请求非常慢	DO/Worker 冷启动	添加 keepalive 定时任务，并为配置提供 KV 回退
初始加载缓慢	JS 包体积过大	代码分割、摇树优化
图片加载缓慢	图片格式未优化	使用 WebP/AVIF、延迟加载
滚动卡顿	布局抖动	使用 transform，避免更改布局
API 响应缓慢	缺少数据库索引	添加索引并实现缓存
内存持续增长	事件监听器泄漏	在 onDestroy 中正确清理
交互缓慢	主线程阻塞	将工作移至 Web Worker

---

敏捷的狐狸把缓慢的森林抛在身后。 🦊