Convex 性能审计

逐一诊断并修复Convex应用中的性能问题。

适用场景

Convex页面或功能运行缓慢或成本过高
```
npx convex insights --details
```
报告显示读取字节数、读取文档数或OCC冲突量较高
低实时性读取路径在可使用时点读取的场景下使用了响应式机制
出现OCC冲突错误或过度的突变重试
订阅数量过高或UI更新缓慢
函数即将达到执行或事务限制
多个同类函数存在相同的性能问题需要修复

不适用场景

Convex初始设置、认证设置或组件提取
无性能优化目标的纯Schema迁移
无用户可见或部署层面可见问题的一次性微优化

注意准则

在规模较小、流量适中或可用信号不足时，优先选择更简洁的代码
除非有可量化的信号、明确的无界路径或已知的热点读/写路径，否则不建议使用摘要表、文档拆分、获取策略变更或涉及大量迁移的部署方案
在Convex中，对小型表执行简单扫描通常是可接受的。不要仅仅因为某种模式在大规模场景下不够理想就进行结构性改造

第一步：收集数据信号

从最可靠的可用信号开始：

如果用户或当前环境已提供部署健康洞察数据，将其作为首要的性能信号来源。
如果可以使用CLI洞察工具，运行
```
npx convex insights --details
```
。必要时使用
```
--prod
```
、
```
--preview-name
```
或
```
--deployment-name
```
参数。
- 如果本地仓库的Convex CLI版本过旧不支持
```
insights
```
  命令，先尝试运行
```
npx -y convex@latest insights --details
```
  再考虑放弃。
如果仓库已使用
```
convex-doctor
```
，可将其结果作为参考，但不强制要求，也不将其视为绝对权威。
如果无法获取运行时信号，仍可通过代码审计进行检查，但需牢记上述注意准则。缺乏洞察数据不代表系统健康，也不意味着需要进行大规模重构。

信号匹配

收集信号后，确定问题类别并阅读对应的参考文档。

信号	参考文档
读取字节数或文档数过高、JS端过滤、不必要的关联查询	`references/hot-path-rules.md`
OCC冲突错误、写入冲突、突变重试	`references/occ-conflicts.md`
订阅数量过高、UI更新缓慢、过度重渲染	`references/subscription-cost.md`
函数超时、事务大小错误、大负载	`references/function-budget.md`
仅反馈“运行缓慢”无具体信号	从 `references/hot-path-rules.md` 开始排查

多个问题类别可能存在重叠。先阅读最相关的参考文档，若症状仍存在，再检查其他文档。

重大修复需确认

如果可能的修复方案具有侵入性、跨模块或涉及大量迁移，需先停止操作并给出可选方案，再进行编辑。

示例：

在多个流程中引入摘要表或汇总表
拆分文档以隔离频繁更新的字段
重写多个页面的分页或获取策略
切换到需要迁移安全部署的新索引或非规范化字段

当正确性依赖于部署过程中对新旧状态的处理时，请参考

skills/convex-migration-helper/SKILL.md

中的迁移流程。

工作流程

1. 界定问题范围

从实际项目中选取一个具体的用户流程。查看代码库、客户端页面和API接口，找到与症状匹配的流程。

记录：

入口函数
使用
```
useQuery
```
、
```
usePaginatedQuery
```
或
```
useMutation
```
的客户端调用点
读取的表
写入的表
该路径属于高读取、高写入还是两者兼具

2. 追踪完整的读写集合

针对路径中的每个函数：

追踪所有
```
ctx.db.get()
```
和
```
ctx.db.query()
```
操作

追踪所有

ctx.db.patch()

、

ctx.db.replace()

和

ctx.db.insert()

操作

记录外键查找、JS端过滤和全文档读取操作
识别所有访问相同表的同类函数
识别同一页面上渲染的响应式统计数据、聚合结果或组件

在Convex中，每一次额外的读取都会增加事务负载，每一次写入都可能使响应式订阅失效。需将读取放大和失效放大视为核心问题。

3. 应用对应参考文档中的修复方案

阅读与问题类别匹配的参考文档。每个参考文档都包含具体模式、代码示例和推荐的修复顺序。

不要仅停留在洞察数据指出的单个函数上。需追踪访问相同表的同类读取和写入函数。

4. 统一修复同类函数

当某个访问表的函数存在性能问题时，需审计同类函数是否存在相同模式。

发现一个问题后，检查同一表族的所有同类读取和写入函数，包括配套的摘要表或汇总表。

示例：

如果某个列表查询从全文档读取切换为摘要表读取，检查该表的其他列表查询
如果某个突变需要无操作写入保护，检查同一表的其他写入函数
如果某个读取路径对未回填字段需要迁移安全部署，检查同类读取是否存在相同的部署风险

除非有明确的产品原因，否则不要仅修复一个路径而保留其他路径的旧模式。

5. 完成前验证

确认以下所有事项：

结果与修复前一致，无记录丢失
预期路径中的多余读取或写入已被消除
当非规范化或索引字段缺失时，回退行为正常
新的写入操作在数据未变更时避免不必要的失效
已检查所有相关的同类读取和写入函数，而非仅原函数

参考文档

```
references/hot-path-rules.md
```
- 读取放大、失效、非规范化、索引、摘要表
```
references/occ-conflicts.md
```
- 写入冲突、OCC解决、热点文档拆分
```
references/subscription-cost.md
```
- 响应式查询成本、订阅粒度、时点读取
```
references/function-budget.md
```
- 执行限制、事务大小、大文档、负载大小

同时可查看官方的Convex最佳实践页面，获取审计过程中可能涉及的参数验证、访问控制和代码组织等额外模式。

检查清单

从洞察数据、控制台或代码审计中收集了信号
确定了问题类别并阅读了对应的参考文档
界定了一个具体的用户流程或函数路径
追踪了该路径中的所有读写操作
识别了访问相同表的同类函数
按照推荐的修复顺序应用了参考文档中的修复方案
统一修复了同类函数
验证了行为并确认无回归问题

convex-performance-audit

NPX安装

标签

SKILL.md 内容（中文）