需同时引入 mapbox-gl.css 和 mapbox-gl.js，设置容器宽高、access token，并在 map.on('load') 后操作图层；center 为 [lng, lat]，source 与 layer 名须一致且大小写敏感。
怎么在HTML里引入Mapbox GL JS并显示基础地图
必须用 mapbox-gl-js 官方 CDN 或 npm 包，不能只放个 <script></script> 标签就完事——缺 mapbox-gl.css 会导致地图容器空白、控件错位、缩放按钮不响应。
实操建议：
- 在
里加两行：<script src="https://api.mapbox.com/mapbox-gl-js/v3.12.0/mapbox-gl.js"></script> - 确保容器有明确宽高（比如
style="width: 600px; height: 400px;"），div#map不能是display: none或父元素未渲染 - 初始化前必须调用
mapboxgl.accessToken = 'your_token_here';，否则控制台报Error: No access token set.
为什么地图加载后是灰色方块或报“Style is not done loading”
常见于异步加载样式失败，尤其用了自定义 style JSON 或离线 tile URL。Mapbox GL 不会自动重试失败的样式请求，也不会降级显示。
实操建议：
- 检查浏览器 DevTools 的 Network 面板，确认
style.json返回 200 且内容合法（不是 404、401 或 HTML 错误页） - 如果用自定义 style，确保所有图层引用的 source 都已正确定义，且
source.type是raster、vector或geojson之一 - 避免在
new mapboxgl.Map({})后立刻调用map.addLayer()——等map.on('load', () => {...})触发后再操作图层
mapboxgl.Map 构造函数里哪些参数最关键、容易设错
container、style、center、zoom 四个必填项里，container 最常出问题：它必须是 DOM 元素或字符串 ID，不能是 jQuery 对象或 document.querySelector() 返回的 null。
实操建议：
-
container推荐传字符串（如'map'），比传document.getElementById('map')更安全；若传元素，确保执行时该元素已存在于 DOM -
style可以是 Mapbox 托管的 URL（如'mapbox://styles/mapbox/streets-v12'），也可以是对象字面量，但后者必须含version: 8字段 -
center是[lng, lat]数组（注意顺序！不是[lat, lng]），超出范围（如纬度 > 90）会导致地图卡死或白屏 - 别漏
projection: 'globe'（v3.10+ 支持），否则地球模式不会启用，即使设置了terrain
加载 GeoJSON 数据后地图没反应？检查 addSource / addLayer 的时机和结构
直接 new Map 后立刻 map.addSource('mydata', {...}) 会报 Error: Style is not done loading —— 这不是代码写错了，是 Mapbox GL 的异步加载机制导致的。
实操建议：
- 所有
addSource、addLayer、setLayoutProperty操作，必须放在map.on('load', () => {...})回调里 - GeoJSON source 的
data字段如果是 URL，需支持 CORS；如果是对象，必须符合 RFC 7946，features数组不能为空，每个feature.geometry不能为 null - layer 的
source名必须和addSource时传的一致，大小写敏感；type值只能是circle、fill、line、symbol、raster等有限几个
最易被忽略的是：地图容器父元素在初始化后动态显隐（比如 tab 切换），会导致 WebGL 渲染上下文丢失，需要手动调用 map.resize()。这不是 bug，是 WebGL 的正常行为。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
