> **本文回答**：常见坑索引 —— 从现象反查解决方案。

# 常见坑

按**现象 → 文件**映射，遇到问题直接跳对应叶子。

## 症状速查

| 症状 | 原因 / 文件 |
|---|---|
| 首屏黑屏 / 画面未出现 | [container-collapse](container-collapse.md) |
| `vjmapext is not defined` | [cdn-order](cdn-order.md) |
| 请求 401 / 403 / CORS | [token-cors](token-cors.md) |
| `svc.openMap` 成功但 `res.bounds` 取不到 | [bounds-parse](bounds-parse.md) |
| Node 里 `openMap` 一直 403 / `{reload:true}` | 自定义 `IRequest` 丢了 `args.headers` → [token-cors](token-cors.md) "Node 环境" 节 |
| `getEpsgParam` 返回 null | 第二参要传**带号或 8 位坐标**，不是普通经度 → [coord/cad-epsg](../coord/cad-epsg.md) |
| 高德底图上 CAD 坐标偏 100~500 米 | [coord-offset-gaode](coord-offset-gaode.md) |
| 控件 / Popup 样式不对 | [createui-no-theme](../../../vjmapext/references/trouble/createui-no-theme.md) |
| 批量 addEntity 非常慢 | [batch-lag](../../../vjmapext/references/trouble/batch-lag.md) |
| Vue / React 切页面后 Marker 重影 | [marker-duplicate](marker-duplicate.md) |
| 内存一直涨不释放 | [listener-leak](listener-leak.md) |
| `fromJSON` 后看不见图 | [fromjson-fit](../../../vjmapext/references/trouble/fromjson-fit.md) |
| 组件卸载后地图未销毁 | [vue-react-dispose](vue-react-dispose.md) |

## Top 10 红旗

1. 容器 `<div>` 没有宽高 / 没有 `position: relative` → 首屏塌陷
2. `<script>` 把 vjmapext 放在 vjmap 前面 → 加载失败
3. `openMap` 成功后没检查 `res.error`
4. 高德底图上 CAD 坐标没做 GCJ02 转换
5. 批量 `addEntity` 循环里每条都 `setDirty()`
6. Vue 组件卸载时没 `map.remove()` → Marker 残留
7. `map.on('click', handler)` 没对应 `off` → 内存泄漏
8. `new vjmap.Service(url, token)` 的服务地址和后端域名协议不一致 → 混合内容（注意：Service 构造是**位置参数** `(url, token)`；配套后端 SDK 也是位置参数 `new Vjmap(baseUrl, token)` / `Vjmap(base_url, token)`）
9. `DomUtil / createUI` 之前没加主题 CSS
10. `fromJSON` 后忘 `zoomExtents()` → 看不到加载的图

## 排查流程

```
1. 看浏览器 Console 有没有红字 → 拷关键字搜本目录
2. 看 Network 面板 → 401/403/CORS → token-cors.md
3. 容器元素检查 → 宽高 0 / display none → container-collapse.md
4. 没错也不显示 → fromjson-fit / bounds-parse
5. 都没问题但画面重影 / 泄漏 → marker-duplicate / listener-leak / vue-react-dispose
```

## 相关

- 初始化 → [setup/overview](../setup/overview.md)
- 卸载 → [setup/dispose](../setup/dispose.md)
- 事件清理 → [event/cleanup](../event/cleanup.md)
- 性能 → [perf/overview](../perf/overview.md)