企业官网建设流程全解析

• 前端
• UI组件

本文以 react-map-gl 仓库中的 Globe 示例（examples/maplibre/globe）为主体，完整还原并讲解如何用react-map-gl/maplibre的一行projection属性把默认墨卡托平面地图切换为 3D 地球仪视图。读完你不仅能照抄示例一键跑起来，还能理解projection、maxPitch、initialViewState等关键属性背后的默认值、底层setProjection调用链，以及 MapLibre GL JS v6 强制要求的 worker 配置方式。

示例定位：复现 Maplibre 官方 Globe 示例

examples/maplibre/globe/README.md对该示例的定位只有一句话：本应用复现了 Maplibre 官方的 globe 示例。在 React 生态中，MapLibre GL JS 自 v4.2 起在样式规范中引入了projection字段，支持mercator、globe以及自定义投影；react-map-gl 8.x 通过Map组件的projectionprop 直接透传这一能力，使得"把世界画成地球仪"在 React 里不需要任何命令式代码，只需声明式地写一个属性：

<Map initialViewState={{latitude: 0, longitude: 0, zoom: 0}} maxPitch={85} mapStyle="https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json" projection="globe" />

这也是本示例 src/app.tsx 的全部核心代码（完整文件仅 27 行）。

项目结构与运行方式

示例是一个独立的 Vite 子项目，目录结构如下：

• examples/maplibre/globe/index.html — 入口页面，负责配置 worker、引入样式、挂载 React 应用；
• examples/maplibre/globe/src/app.tsx — 地图组件与渲染入口；
• examples/maplibre/globe/src/control-panel.tsx — 右上角说明面板（纯展示，无交互逻辑）；
• examples/maplibre/globe/package.json — 依赖与脚本定义。

依赖版本

从 package.json 看，示例锁定了一组关键依赖：

{ "dependencies": { "maplibre-gl": "^6.0.0", "react": "^18.0.0", "react-dom": "^18.0.0", "react-map-gl": "^8.0.0" }, "devDependencies": { "typescript": "^6.0.3", "vite": "^8.2.0" } }

需要注意maplibre-gl ^6.0.0与react-map-gl ^8.0.0的组合：react-map-gl 8.x 对 MapLibre v6 提供了setProjection等 API 的适配（源码中可见map.setProjection?.(...)的可选链调用），如果你使用更低版本的 maplibre-gl，globe 投影可能不可用或行为不同。

运行命令

按 README 给出的方式运行：

cd examples/maplibre/globe npm i npm run start

其中start脚本实际是vite --open，即启动 Vite 开发服务器并自动打开浏览器。仓库还提供了一个备用脚本start-local（vite --config ../../vite.config.local.js），用于以本地源码方式构建 react-map-gl 而非 npm 发布版本，适合在修改 modules/react-maplibre 源码后本地联调。

入口文件：worker 配置是 MapLibre v6 的硬性要求

globe/index.html 中的<script type="module">部分值得逐行理解：

<script type="module"> import {setWorkerUrl} from 'maplibre-gl'; import 'maplibre-gl/dist/maplibre-gl.css'; import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'; import {renderToDom} from './src/app.tsx'; setWorkerUrl(workerUrl); renderToDom(document.getElementById('map')); </script>

关键点：

1. setWorkerUrl必须在渲染地图前调用。官方 API 文档 docs/api-reference/maplibre/map.md 明确指出："MapLibre GL JS v6 中使用打包器的应用，必须在渲染地图前配置 worker"。示例利用 Vite 的?worker&url导入语法生成 worker 地址，这是当前推荐的打包器集成方式。
2. #map容器样式在<style>中定义为width: 100vw; height: 100vh，让地球仪占满整个视口。
3. renderToDom(document.getElementById('map'))调用的正是 src/app.tsx 中导出的renderToDom函数，它用createRoot(container).render(<App />)挂载 React 应用——这是一种不依赖框架入口文件的轻量挂载方式。

示例源码逐行讲解：src/app.tsx

import * as React from 'react'; import {createRoot} from 'react-dom/client'; import {Map} from 'react-map-gl/maplibre'; import ControlPanel from './control-panel'; export default function App() { return ( <> <Map initialViewState={{ latitude: 0, longitude: 0, zoom: 0 }} maxPitch={85} mapStyle="https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json" projection="globe" /> <ControlPanel /> </> ); } export function renderToDom(container) { createRoot(container).render(<App />); }

projection="globe"：把平面地图变成地球仪

projection是开启本示例效果的核心属性。按 docs/api-reference/maplibre/map.md 的定义，它接受string或 Projection 对象两种形式，默认值为'mercator'。取值"globe"时，MapLibre 会使用 Web Mercator 球面投影渲染，世界呈现为一个可旋转、可拖动的 3D 球体；此时地球边缘会有自然的弧形过渡，而不是平面地图的矩形边界。

projection也支持传入完整的 Projection 对象（如 `{type: 'globe'}），react-map-gl 会在内部把字符串形式归一化为该对象格式（后文源码部分会给出证据）。

maxPitch={85}：为球面视角预留最大俯仰角

pitch是相机相对屏幕平面的俯仰角。官方文档中maxPitch的默认值是 60，而 globe 视图在极端俯仰下需要接近正射（从上往下"看地球"）的视角，因此示例把它放宽到 85（0–85 为合法区间）。如果不设置这一项，用户在地球仪视图里拖拽倾斜时会在 60 度处被"卡住"，无法获得完整的球面观察体验。

mapStyle：基底样式决定地球长什么样

mapStyle既可以是符合 MapLibre Style Specification 的 JSON 对象，也可以是 JSON 的 URL。示例选择了 CARTO 的 Voyager 样式（一个偏明快风格的全球底图），作为 URL 传入后由 MapLibre 自行加载。换成任何支持 globe 投影的样式 URL 或本地 style.json 风格的对象即可更换"地球皮肤"。

initialViewState：非受控模式的初始相机

initialViewState指定地图的初始经纬度与缩放：latitude: 0, longitude: 0, zoom: 0即赤道本初子午线交叉点、全球视野，这正是看地球仪最自然的起点。

官方文档特别强调：只有当Map作为非受控组件使用时才应指定initialViewState；若同时传入longitude/latitude/zoom等受控 props，前者会覆盖后者。本示例没有绑定任何onMove回调，属于典型的非受控用法——相机状态完全交给地图内部维护，React 侧零状态管理。

ControlPanel 的作用

src/control-panel.tsx 用React.memo包裹一个纯展示组件，渲染在index.html中定义好的.control-panel绝对定位容器上，内容仅有一句 "Use globe projection." 说明。它展示了 react-map-gl 示例的通用 UI 约定：说明面板与地图平级渲染在同一个 React 树中，通过 CSS 悬浮在地图之上。

关键属性速查表

结合 docs/api-reference/maplibre/map.md 与示例代码，本例涉及属性的完整说明如下：

源码级实现：projection在 react-map-gl 内部如何生效

以下分析基于modules/react-maplibre的实际源码，用于回答两个问题：属性默认值从哪里来、React 属性变化如何落到 MapLibre 的setProjection调用。

1. 默认投影是 mercator：DEFAULT_SETTINGS

在 modules/react-maplibre/src/maplibre/maplibre.ts 中，Maplibre包装类维护了一份默认设置：

// maplibre.ts (DEFAULT_SETTINGS 片段) projection: 'mercator',

即如果不传projection，地图始终按墨卡托平面渲染；示例显式传入"globe"正是为了覆盖这个默认值。

2. 地图实例的创建：map.tsx

<Map>组件本身并不直接 new 出地图，而是在useEffect中先解析底图库，再委托给Maplibre包装类：

// components/map.tsx (第 49、67 行附近) Promise.resolve(mapLib || import('maplibre-gl')) .then((module) => { // ... 校验 module.Map setGlobals(mapboxgl, props); // ... maplibre = new Maplibre(mapboxgl.Map, props, containerRef.current); });

这说明两件事：react-map-gl/maplibre入口在默认情况下会动态import('maplibre-gl')（示例无需显式mapLibprop，因为入口 HTML 已把库加载进页面，而组件内动态导入的是同版本模块）；以及每次 props 更新都会经由useIsomorphicLayoutEffect(() => mapInstance.setProps(props))推给包装类，进入下一节的更新流程。

3. 属性变更到 setProjection 的两条更新路径

在 modules/react-maplibre/src/maplibre/maplibre.ts 中，从源码结构看，projection被纳入了两条更新路径：

路径一：常规设置更新（_updateSettings）。有一组"可通过同名 setter 即时更新"的属性清单：

// maplibre.ts 第 173 行 const settingNames = ['maxBounds', 'projection', 'renderWorldCopies'] as const;

_updateSettings遍历该清单，当检测到projection在前后两次 props 间发生变化（deepEqual比较）时，按命名约定动态调用对应的 setter：

// maplibre.ts 第 488–498 行（简化） private _updateSettings(nextProps, currProps): boolean { for (const propName of settingNames) { const propPresent = propName in nextProps || propName in currProps; if (propPresent && !deepEqual(nextProps[propName], currProps[propName])) { const nextValue = propName in nextProps ? nextProps[propName] : DEFAULT_SETTINGS[propName]; const setter = map[`set${propName[0].toUpperCase()}${propName.slice(1)}`]; setter?.call(map, nextValue); // 即 map.setProjection(...) } } // ... }

这里值得注意的细节：当某属性在nextProps中被移除时，会回落到DEFAULT_SETTINGS中的值——对projection来说就是'mercator'。这意味着如果你在受控场景中把projectionprop 从"globe"改为不传，地图会自动切回墨卡托，而不是保留旧投影。

路径二：样式组件延迟更新（_updateStyleComponents）。源码注释解释了为何light、projection、sky、terrain四者要单独处理："它们不能立即应用，必须满足特定条件（样式已加载、数据源已加载等），且可能被 mapStyle 覆盖"。对应实现：

// maplibre.ts 第 527–544 行（简化） private _updateStyleComponents({light, projection, sky, terrain}): void { const map = this._map; const currProps = this._styleComponents; // 只有样式加载完成后才安全操作 if (map.style?._loaded) { // ... if ( projection && !deepEqual(projection, currProps.projection) && projection !== currProps.projection?.type ) { currProps.projection = typeof projection === 'string' ? {type: projection} : projection; // @ts-ignore setProjection does not exist in v4 map.setProjection?.(currProps.projection); } } }

这段代码同时解释了三件事：

1. 字符串归一化：typeof projection === 'string' ? {type: projection} : projection——这正是文档所说"projection接受 string 或 Projection 对象"的底层实现；
2. 去重判断：projection !== currProps.projection?.type防止 MapLibre 在样式对象中回读出的投影配置触发无意义的重复设置；
3. 版本兼容：setProjection?.()的可选链调用表明该方法在 maplibre-gl v4 中不存在，代码层面做了向前兼容，但实际使用 globe 仍需要支持该 API 的 maplibre-gl 版本（示例锁定 v6）。

4. 渲染容器的挂载细节

回到 map.tsx，组件返回的容器 div 会合并默认样式{position: 'relative', width: '100%', height: '100%', ...props.style}，并在地图实例就绪后把children（示例中没有，但ControlPanel是平级兄弟节点）渲染进一个内部子容器。示例的全屏效果由此链式成立：#map（100vw/100vh）→ Map 容器（100%/100%）→ 地图 canvas。

实践要点与常见调整

1. 切换回平面地图：把projection改为"mercator"或直接移除该 prop（依据上文_updateSettings的回落逻辑，移除后同样会回到'mercator'），这是 react-map-gl 中"受控切换投影"的标准做法，无需销毁重建地图。
2. globe + terrain 的组合：仓库中还提供了 examples/maplibre/terrain 示例，terrain与projection同属_updateStyleComponents管理的样式组件，两者都要求底层样式加载完成后才应用，组合使用时注意数据源（DEM）与样式的配合。
3. 受控模式的差异：本示例是非受控用法。若需要监听相机（例如在地球仪上读取当前经纬度），应改为受控模式并绑定onMove/onMoveEnd回调，参考 docs/get-started/state-management.md 的示例；此时initialViewState不再适用，改用longitude/latitude/zoom等受控 props。
4. worker 配置不可省略：使用 maplibre-gl v6 时，若未像 globe/index.html 那样在渲染前调用setWorkerUrl，地图将无法初始化。这是 v6 相对旧版本的关键行为变化，升级 maplibre-gl 时是高频踩坑点。

小结

Globe 示例用不到 30 行 React 代码演示了 react-map-gl 与 MapLibre GL JS 在投影能力上的完整协作面：projection="globe"一行开启地球仪视图，maxPitch={85}补足球面视角的俯仰上限，mapStyle与initialViewState决定外观与起点，入口 HTML 中的setWorkerUrl满足 v6 的 worker 强制要求。而 modules/react-maplibre/src/maplibre/maplibre.ts 中的DEFAULT_SETTINGS、settingNames与_updateStyleComponents则展示了这套声明式属性在底层如何经由setProjection落到原生 Map 实例——理解这条链路后，无论是投影切换、与地形组合还是版本升级排查，都有了明确的源码依据。

• 前端
• UI组件