高德地图 JS API 2.0 在国产 Linux/ARM 电脑上渲染失败 的排查与解决

项目部署到国产 Linux/ARM 电脑后，高德地图出现了以下问题：

• 3D 建筑不显示；
• 地图无法倾斜、旋转；
• 高精度 WebGL 图层无法正常渲染；
• 地图自动降级为二维模式。

问题原因

浏览器虽然支持 WebGL，但当前显卡驱动或图形环境被判定存在性能风险。

高德 JS API 2.0 在初始化时会对 WebGL 运行环境进行检测。当严格检测未通过时，高德会主动关闭 WebGL 渲染并降级为二维地图。

因此会出现浏览器可以创建 WebGL 上下文，但：

控制台执行AMap.Browser.isWebGL

返回false

这并不代表电脑完全不支持 WebGL，而是高德 JS API 主动进行了兼容性降级。

解决方法

在加载高德 JS API 之前设置：

window.forceWebGL = true;

如果项目使用 Vue 3 和 @vuemap/vue-amap，可以这样处理：

import { initAMapApiLoader } from '@vuemap/vue-amap';

// 强制高德 JS API 使用 WebGL，避免被自动降级为二维地图。
// 必须在加载高德 JS API 之前设置。
(window as any).forceWebGL = true;

initAMapApiLoader({
  key: '你的高德地图 Key',
  version: '2.0',
  plugins: [
    'AMap.Scale',
    'AMap.ToolBar'
  ]
});

如果使用普通脚本加载高德地图：

<script>
  window.forceWebGL = true;
</script>

<script src="https://webapi.amap.com/maps?v=2.0&key=你的Key"></script>

需要注意，forceWebGL 必须写在高德 JS API 加载之前，否则不会生效。

修改后，地图的旋转、倾斜、3D 建筑以及高精度 WebGL 图层均可恢复正常。

forceWebGL 会绕过高德的性能检测。使用后应在目标电脑上测试缩放、旋转和长时间运行是否稳定。