Mapbox GL JS 3.25.0 带来了两项破坏性变更：ESM 入口点改为命名导出，全局 accessToken 被替换为构造选项 MapaccessToken。这两处改动看似不大，却直接影响现有项目的打包体积和初始化方式——升级前不搞清楚，地图直接白屏。
ESM 入口点：从默认导出走向命名导出
旧版本中，ESM 入口点是一个默认导出对象，打包工具很难判断哪些成员被实际使用，只能把整个包塞进产物。3.25.0 把 ESM 入口点改为命名导出：
// 旧写法——打包工具无法静态分析，全量引入
import mapboxgl from 'mapbox-gl';
mapboxgl.Map;
mapboxgl.NavigationControl;
// 新写法——命名导出，打包工具可按需移除未使用代码
import * as mapboxgl from 'mapbox-gl/esm';
// 或更精确地只拿需要的
import { Map, NavigationControl } from 'mapbox-gl/esm';
关键收益：现代打包工具（Rollup、Vite、webpack 5 的 tree-shaking）现在有机会在编译期识别并剔除你没用到的导出成员。不过官方也坦诚——由于库内部仍有大量动态引用，大部分代码块暂时还无法被静态删除，这次改动只是迈出了第一步。
如果你的项目用 CommonJS 方式引入（require('mapbox-gl')），这次 ESM 变更不影响你，但长远来看，切换到命名导出是更健康的方向。
accessToken 退役，MapaccessToken 接棒
过去十多年，Mapbox 的标准做法是把 token 挂到全局对象上：
mapboxgl.accessToken = 'pk.your_token_here';
new mapboxgl.Map({ container: 'map' });
3.25.0 正式废弃了这个全局属性，改为在 Map 构造选项中传入：
import { Map } from 'mapbox-gl/esm';
const map = new Map({
container: 'map',
MapaccessToken: 'pk.your_token_here',
style: 'mapbox://styles/mapbox/streets-v12',
center: [116.4, 39.9],
zoom: 10
});
这样做的好处是 token 与实例绑定，不再污染全局空间。在微前端或多地图实例场景下，不同实例可以用不同 token，互不干扰。旧的全局赋值方式在当前版本仍能运行，但会在控制台打出废弃警告，后续版本将彻底移除。
迁移实操：一份可跑的最小示例
下面是一个用 Vite + Mapbox GL JS 3.25.0 的最小项目，可以直接复制运行：
mkdir mapbox-325-demo && cd mapbox-325-demo
npm create vite@latest -- --template vanilla
npm install mapbox-gl@3.25.0
把 index.html 改为：
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8" />
<title>Mapbox 3.25 Demo</title>
<style>
body { margin: 0; }
#map { width: 100vw; height: 100vh; }
</style>
</head>
<body>
<div id="map"></div>
<script type="module" src="/main.js"></script>
</body>
</html>
main.js 写成：
import { Map, NavigationControl } from 'mapbox-gl/esm';
import 'mapbox-gl/dist/mapbox-gl.css';
// ⚠️ 把下面替换为你自己的 Mapbox 公开 token
const TOKEN = 'pk.your_real_token_here';
const map = new Map({
container: 'map',
MapaccessToken: TOKEN,
style: 'mapbox://styles/mapbox/streets-v12',
center: [116.397, 39.908], // 北京
zoom: 11
});
map.addControl(new NavigationControl(), 'top-right');
启动：
npm run dev
浏览器打开后应能看到北京城区街道地图，右上角有缩放控件。如果白屏，先检查 token 是否有效、网络是否可达 Mapbox CDN。
升级前的检查清单
- 排查旧导入方式：全局搜索
import mapboxgl from 'mapbox-gl'和require('mapbox-gl')，逐个改为命名导出或import * as mapboxgl from 'mapbox-gl/esm'。 - 排查 accessToken 赋值：搜索
mapboxgl.accessToken =，替换为构造选项MapaccessToken。如果多处创建地图，每处都要传。 - 留意 CSS 引入路径：样式文件
mapbox-gl/dist/mapbox-gl.css不受此次变更影响，照旧引入即可。 - 验证打包产物体积：升级后用打包工具的 analyze 插件对比产物大小。这次改动对体积的削减可能有限，但后续版本会持续改善。
- 关注控制台废弃警告：3.25.0 仍兼容旧写法但会打警告，看到警告说明还有遗漏的迁移点。
这次升级的破坏面不算大，但两项改动都指向同一个方向——让 Mapbox GL JS 更适合现代前端工具链的静态分析和按需裁剪。如果你还在用旧版全局 token + 默认导出，现在就是动手的时机。