本地运行 OpenLayers 官网示例的方法
要本地运行 OpenLayers 官网示例，最直接的做法是下载官方预构建的 site 包（当前稳定版为 v10.11.0，含示例与文档），解压后用任意本地 HTTP 服务器托管整个目录，再在浏览器打开 examples 路径。不能双击 HTML 用 file:// 打开，否则 ES 模块、本地数据与跨域请求都会失败。若只改某一个示例，可从官网示例页复制 Vite 项目文件后执行 npm start；若需要改库本身，则克隆仓库并运行 npm run serve-examples。
为什么不能直接双击打开示例 HTML
官网示例普遍采用 ES modules（import … from ‘ol/…’），并会请求 GeoJSON、矢量瓦片或第三方底图。浏览器对 file:// 协议限制很严：模块加载常被拦截，XHR/fetch 也会触发 CORS 报错。因此无论用 site 包还是自己搭的页面，都必须通过 http://localhost 访问。Python、npx serve、npx http-server 等任意静态文件服务器都可以，关键是协议与端口正确。
- 验收标准：浏览器地址栏是 http://localhost:端口/…，控制台无 “Failed to load module” 或 CORS 红字。
- 离线注意：大量示例依赖在线 OSM 瓦片或 openlayers.org 上的示例数据，断网时对应图层会空白，需自行换成本地数据源。
方法一：下载 site 包，一键浏览全部示例（推荐入门）
截至 2026 年 11 月，最新稳定版是 OpenLayers v10.11.0（2026 年 10 月 4 日发布）。官方在 Releases 中提供 v10.11.0-site.zip（Includes examples and documentation），解压即得与官网一致的静态站点，最适合先通读、对照改代码。
- 打开 OpenLayers 最新 Releases 页面，下载 v10.11.0-site.zip（或同版本的 site 包）。
- 解压到任意目录，例如 ol-site/。
- 在该目录打开终端，启动本地服务器。常用命令：
- python3 -m http.server 8000
- 或 npx serve -p 8000、npx http-server -p 8000
- 浏览器访问 http://localhost:8000/examples/（或根目录 index.html）。示例列表与交互效果应与官网一致（外部瓦片除外）。
完整库与源码包是 v10.11.0-package.zip，一般不需要仅为“看示例”而下载。历史版本同样在 Releases 列表中按标签取用即可。
方法二：用 Vite 单独复现某一个示例
官网每个示例页都给出了可复制的 Vite 最小项目（main.js、index.html、package.json）。适合只研究某一功能、或准备改成自己的小 demo。当前示例页常见的 package.json 依赖大致为：”ol”: “10.11.0”，开发依赖 “vite”: “^8.1.5″，脚本 “start”: “vite”、”build”: “vite build”。
- 打开任意示例（可从 OpenLayers 官网示例索引 进入），复制页面上的 main.js、index.html、package.json 到本地空目录。
- 在该目录执行 npm install，再执行 npm start。开发服务器通常落在 http://localhost:5173。
- 改代码后保存即可热更新。需要静态部署时执行 npm run build，再对生成的 dist/ 做本地服务或上传。
若暂时不想装 Node，也可在示例页点 “Edit” 跳到在线沙箱直接改，但离线与版本锁定仍以本地 Vite 更稳妥。新项目若从零开始，也可用官方脚手架 npm create ol-app my-app（默认 Vite），再按需把示例代码贴进去。
方法三：克隆仓库跑完整示例服务（适合改源码）
需要调试库内部实现、或批量改 examples 目录时，用源码方式。官方要求 Git + Node.js 16+（建议用当前 LTS），流程如下：
- git clone https://github.com/openlayers/openlayers.git，进入仓库目录。
- npm install。
- npm run serve-examples，浏览器访问 http://localhost:8080/。
- 部分示例依赖 Mapbox、MapTiler 等密钥：参考 examples/.env.example，在 examples/.env（已被 gitignore）里写入对应 *_KEY 覆盖演示值；无密钥时相关图层通常不显示。
仅想看示例时不必克隆整仓，site 包或单示例 Vite 更轻。克隆主要用于开发与提交补丁。
| 场景 | 推荐方式 | Node 要求 | 典型访问地址 |
|---|---|---|---|
| 通读全部示例/文档 | site.zip + 静态服务器 | 无（仅浏览器） | http://localhost:端口/examples/ |
| 改某一个示例 | Vite 复制三件套 | 14+（建议 LTS） | http://localhost:5173 |
| 改库源码/批量示例 | 克隆仓库 + serve-examples | 16+ | http://localhost:8080/ |
运行时要注意的配置与限制
- 版本对齐：单示例 Vite 的 ol 版本建议与官网当前稳定版一致（写作时为 10.11.0），避免 API 差异。
- 外部服务：OSM、第三方底图、在线 GeoJSON 需要网络；纯离线请替换为本地文件或自建瓦片。
- API Key：Mapbox / MapTiler / Bing 等示例缺 key 时图层空白，按 .env 或示例注释补齐。
- 浏览器 API：如 Geolocation，桌面测试常需模拟传感器，否则定位示例表现异常。
- 旧写法：全量 ol.js + 全局变量已不推荐；新示例以 ES modules + bundler 为主。
常见问题
双击 HTML 后页面空白或控制台报模块错误怎么办？
这是典型的 file:// 限制。请改用本地 HTTP 服务器托管目录，用 http://localhost 访问；Chrome 等对本地文件协议限制尤其严格。
示例地图只有部分图层，或完全不出瓦片？
多数示例依赖在线瓦片或官方示例数据。先确认本机可访问外网；离线环境需把数据源改成本地文件或自有服务。带第三方商业底图的示例还要检查 API Key 是否已配置。
npm run serve-examples 或 Vite 启动失败，提示 Node 版本过低？
源码开发建议 Node 16+，Vite 示例一般要求 14+。升级到当前 LTS 后重新 npm install 再试。Git 也需事先安装好以便克隆仓库。
构建后的 dist 怎么本地验收？
在项目里执行 npm run build，再用静态服务器指向 dist 目录（与 site 包相同做法）。确认路由与资源相对路径正确后再部署到正式环境。
本地跑官网示例，优先用 v10.11.0-site.zip 加本地服务器快速通览；真正动手改某个功能时，再按示例页复制 Vite 三件套。务必始终通过 http://localhost 访问，并提前准备好外网或本地数据与必要的 API Key，这样对照 openlayers官网教程 改代码时才不会被环境问题打断。