外观
调试与排查手册
约 2563 字大约 9 分钟
2026-10-11
本手册是 常见问题（issue 分类，按功能现象浏览）的反向索引：当你已经看到了报错信息或异常现象，可以直接在下面两张表里定位。每个条目的具体解决步骤都在对应的 issue 文章中，本页不重复内容，只负责"指路"。
1. 排查总流程
遇到"不显示 / 报错 / 效果不对"时，先按下面顺序走一遍，能解决大部分问题：
- 看控制台：F12 打开 Console，先处理红色报错，再看 Network 里瓦片、模型、config.json 是否 200。
- 最小复现：在功能示例中用同一份 URL、同一组参数新建空白页验证。示例能跑、你的代码不能跑，就是集成/参数问题；示例也不能跑，多半是数据或服务问题。
- 核版本：
mars3d、mars3d-cesium、各插件三者大版本必须一致；对照版本更新日志中的"弃用 & API 重构"。 - 二分定位：注释掉一半图层/特效/分析代码，逐步缩小到具体对象；确认是数据问题、参数问题还是环境问题。
- 查索引：在本页第 2、3 节按报错文案或现象找对应文章。
浏览器环境与显卡要求见 访问系统环境要求，调试环境搭建见 开发环境搭建。
2. 按报错信息反查（控制台文案 → 原因与文章）
| 控制台报错 / 提示 | 常见原因 | 处理入口 |
|---|---|---|
mars3d.xxx is not a constructor | 类不存在：漏引插件（如热力图 mars3d-heatmap）、漏引第三方资源、SDK 版本与示例不一致 | mars3d.* is not a constructor |
Cannot read properties of undefined (reading 'BaseLayer') | 插件引入顺序错误，先引入了插件、后引入 mars3d | 热力图使用问题 - 引入顺序 |
| 弹窗"WebGL 渲染时发生错误，渲染已经停止" | 显卡/显存不足、数据量超 GPU 内存、坐标参数异常、平视/仰角内部计算异常 | WebGL渲染错误弹窗 |
No 'Access-Control-Allow-Origin' header ... | 跨域：数据服务或瓦片服务未配置 CORS | 跨域问题 |
Failed to obtain image tile X: x Y: y Level: z、切片 404 | 切瓦片范围不全或路径不对；底图能出但控制台一片红时可在 nginx 兜底透明图 | 框架集成问题 - 404 报错处理 |
| 打包发布后底图/数据加载不出来，本地正常 | config.json 等资源相对路径在部署目录下失效；Node/NPM 环境差异 | 框架集成问题 - 发布后异常 |
Unsupported codec in video frame: 12（flv 播放失败） | 视频是 H.265 编码，播放器不支持，改 H.264 或换 EasyPlayer 等 | 视频矢量相关 |
| 升级后模型裁剪、压平等功能失效 | Cesium / Mars3D 大版本存在不兼容改动（如 1.102+、1.83 KTX2） | Cesium版本兼容 |
天地图等服务 403、token 相关报错 | key 过期、超限或替换不彻底（config.json、代码、瓦片地址三处） | token值修改 |
| 图片加载黑屏 / 大图片不显示 | 单张图片分辨率超过 WebGL 4096 像素限制（如 60M imageLayer） | 瓦片图层 - 图片过大 |
WebGL 崩溃后希望页面自动恢复，可以监听渲染错误事件：
// webgl渲染失败后，刷新页面 map.on(mars3d.EventType.renderError, () => { window.location.reload() })
3. 按现象反查
3.1 场景与性能
| 现象 | 先看哪里 |
|---|---|
| 页面白屏 / 地球出不来 | 控制台先按第 2 节排错；显卡与浏览器环境见 WebGL渲染错误弹窗 与 访问系统环境要求 |
| 越用越卡、CPU 持续 100% | 显卡设置、渲染模式（requestRenderMode）、Mars3D 参数，见 CPU占用率100；系统优化清单见 性能优化与调优 |
| Vue 项目里地图越来越卡 | mars3d 对象放进了 data/store/computed 被响应式代理；对象关闭后未销毁，见 Vue技术栈下卡顿 |
| 国产信创（统信/麒麟/国产显卡）环境异常 | 国产信创系统调优 |
| FPS、显存、内存怎么观测 | 性能优化与调优 - 排查工具 |
3.2 模型与瓦片
| 现象 | 先看哪里 |
|---|---|
| 3DTiles 模型不显示 | URL、参数、渲染报错、官方示例验证 4 步走：加载3dtiles不出现 |
| glTF 小模型不显示 | URL、参数、深度检测遮挡、格式转换：加载gltf不出现 |
| 模型/矢量在地面漂移、忽隐忽现 | 深度检测与高度问题：加载的矢量数据在地面漂移 |
| 模型压平、裁剪、开挖效果不对 | 模型分析、地形分析 |
| 需要模型按构件显隐、单击分户、单体化 | 模型单体化 |
| 模型相关其他疑问（贴地形、旋转轴、光照等） | 三维模型其他问题 |
| 瓦片偏移/模糊/没铺满/南北极缺圆 | 瓦片图层 |
| 高德、百度等国内底图样式、注记、坐标偏移 | 高德百度地图 |
| 地形加载、多地形、坡度坡向异常 | 地形服务加载、地形 |
| 图层叠放顺序不对、被盖住 | zIndex层级 |
| 热力图不显示 / 正上方白方块 / 贴地异常 | 热力图使用问题 |
| 模型、瓦片加载效率问题 | 加载效率 |
| 内网离线环境 | 内网离线 与 离线私有化部署 |
3.3 矢量、控件与交互
| 现象 | 先看哪里 |
|---|---|
| 矢量对象不显示（视域、坐标、深度检测） | 加载的矢量不显示 |
| 单击事件不触发 / 拾取坐标不对 | 事件机制 - "事件不触发"排查清单 |
| Popup 弹窗不显示、内容想自定义、想自动弹出 | Popup弹窗、控件 |
| 线/面样式（宽度、渐变、闪烁、材质等）问题 | 多坐标矢量问题 |
| 点/图标/小模型/Div 相关问题 | 单坐标矢量问题 |
| 绘制、编辑操作相关 | 绘制编辑 |
| 动态路线、FixedRoute、轨迹贴地卡死 | 动态路线 |
| Video3D 视频融合、flv 播放 | 视频矢量相关 |
| 控件（鹰眼、右键菜单、时间线、locationBar 等） | 控件 |
| 特效、泛光、亮度、气象效果 | 特效相关 与 特效 |
| 量算、剖面、坡度坡向等分析功能 | 空间分析 与 管理及分析功能 |
| 坐标经纬度/高程转换结果不对 | 坐标转换问题 与 坐标转换 |
3.4 框架、版本与工程
| 现象 | 先看哪里 |
|---|---|
| 本地正常、打包后异常 | 框架集成问题 |
| 中键不能旋转、移动端锁正北、2.5D 下 flyTo 的 pitch 不生效 | 框架集成问题 - 相机相关 与 相机及视角 |
| 不确定示例、模版、SDK 之间的关系 | 示例及项目、功能示例、通用项目模版-Vue版 |
| 第三方图层（天地图、高德、pbf 等）集成 | 第三方集成 |
| NPM / CDN / 静态三种集成方式的差异 | NPM方式集成、静态方式集成、CDN方式集成 |
4. 求助前的检查清单
以上索引都没解决时，提 issue 或进群提问前请先准备好这些信息（也能帮助你自己再梳理一遍）：
- 报错原文：Console 红色报错的完整截图/文本，而不是"报错了"。
- 版本信息：mars3d、mars3d-cesium、浏览器、操作系统（信创环境注明芯片与显卡）。
- 复现方式：能否在功能示例中复现；数据 URL 是否可直接访问。
- 最小代码：去掉业务逻辑后仍能复现的配置/代码片段，以及 Network 中异常请求的状态码。