MapLibre GL JS 入门:npm 安装与第一个地图
MapLibre GL JS 用 npm 安装后即可在浏览器里用 WebGL 渲染矢量瓦片交互地图:执行 npm install maplibre-gl,再导入 Map 与 CSS,用 new Map 指定容器、样式、中心和缩放就能显示第一张图。截至 2026 年 11 月,最新稳定版是 6.16.0(2026 年 10 月 25 日发布),仅提供 ESM,必须 WebGL2,官方 demotiles 样式无需 API key。下面按「安装 → 出图 → bundler 配置 → 验收」给出可执行步骤。

用 npm 安装 MapLibre GL JS
要解决的问题很直接:把库装进项目,并正确拿到 ESM 入口和样式表。v6 起包声明为 “type”: “module”,无默认导出、无 UMD/CommonJS,Node 需 ≥16.14.0、npm ≥8.1.0。
- 在项目根目录执行:npm install maplibre-gl。
- 在入口脚本中命名导入:import { Map, setWorkerUrl } from ‘maplibre-gl’;(或 import * as maplibregl from ‘maplibre-gl’;)。
- 同步导入样式:import ‘maplibre-gl/dist/maplibre-gl.css’;。不导入 CSS,Marker、Popup 等 DOM 控件会错位或看不见。
- 确认主模块路径为 dist/maplibre-gl.mjs,worker 为 dist/maplibre-gl-worker.mjs。可在 GitHub 上的 package.json 核对当前 engines 与入口字段。
若暂时不用打包器、只想快速试效果,可用 <script type=”module”> 从 unpkg 加载并 pin 主版本(例如 @^6.16.0),同时用 link 引入同版本 CSS;不要用 @latest,否则容易空白图加 404。
写出第一个地图:容器、样式与初始化
目标:页面上出现可缩放、可平移的底图,并确认 load 事件能触发。容器必须有明确高度,否则地图区域高度为 0,看起来是空白。
- HTML 放一个容器:<div id=”map”></div>,用 CSS 设高度,例如 #map { height: 400px; } 或父级满屏时用 height: 100%。
- 在脚本里创建实例(CDN 场景可省略 setWorkerUrl):new Map({ container: ‘map’, style: ‘https://demotiles.maplibre.org/style.json’, center: [0, 0], zoom: 1 })。也可用 globe.json。这是官方 Quickstart 与 “Display a map” 示例用的免费样式,无需密钥。
- 可选参数:maplibreLogo: true 显示库标识;需要时再监听 map.on(‘load’, …) 做后续图层操作。
- 用 try-catch 包住构造函数,或监听 map.on(‘error’),以便捕获 WebGL 不可用等情况。
- 验收标准:页面出现底图、滚轮缩放与拖拽平移正常、控制台无 worker 404、load 能触发。
- 若只用栅格层能部分显示而矢量层不显示,优先怀疑 worker 未正确加载(见下一节)。

Bundler 里必须配置 Worker(Vite / webpack 等)
v6 使用 ESM worker。CDN 一般能自动检测;用 Vite、webpack、esbuild、Rollup、Next.js(Turbopack)等打包时,必须在创建第一个 Map 之前调用一次 setWorkerUrl,否则常见现象是整图空白或灰色、load 不触发,控制台可能看到 worker 相关 404。
- Vite 示例思路:import workerUrl from ‘maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url’; 然后 setWorkerUrl(workerUrl);
- webpack 等:setWorkerUrl(new URL(‘maplibre-gl/dist/maplibre-gl-worker.mjs’, import.meta.url).toString()); 必要时把 worker 文件复制到输出目录并保证可被同源访问。
- SSR 框架(如 Next.js)务必在客户端再 new Map,不要在服务端渲染阶段初始化。
- 严格 CSP 时建议 worker-src ‘self’;(自托管 worker)或 worker-src ‘self’ blob:;(CDN),并配合 img-src data: blob: ‘self’;;也可显式 setWorkerUrl 到同源路径。
本地直接用 file:// 打开 HTML 时,worker 常因 origin 限制失败,请改用本地开发服务器验证。
环境要求与版本对照
动手前先对照下表,避免装错入口或跑在不支持的环境上。版本信息以官方发布为准,可在 MapLibre GL JS Releases 查看变更说明。
| 项目 | 要求 / 说明 |
|---|---|
| 最新版本(截至 2026-11) | 6.16.0(2026-10-25);此前有 6.15.0、6.14.0;v6.0.0 于 2026-07-22 |
| 模块形态 | 仅 ESM(maplibre-gl.mjs);无默认导出;不可 require() |
| 运行时 | Node ≥16.14.0,npm ≥8.1.0;浏览器需 WebGL2 |
| WebGL1 | v6 已移除;不支持时 Map 构造抛出 GPUInitializationError |
| 样式来源 | 推荐 demotiles.maplibre.org 免费样式;第三方如 MapTiler 通常需 key |
| CSS | 必须引入 dist/maplibre-gl.css,否则控件样式失效 |
从 v5 升级时,重点改导入方式、补 setWorkerUrl、确认 WebGL2,并查阅官方 v5→v6 迁移说明中的事件与 GeoJSON 嵌套属性变化。
常见问题
地图一片空白或灰色,控制台几乎没报错?
多数是 bundler 未配置 setWorkerUrl,导致 maplibre-gl-worker.mjs 加载失败。按上一节为 Vite/webpack 设置 worker,并确认文件被正确输出与同源服务;CDN 请 pin 版本不要用 @latest。
import maplibregl from ‘maplibre-gl’ 报错或 require 失败?
v6 无默认导出,也没有 CommonJS 入口。改用 import { Map } from ‘maplibre-gl’ 或 import * as maplibregl from ‘maplibre-gl’;require 会触发 ERR_PACKAGE_PATH_NOT_EXPORTED。
构造 Map 时抛出 GPUInitializationError?
当前环境不支持 WebGL2。用 try-catch 捕获该错误(可用 instanceof),给用户友好提示;现代桌面与移动浏览器一般已支持,可参考官方 “Check if WebGL is supported” 示例思路做探测。
Marker / Popup 位置乱或看不见?
几乎都是漏了 CSS。确认已 import ‘maplibre-gl/dist/maplibre-gl.css’ 或通过 link 引入同版本样式;同时检查容器高度是否为 0。
总结:用 npm 安装 maplibre-gl,导入 ESM 的 Map 与 CSS,给容器固定高度,用 demotiles 样式即可出第一张图;打包环境务必在创建 Map 前调用 setWorkerUrl,并确认 WebGL2 可用。建议先在本地开发服务器跑通官方 demotiles 示例,再换成自己的样式与业务图层;升级或核对版本时直接查看官方 Releases 与 package.json,避免跟错入口。