企业官网建设流程全解析

• 前端
• UI组件

本文基于仓库内的官方升级指南 docs/upgrade-guide.md 编写，覆盖 react-map-gl 从 v1 到 v8.0 的全部重大变更：模块入口拆分（react-map-gl/mapbox、react-map-gl/maplibre、react-map-gl/mapbox-legacy）、TypeScript 类型重命名、Map组件 props 重构、MapController/overlay 组件移除等。结合当前仓库（主包版本为 8.1.0-alpha.2，见 modules/main/package.json）的源码与测试实现，帮助你在跨版本升级时精确定位每一步需要修改的代码，并理解每项变更背后的实现原因。

升级到 v8.0

v8 是一次以“按地图引擎拆分入口”为核心的版本，升级时需要处理三件事：替换导入入口、放弃 maplibre-gl@<=3 支持、重命名 TypeScript 类型。

替换导入入口

所有从react-map-gl根路径的导入必须替换为以下入口之一：

• 搭配mapbox-gl@>=3.5.0：从react-map-gl/mapbox导入
• 搭配mapbox-gl@<3.5.0：从react-map-gl/mapbox-legacy导入
• 使用 MapLibre 的用户：从react-map-gl/maplibre导入（该入口自 v7.1 引入，见下文）

这一拆分在仓库的包配置中可以直接验证。modules/main/package.json 的exports字段只暴露三个子路径，没有任何根入口：

"exports": { "./mapbox": {...}, "./maplibre": {...}, "./mapbox-legacy": {...} }

三个入口的实现都是极薄的转发层：

• modules/main/src/mapbox.ts：export * from '@vis.gl/react-mapbox'
• modules/main/src/maplibre.ts：export * from '@vis.gl/react-maplibre'
• modules/main/src/mapbox-legacy/index.ts：独立导出Map、Marker、Popup、各控件与useControl/useMap，并附带mapbox-legacy专属的类型与工具模块

从源码结构看，mapbox与mapbox-legacy对应 monorepo 中两个独立的实现包（modules/react-mapbox与modules/main/src/mapbox-legacy），前者基于 mapbox-gl v3 系列的 API 编写，后者保留对旧版 mapbox-gl 的兼容。这也解释了为什么需要按mapbox-gl版本选择入口——两条代码路径对底层库的假设并不相同。

不再支持 maplibre-gl@<=3

maplibre-gl@<=3已被移除支持，MapLibre 用户需要升级到 maplibre-gl v4+。

TypeScript 类型重命名

v8 将部分自定义类型重命名，与底层地图库的官方类型名对齐：

两条入口的类型来源可以在源码中对照确认：

• react-map-gl/mapbox路径直接 re-export mapbox-gl 的官方类型名，见 modules/react-mapbox/src/types/style-spec.ts（StyleSpecification、LightSpecification、FogSpecification、TerrainSpecification、ProjectionSpecification等全部来自mapbox-gl）
• react-map-gl/mapbox-legacy路径则用export type {...} from 'mapbox-gl'把官方短名映射为*Specification名称，见 modules/main/src/mapbox-legacy/types/style-spec.ts，例如Style as StyleSpecification、Light as LightSpecification、Fog as FogSpecification、AnySourceData as SourceSpecification等，与上表的重命名规则一一对应

如果项目中通过import type {MapStyle, CircleLayer} from 'react-map-gl/mapbox'之类的写法引用了旧类型，升级到 v8 后需要按上表逐一替换为新名称。

MapLibre：移除RTLTextPlugin默认值

为了与 MapLibre 的默认行为对齐，v8 移除了原先从 mapbox.com 默认加载的RTLTextPlugin（该插件用于支持阿拉伯语、希伯来语等从右向左书写的文本）。如果希望保留旧版行为，需要显式指定pluginUrl或从其他来源提供插件：

<Map RTLTextPlugin="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js" />

源码层面这一差异非常清晰：

• Mapbox 入口的 modules/react-mapbox/src/utils/set-globals.ts 中，RTLTextPlugin的解构默认值仍是指向 mapbox.com 的插件 URL，即 Mapbox 用户不传该 prop 时插件会自动加载
• MapLibre 入口的 modules/react-maplibre/src/utils/set-globals.ts 中则没有任何默认值：只有当你传入RTLTextPlugin（字符串 URL，或{pluginUrl, lazy}对象形式）时才会调用mapLib.setRTLTextPlugin(...)

因此 v8 升级时对 MapLibre 项目的一个必查项就是：如果界面需要 RTL 文本支持，确认Map上显式传入了RTLTextPlugin。

升级到 v7.1

v7.1 最大的变化是为 MapLibre 用户提供了独立的模块入口react-map-gl/maplibre。

MapLibre 用户改用新入口

maplibre-gl用户不再需要安装mapbox-gl或任何占位包作为依赖。把导入切换到react-map-gl/maplibre后，组件不再需要mapLibprop，并使用maplibre-gl自己定义的类型：

import Map from 'react-map-gl'; import maplibregl from 'maplibre-gl'; function App() { return <Map mapLib={maplibregl} style={MAP_STYLE} maplibreLogo // 这会产生 TypeScript 错误，因为 Mapbox 的 options 中没有这个定义 />; }

import Map from 'react-map-gl/maplibre'; // <- 注意更新后的导入 function App() { return <Map // mapLib 默认为 `import('maplibre-gl')` style={MAP_STYLE} maplibreLogo />; }

v7.0 时代mapLib写法存在的一个典型痛点是类型系统无法区分底层引擎：maplibreLogo这类 MapLibre 专属选项在 Mapbox 类型定义中不存在，只能靠as any或忽略报错。独立入口让react-map-gl/maplibre的MapProps直接基于maplibre-gl的类型，问题自然消失。

清理占位依赖

如果按照旧版文档建议，从占位包（如npm:empty-npm-package@^1.0.0）安装了mapbox-gl，应将其从 package.json 中移除。主包现在把mapbox-gl与maplibre-gl都声明为可选的 peer dependency（peerDependenciesMeta中optional: true，见 modules/main/package.json），你只需安装自己实际使用的那个地图库。

其他 v7.1 变更

• @types/mapbox-gl的依赖版本约束已放宽。如果以mapbox-gl作为底层库，建议在 package.json 中显式列出与mapbox-gl主版本一致（v1 或 v2）的@types/mapbox-gl。该包已不再是非 Mapbox 代码路径的必需依赖，未来版本还可能被进一步降级为可选 peer dependency。
• 如果你把Map组件作为 deck.gl（deck.gl）ContextProvider的子节点使用，需要把deck.gl升级到>=8.9.18。

升级到 v7.0

v7 是 react-map-gl 的一次完全重写：重新设计为更快、更轻量、完全类型化，行为与暴露的 API 尽量与所包装的地图库保持一致，并最大化与第三方插件的兼容性。如果你的代码依赖 v5/v6，需要按下述章节逐项修改。

重要：如果你在使用 react-map-gl 的控件（Marker、Popup、NavigationControl等）配合 deck.gl 的ContextProvider，请不要升级到 v7——旧方案在 v7 中不再工作。该用例的支持正在迁移到一个不依赖 mapbox 的新项目。

依赖变更

• 需要在你的 package.json 中添加mapbox-gl（或兼容的 fork）。react-map-gl不再在 dependencies 中固定某个地图渲染器，你可以自由选择 Mapbox v1、v2 或 MapLibre。
• viewport-mercator-project（@math.gl/web-mercator的别名）不再是依赖。如需要，仍可以自行安装它作为视口数学工具，但已非必需。

模块导出移除

关于MapController的移除值得展开：v7 不再维护一套自定义的输入处理逻辑，而是让Map组件的 props 直接映射到地图库的原生 handler。从源码看，modules/react-mapbox/src/mapbox/mapbox.ts 中的handlerNames列表（scrollZoom、boxZoom、dragRotate、dragPan、keyboard、doubleClickZoom、touchZoomRotate、touchPitch）就是被支持透传的交互开关，默认全部启用（见 modules/react-mapbox/src/mapbox/mapbox.ts 中_updateHandlers对nextProps[propName] ?? true的处理）。如果你此前用自定义MapController做过特殊输入处理，建议先对照原生 handler 的选项评估可行性。

Map 组件 props 变更

完整的 props 文档见 docs/api-reference/mapbox/map.md，核心变更如下：

重命名的 props（与底层库对齐）：

注意preventStyleDiffing→styleDiffing不仅是改名，语义取反：默认值从“不 diff”变成了“diff 开启”。源码中可以确认styleDiffing默认值为true（modules/react-mapbox/src/mapbox/mapbox.ts 的类型注释@default true，以及 modules/react-mapbox/src/mapbox/mapbox.ts 中const {mapStyle = DEFAULT_STYLE, styleDiffing = true} = nextProps的解构默认值）。

默认值变更：

• mapStyle现在必须显式指定。默认值从"mapbox://styles/mapbox/light-v9"变为空样式。源码中的空样式定义为{version: 8, sources: {}, layers: []}（modules/react-mapbox/src/mapbox/mapbox.ts），也就是说升级后如果不传mapStyle，地图将是一张没有瓦片、没有图层的空白画布。

移除的 props：

• width、height、visible：这三个 prop 被移除，尺寸与可见性应通过style（CSS）控制。
• onViewportChange、onViewStateChange、onInteractionStateChange：v7 支持两种模式——把Map当作非受控组件使用（配合新的initialViewStateprop），或者在需要外部管理相机状态（例如 Redux）时改用onMove回调同步状态。相关模式见 docs/get-started/state-management.md。
• 所有transition*props：改用map.easeTo()与map.flyTo()，参考示例 examples/mapbox/viewport-animation。
• mapOptions：原生Map类的几乎所有选项现在都直接作为 props 暴露。
• onHover：改用onMouseMove或onMouseEnter。
• 所有交互回调的事件参数格式都发生了变化，详情见文档。
• getCursor：作为让Map与原生组件行为一致的一部分被移除。设置光标请使用cursorprop；动态改变光标的做法参考示例 examples/mapbox/custom-cursor。
• touchAction与eventRecognizerOptions：改用cooperativeGesturesprop。

其他组件

• 所有capture*props 被移除。
• 所有*labelprops 被移除，改用Map的localeprop。
• 所有地图控件的 props 现在严格对齐 mapbox-gl 的对应控件。这一方向让 react-map-gl 删去了大量自定义代码，使组件对从原生库迁移过来的开发者更可预测。如果你的应用依赖某个已不再支持的旧特性，建议在项目讨论区（Discussion）发起讨论，维护者会逐案评估。

升级到 v5.3 / v6.1

• MapContext成为正式 API。实验性的_MapContext导出将在未来版本移除。
• react-virtualized-auto-sizer不再是依赖。
• 地图控制器的惯性（inertia）默认开启。要恢复之前版本的行为，通过 interaction options 显式关闭：

const CONTROLLER_OPTS = { dragPan: {inertia: 0}, dragRotate: {inertia: 0}, touchZoom: {inertia: 0} }; <MapGL {...CONTROLLER_OPTS} ... />

• Source与Layer组件不再通过ref暴露命令式方法——这是向函数式组件迁移的一部分，符合最新 React 推荐的写法：
  • 如果你曾调用sourceRef.getSource()，可替换为mapRef().getMap().getSource(sourceId)
  • 如果你曾调用layerRef.getLayer()，可替换为mapRef().getMap().getLayer(layerId)

升级到 v6

• 有效的 Mapbox access token 现在始终必需（不再支持无 token 运行）。
• InteractiveMap的maxPitch默认值从60改为85。这一默认值在 v7 的重写中延续了下来，当前源码的DEFAULT_SETTINGS里同样是maxPitch: 85（modules/react-mapbox/src/mapbox/mapbox.ts）。
• mapbox-glv2 引入了构建系统的破坏性变更：把 mapbox-gl v2 纳入转译（transpile）范围可能导致生产构建崩溃，报错信息为m is not defined。通用解法是在构建工具中把mapbox-gl排除在转译之外（例如 webpack 的transpileDependencies/ babel 的exclude配置）。

升级到 v4

• onChangeViewport被移除，改用onViewportChange。
• Immutable.js不再是依赖。
• 导出项experimental.MapControls被移除，改用MapController。
• InteractiveMap的mapControlsprop 重命名为controller。
• 移除对图层样式中已废弃interactive属性的支持。请改用interactiveLayerIdsprop 指定哪些图层可点击——这一机制在 v7 中同样存在：interactiveLayerIds仍是Map的 prop，源码中用于过滤queryRenderedFeatures的查询范围（modules/react-mapbox/src/mapbox/mapbox.ts、modules/react-mapbox/src/mapbox/mapbox.ts）。

升级到 v3.2

• 最新版 mapbox-gl 要求始终包含样式表（stylesheet）。样式引入方式见 docs/get-started/get-started.md。
• Immutable.js 不再是硬依赖，并将在下一个主版本中移除。如果你的应用中有直接 import immutable，建议在应用依赖中显式列出。

升级到 v3

v3 是 react-map-gl 的一次主版本大升级。虽然变更与移除的功能大多经历了温和的废弃（deprecation）过程，但仍有若干无法避免的破坏性变更。

版本要求

• 构建react-map-gl 的 Node 版本要求为>= v6.4.0（由 mapbox-gl JS v0.38.0 引入）。使用预构建版本没有此限制。

MapGL 组件

• 两个地图组件：v3 将 Map 组件拆分为StaticMap与InteractiveMap。InteractiveMap是默认导出，设计上尽可能兼容 v2 的默认组件。

onChangeViewport回调现在包含width和height

传给onChangeViewport回调的viewport参数现在包含width与height。如果应用代码把viewport与width/height组合使用，可能需要更新——请检查依赖该行为的渲染代码：

// BAD: 'width' 和 'height' 会被 'viewport' 对象中的值覆盖 <ReactMapGL width={500} height={400} {...viewport} /> // GOOD: 'width' 和 'height' 会覆盖 'viewport' 中的值 <ReactMapGL {...viewport} width={500} height={400} />

Overlays

• 部分 Overlay 移入示例：使用频率较低的 overlay（DraggablePointsOverlay、ChoroplethOverlay、ScatterplotOverlay）被移到 examples 中。大多数用户现在使用 mapbox 样式或 deck.gl 图层，移除这些 overlay 可以为多数用不到它们的用户减小库体积。如果仍在用，直接把 overlay 源文件复制进你的应用即可。
• Overlay 必须是 Map 的子节点：overlay 现在必须渲染为react-map-gl主组件的子节点，才能自动与地图视口同步。

fitBounds工具函数

fitBounds工具函数移到了 math.gl 库（viewport-mercator-project包）。调用方式变为：

import WebMercatorViewport from 'viewport-mercator-project'; const viewport = new WebMercatorViewport({width: 600, height: 400}); const bound = viewport.fitBounds( [[-73.9876, 40.7661], [-72.9876, 41.7661]], {padding: 20, offset: [0, -40]} ); // => bounds: instance of WebMercatorViewport // {longitude: -73.48760000000007, latitude: 41.268014439447484, zoom: 7.209231188444142}

废弃的 props

以下 React props 开始进入废弃流程。这些旧props仍可用（控制台会有警告），但很可能在下一个主版本中移除，建议尽快改用新props：

升级到 v2

v2 与 v1 API 兼容。但如果仍在使用 v1，请确认先完成以下升级：

• Node 版本升到v4或更高
• React 版本升到15.4或更高

背景：mapbox-gl0.31.0 引入了对 Node >= v4 的硬依赖。

升级到 v1

（从 0.6.x 升级）

• Overlay 导入方式变化：地图 overlay 组件（HTMLOverlay、CanvasOverlay、SVGOverlay等）改为具名导出（named exports），不再需要通过相对源路径导入：

// v1.0 import MapGL, {SVGOverlay} from 'react-map-gl'; // v0.6 import MapGL from 'react-map-gl'; import SVGOverlay from 'react-map-gl/src/api-reference/svg-overlay';

• 地图状态变化：onViewportChanged报告的地图状态现在包含额外字段——不仅跟踪透视模式需要的pitch与bearing，还包含投影如何被用户改变的瞬态信息。这些信息必须在下次渲染时传回 react-map-gl 组件。为简化和面向未来，建议每当状态变化时把整个mapState存入应用 store，然后整体传回组件，而不是分别跟踪longitude、latitude、zoom等单个字段。

版本迁移速查表

升级操作建议

1. 先确定目标入口：根据底层地图库及版本，确定使用react-map-gl/mapbox、react-map-gl/mapbox-legacy还是react-map-gl/maplibre，这是 v8 升级的第一决策点；仓库中 modules/react-mapbox、modules/react-maplibre 与 modules/main/src/mapbox-legacy 分别对应三条实现路径，可作为对照阅读的起点。
2. 按依赖关系自底向上迁移：先处理Map组件（props 重命名、mapStyle显式化、视口模式选择），再处理Source/Layer，最后处理各控件组件——因为控件 props 在 v7 起严格对齐原生库，Map不先改好，控件层容易连环报错。
3. 用类型检查兜底：v7 起项目完全类型化，升级后跑一遍 TypeScript 编译，类型重命名（v8）与 props 移除（v7）的大多数问题会直接以编译错误形式暴露出来，例如 v7 示例中maplibreLogo在 Mapbox 类型下的报错就是典型案例。
4. 关注仓库示例：examples/mapbox与examples/maplibre目录下的 custom-overlay、viewport-animation、custom-cursor 等示例覆盖了 v7 移除项的主要替代方案，可直接作为迁移参照。

• 前端
• UI组件