这篇笔记解决什么问题
这个 Demo 现在故意做得很克制,不是因为功能想不到,而是因为我们需要先拿到一个稳定、可反复验证的 Cesium 初始化基线。
之前往页面里叠加扫描圈、点位和联动面板之后,运行过程中出现过 Maximum call stack size exceeded。在这种情况下,继续往上堆功能会让问题越来越难拆,所以这里先把目标收敛为一件事:
- 让真实的 Cesium
Viewer在 Demo 详情页里稳定初始化 - 保证路由切换和组件卸载时能干净销毁
- 保留内容壳和运行时代码分离的页面结构
当前实现怎么拆
当前这条链路分成两层:
content/demos/*.md负责 Demo 页面元数据和“怎么观察效果”的轻量说明demos/**/*.js负责真正的浏览器运行时逻辑
这样做的好处是,Demo 页可以继续承担展示入口和内容壳,而重型 3D 初始化逻辑仍然留在客户端按需加载,不会把 SSR 页面也拖进浏览器专属依赖里。
运行时的关键选择
1. 使用 ESM import 初始化 Cesium
这个 Demo 直接通过 ESM 方式加载 Cesium,而不是再额外挂一套传统脚本注入逻辑。这样做有两个好处:
- 依赖边界更清楚,运行时和工程构建保持一致
- 以后继续加功能时,更容易沿用模块化拆分方式
2. 静态资源继续预先复制
虽然运行时代码走 ESM,但 Cesium 仍然需要它自己的静态资源目录。当前策略是继续通过 prepare:cesium 把这些资源复制到 public/cesiumStatic,这样运行时能稳定访问 Workers、Assets 和 Widgets。
这个点很重要,因为很多“看起来像初始化失败”的问题,本质上不是 Viewer API 本身的问题,而是静态资源路径没准备好。
3. 底图先走最稳妥路线
为了保证没有 token 的情况下也能稳定显示,当前版本优先使用 Cesium 自带的基础纹理资源,不把 Demo 的可运行性绑定到外部服务授权状态上。
这意味着它不是一个追求“最好看”的版本,而是一个追求“最稳定、最容易定位问题”的版本。
为什么先回到最小版本
这个 Demo 当前最重要的价值,不是展示复杂业务能力,而是作为后续迭代的安全起点。
如果基础初始化都不稳定,那么后面再加:
- 扫描圈
- 飞线
- 点位
- 联动面板
- 自定义镜头节奏
这些能力时,很难判断问题到底出在哪一层。先把基线做小,后续每次新增能力时都能更明确地验证“是哪一步把稳定性打破了”。
后续怎么继续加
比较稳妥的节奏是按层往回加,而不是一次性恢复全部效果:
- 先加单一图层或单一实体能力
- 再加交互或面板联动
- 最后再回到更完整的可视化编排
这样每一步都有明确的回退点,也更适合作为作品集里的长期维护 Demo。