OpenLayers 从零创建第一个地图页面
要用 OpenLayers 从零创建第一个地图页面，最快的做法是安装官方 npm 包 ol（截至 2026 年 11 月最新稳定版为 v10.11.0），准备一个带明确宽高的 HTML 容器，再用 Map、View、TileLayer 和 OSM Source 几行代码即可渲染可交互的 OSM 底图。默认投影为 EPSG:3857，中心点用投影坐标，容器必须设置 CSS 高度，否则会空白。新手直接用官方脚手架 npm create ol-app 可一键生成可运行项目。
OpenLayers 核心组件：创建地图前先弄清这四块
OpenLayers 是免费开源的 JavaScript 库（2-clause BSD License），专门用来在网页上放交互式动态地图，支持瓦片、矢量、标记，桌面和移动端都能用。创建任何一个地图页面，本质上就是把四个核心对象拼在一起：
- Map：地图实例本身，必须指定 target（HTML 容器 id）、至少一层 Layer，以及一个 View。
- View：控制中心点、缩放级别、旋转和投影，默认 EPSG:3857（球面墨卡托）。
- Layer：常见如 TileLayer（栅格瓦片）、VectorLayer（矢量）。
- Source：数据来源，OSM、XYZ、WMS、GeoJSON 等都行。
官方把这些概念写得很清楚，可先看一遍 OpenLayers 基础概念教程，再动手会少走很多弯路。地图容器是普通 div，但必须用 CSS 给它固定高度（或 absolute 填充），否则渲染出来就是空白。
环境准备与安装方式怎么选
开发环境最低要求：Node.js 14 或更高版本，以及 git（脚手架会用到）。浏览器覆盖所有全球使用率超过 1% 的现代浏览器（Chrome、Firefox、Safari、Edge），从 v7 起已不再支持 IE。生产环境推荐用模块打包，开发试用才考虑完整构建。
| 方式 | 适用场景 | 优点 | 注意点 |
|---|---|---|---|
| npm 包 ol + Vite 脚手架 | 正式项目、学习推荐 | 自动配置、ES 模块、热更新、体积可控 | 需要 Node 环境 |
| CDN / 完整构建 ol.js | 快速原型、无 Node 临时试用 | 引入即用，全局 ol 命名空间 | 不推荐生产；部分依赖需额外加载 |
生产首选 npm：新项目直接跑脚手架，现有项目执行 npm install ol。完整构建文件可到官网下载页获取对应版本的 zip。无论哪种方式，都要记得引入 ol/ol.css，否则默认控件样式会乱。
用官方脚手架从零跑出第一个地图（推荐步骤）
这是官方 Quick Start 推荐路径，几分钟就能看到地图，适合想马上验收效果的学习者。
- 打开终端，执行 npm create ol-app my-app（把 my-app 换成你喜欢的目录名）。
- 进入目录：cd my-app，然后 npm start。Vite 开发服务器会自动打开浏览器。
- 打开生成的 index.html，确认里面有一个 <div id=”map” class=”map”></div>。
- 打开 main.js，里面已经是最简地图代码：导入 Map、View、TileLayer、OSM，然后 new Map 指定 target、layers 和 view（center [0, 0]，zoom 2）。
- 打开 style.css，给 .map 设置宽高，例如 width: 100%; height: 400px;（或 height: 100vh）。保存后页面热更新，应立刻看到 OSM 世界地图。
- 需要打包上线时执行 npm run build，产物在 dist/ 目录。
脚手架已经帮你装好 OpenLayers 和开发服务器，生成的代码就是官方 Simple Map 的精简版。想对照完整示例可直接参考 OpenLayers 官方 Quick Start 文档。验收标准很简单：浏览器里能看到瓦片、鼠标滚轮可缩放、拖拽可平移、控制台无报错。
手写最简代码时必须盯住的细节
如果不用脚手架，自己写 HTML + JS，核心也只要这几步，但细节容易踩坑。
- HTML 里放一个空 div，id 设为 map，并在 CSS 里写死高度（最常见遗漏）。
- 用 ES 模块导入：Map 来自 ol/Map.js，View 来自 ol/View.js，TileLayer 来自 ol/layer/Tile.js，OSM 来自 ol/source/OSM.js。
- new Map 时传入对象：target 写容器 id，layers 数组里放 new TileLayer({ source: new OSM() })，view 里写 new View({ center: [0, 0], zoom: 2 })。
- 如果想用经纬度当中心，必须先 import { fromLonLat } from ‘ol/proj.js’，再写 center: fromLonLat([经度, 纬度])，否则位置会偏到海里去。
- 脚本标签要加 type=”module”，或者用 Vite / webpack 等打包工具处理裸导入。
本地预览千万别直接双击用 file:// 协议打开，很容易触发 CORS 导致瓦片加载失败。用脚手架的 npm start，或自己起一个简单 HTTP 服务即可。
常见问题
地图完全空白，什么都不显示？
九成是容器没有高度或宽度。给 #map 写 CSS（height: 400px 或 100vh）立刻见效。其次检查是否用了模块导入却没配 bundler，或 View 的 center/resolution 没定义。用本地 HTTP 服务而不是 file:// 打开页面。
瓦片加载失败或控制台报 CORS？
本地 file 协议最容易中招。改用 Vite 开发服务器或 python -m http.server。跨域瓦片源可在 Source 上设 crossOrigin: ‘anonymous’。OSM 默认已处理，一般脚手架环境不会出问题。
中心点位置完全不对？
默认投影是 EPSG:3857，单位是米。直接塞经纬度数组会偏到错误位置。用 fromLonLat 把 [lon, lat] 转成投影坐标后再赋给 View 的 center。
npm 导入报 relative module specifier 之类错误？
裸导入（import … from ‘ol/…’）必须经过打包工具解析。跟着官方脚手架用 Vite，或改用完整构建的全局 ol.Map 写法做临时测试。
总结：从零创建第一个 OpenLayers 地图页面，优先用 npm create ol-app 脚手架，确保容器有明确高度并引入 ol.css，再用 Map + OSM TileLayer + View 三件套即可验收。建议先跑通官方 Quick Start 再按需加矢量图层或自定义投影，遇到空白先查高度和本地服务协议，这两步能解决绝大多数入门问题。