> **本文回答**：性能主题总览 —— vjmap 底座渲染、vjmapext 实体渲染桶、FX GPU 特效、事件节流、内存泄漏。

# 性能主题

| 层 | 对象 | 性能关键点 |
|---|---|---|
| vjmap 底座 | `map` / source / layer | feature-state 换样式 / 减少 layer 数 / source 聚合 |
| vjmapext 实体 | `mapcadLayer.addEntity` | render-bucket 分桶 / `styleChanged` 快路径 / `dynamic` / `beginBulk` |
| GPU FX | `mapcadLayer.fx` | `setQuality` / `addPoints` 批量 / bucket 层级 / 事件 metrics |
| 事件 | `map.on` / `eventBus.on` | mousemove 合并 / RAF / debounce |

## 子项索引

| 文件 | 主题 |
|---|---|
| [render-buckets](../../../vjmapext/references/perf/render-buckets.md) | hot / cold / dynamic 渲染桶原理 |
| [dynamic-entities](../../../vjmapext/references/perf/dynamic-entities.md) | `entity.dynamic = true` 应用场景 |
| [style-only-fast-path](../../../vjmapext/references/perf/style-only-fast-path.md) | `styleChanged()` 快路径 |
| [render-cache](../../../vjmapext/references/perf/render-cache.md) | RenderCache 失效 / forceFullRender |
| [fx-overview](../../../vjmapext/references/perf/fx-overview.md) | fx GPU 图层 vs 实体层分工 |
| [fx-quality](../../../vjmapext/references/perf/fx-quality.md) | `setQuality` / `getMetrics` / fx 事件 |
| [fx-presets](../../../vjmapext/references/perf/fx-presets.md) | 12 点 / 5 线 预设选型 |
| [large-markers](large-markers.md) | 上万 Marker → Symbol / Cluster 切换 |
| [event-throttling](event-throttling.md) | mousemove 合并 / RAF / debounce |
| [batch-rendering](../../../vjmapext/references/perf/batch-rendering.md) | 批量新增 / 修改策略 |
| [memory-leaks](memory-leaks.md) | 未 off / 未 remove / 未卸载 |
| [profiling](profiling.md) | Chrome DevTools / Performance 录制 |

## 最小代码：快路径 vs 慢路径

```js
// 慢：几何 + 样式全量重算
for (const e of entities) {
  e.color = 0xff0000;
  e.changed();
}

// 快：仅样式
for (const e of entities) {
  e.color = 0xff0000;
  e.styleChanged();          // 不重建空间索引 / 不重新三角化
}

// 批量样式修改无需专用批量 API——styleChanged 只标脏，重绘按帧合并；
// 需要一步撤销时包 undo 事务：
mapcadLayer.undoManager.beginTransaction();
for (const e of entities) {
  e.color = 0xff0000;
  e.styleChanged();
}
mapcadLayer.undoManager.endTransaction();
```

## 性能诊断速查

| 症状 | 最可能的原因 | 去哪看 |
|---|---|---|
| 新增 1 万实体一卡一卡 | 循环里每次 `setDirty` / `changed` | [batch-rendering](../../../vjmapext/references/perf/batch-rendering.md) |
| 只改颜色也很卡 | 用了 `changed()` 而不是 `styleChanged()` | [style-only-fast-path](../../../vjmapext/references/perf/style-only-fast-path.md) |
| 频繁改坐标但没反应 | 没设 `entity.dynamic = true` | [dynamic-entities](../../../vjmapext/references/perf/dynamic-entities.md) |
| 地图一缩放就卡 | 太多 Marker（DOM 每个节点重算 transform） | [large-markers](large-markers.md) |
| mousemove handler 慢 | 每帧 fire，handler 没节流 | [event-throttling](event-throttling.md) |
| 切换页面地图不释放 | 没 off 事件 / 没 remove map | [memory-leaks](memory-leaks.md) |
| FX 特效撑不住 1 万点 | 逐个 `addPoint` 而不是 `addPoints` | [fx-quality](../../../vjmapext/references/perf/fx-quality.md) |

## 主题级 Top 5 陷阱

1. **`changed()` vs `styleChanged()` 混用**：只改颜色却用 `changed()` → 整个空间索引重建。
2. **循环 add 1 万实体不走 bulk**：每次都触发 render → 上万次 RAF 合并失败。
3. **Marker DOM 数量上限**：> 500 个 DOM Marker 就开始明显卡；换 Symbol 图层。
4. **`dynamic = false` 的实体反复改属性**：画面不更新或"怎么刷都一样"。
5. **eventBus 没 off**：组件卸载后回调仍跑、还持有大对象引用 → 内存泄漏。

## 相关

- 批量 → [batch/overview](../../../vjmapext/references/batch/overview.md)
- 动画/特效 → vjmapext skill `references/perf/fx-overview.md`
- 卸载 → [trouble/vue-react-dispose](../trouble/vue-react-dispose.md)