GIS研习社 GIS研习社
WebGIS

OpenLayers 安装与 CDN、npm 引入方式

WebGIS
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

OpenLayers 安装最稳妥的做法是用 npm 安装官方包 ol（命令 npm install ol），再配合 Vite、webpack 等打包工具按需引入模块；这是官方推荐、适合正式项目的方式。截至 2026 年 11 月，最新稳定版为 v10.11.0（2026 年 10 月 4 日发布）。临时演示或快速原型可用 CDN 引入完整构建，但官方明确不推荐用于生产。新项目可直接用 npm create ol-app 脚手架起步。

OpenLayers 地图运行效果示意

用 npm 安装并模块化引入（推荐）

正式 GIS 项目优先走 npm，这样只打包真正用到的模块，体积可控，也方便配合 TypeScript。包名是 ol，安装后自带 *.d.ts 声明文件。

  1. 确认本机已安装 Node.js 14 或更高版本，并装好 git（脚手架需要）。
  2. 在现有项目根目录执行：npm install ol。
  3. 在入口 JS/TS 里按需导入，例如：
    • import Map from ‘ol/Map.js’;
    • import View from ‘ol/View.js’;
    • import TileLayer from ‘ol/layer/Tile.js’;
    • import OSM from ‘ol/source/OSM.js’;
    • 样式：import ‘ol/ol.css’;（或在 CSS 里 @import “ol/ol.css”;）
  4. 用 Vite、Rollup、webpack 或 Parcel 构建；官方提供对应示例仓库，一般执行 npm run build 得到 dist。

包声明了 “type”: “module”，请按 ES 模块方式写导入。完整步骤与示例可对照官方 OpenLayers Quickstart 文档。

用 CDN 快速引入（仅开发测试）

没有打包环境时，可用 jsDelivr 托管的完整构建做原型。官方在下载页写明：完整构建省略了 geotiff、ol-mapbox-style 等依赖，且不推荐用于生产。使用全局命名空间 ol.，不能写 ES import。

当前版本示例（v10.11.0）：

  • 脚本：<script src=”https://cdn.jsdelivr.net/npm/ol@10.11.0/dist/ol.js”></script>
  • 样式：<link rel=”stylesheet” href=”https://cdn.jsdelivr.net/npm/ol@10.11.0/ol.css”>

页面里写 new ol.Map({…})。旧版 github.io 托管路径因仓库体积超限常会 403/404，请改用 npm 版本号路径，或从官网下载后本地托管。版本与压缩包说明见 OpenLayers 官方下载页。

OpenLayers 官方下载页，可获取当前版本包与 CDN 说明
OpenLayers 官方下载页，可获取当前版本包与 CDN 说明（截图来源：openlayers.org）

新项目脚手架与运行环境

从零开始最快的方式：

  1. npm create ol-app my-app
  2. cd my-app
  3. npm start（默认 Vite 开发服务器）

需要 Node.js 14+ 与 git。浏览器方面，OpenLayers 面向全球使用率超过 1% 的现代浏览器（Chrome、Firefox、Safari、Edge），桌面与移动（指针/触摸）均可；默认 Canvas 渲染，也支持 WebGL。极旧环境（如 IE9+、Android 4.x）需自行加 polyfill（requestAnimationFrame、classList、fetch、URL 等）并可能配合 Babel 转译，一般生产项目可忽略。

对比项 npm + 打包 CDN 完整构建
适用场景 正式项目、按需模块 原型、课堂演示
体积与性能 只打包用到的模块，更优 完整包较大，官方不推荐生产
引入写法 ES import … from ‘ol/…’ 全局 ol.Map 等
样式 必须引入 ol/ol.css 同样必须引入 ol.css
依赖完整性 按需加 geotiff 等 默认省略部分依赖，需额外脚本

地图容器必须有明确非零宽高，例如 #map { width: 100%; height: 400px; }；若用百分比高度，请保证 html、body 及父级也有高度，否则地图空白。

验收标准与升级注意

装好后按下面几条自检即可认为引入成功：

  • 页面出现地图底图（如 OSM），缩放控件样式正常（说明 ol.css 已加载）。
  • 控制台无 “map container’s width or height are 0” 警告。
  • npm 方式下能正常 tree-shaking；CDN 方式下能用 ol. 前缀创建 Map/View。
  • 隐藏/显示容器后调用 map.updateSize()，地图尺寸正确刷新。

升级到 v10.11.0 时留意 changelog 中的破坏性变更（如 GeoJSON 空坐标、颜色插值空间、WMTS extent 等行为调整）。许可证为 BSD 2-Clause，可放心用于商业与开源项目。完整构建也可从 releases 下载 v10.11.0-package.zip / site.zip 后本地引用。

常见问题

地图空白，控制台提示容器宽高为 0？

容器实际宽高为 0（常见于相对高度 % 但父元素无高度，或从旧版升级后布局变化）。给 #map 设明确 px 高度，或让 html/body/#map 均为 height:100%，容器显示后再调用 map.updateSize()。

CDN 旧链接 403/404 怎么办？

github.io@master 一类路径因仓库超过 jsDelivr 体积限制已失效。改用 cdn.jsdelivr.net/npm/ol@版本号/…，或下载官方 package 后本地托管。

能一边用 CDN 一边写 import 吗？

不能。CDN 是 UMD 全局 ol，import 是 ES 模块写法。二选一：要么去掉 import 改用 ol. 前缀，要么改用 npm 安装走打包。

生产环境为什么不要直接用 CDN 完整包？

完整构建体积大且省略部分依赖，无法按需裁剪。生产请用 npm 安装 ol，用打包工具只引入实际模块，再部署自己的 dist。

总结：日常开发与上线请用 npm install ol 并按模块导入，配合 ol.css 与非零高度容器；仅做快速演示时才用 jsDelivr CDN，且勿混用两种写法。建议先按脚手架跑通一个 OSM 底图示例，确认验收标准全部通过后再接入业务图层与服务。