OpenLayers from Zero to Mastery: A Practical Guide 2025-2026

1. Introduction and positioning

In the field of WebGIS development, if you need to build professional-level 2D map applications, there is a very mature and powerful tool - OpenLayers.

OpenLayers is an open source JavaScript map library mainly used for building 2D GIS applications in the browser.It supports a rich set of map projections, vector data, and OGC services (WMS/WFS/WMTS) and is a very common technology selection in enterprise-level WebGIS platforms.

Compare with other map libraries

Technology	Features	Applicable scenarios
OpenLayers	The most powerful, supporting complex GIS	WebGIS platform
Leaflet	Lightweight and simple	Simple map
Mapbox GL JS	High-performance vector tiles	Map products
CesiumJS	3D Earth Engine	Digital Twin

Brief summary:

OpenLayers = WebGIS 工程
Leaflet = 轻量地图
MapboxGL = 高性能地图
Cesium = 3D 地球

Version and capabilities used here

These examples target OpenLayers 10.11.0. The following capabilities are used here but were not necessarily introduced in that release.

Complete ESM Modular
Better Tree Shaking
WebGL rendering enhancements
Better vector rendering performance
Better Mobile Support

What can you do after studying?

After mastering OpenLayers, you can develop:

🌍 Smart City GIS Platform
🚦 Traffic Monitoring Map
🏙 Urban Planning System
🛰 Satellite image browsing system

Target readers:

零基础 GIS → 能独立开发 WebGIS 项目

2. Development environment setup

Method 1: CDN (easiest)

Suitable for quick experience.

html

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.11.0/ol.css" />

<script src="https://cdn.jsdelivr.net/npm/ol@10.11.0/dist/ol.js"></script>

Method 2: Recommended method (Vite + npm)

Recommended for modern projects:

bash

npm create vite@latest openlayers-demo
cd openlayers-demo

npm install
npm install ol@10.11.0

Start the project:

bash

npm run dev

Method three: ESM + importmap

Modern browser way:

html

<script type="importmap">
  {
    "imports": {
      "ol": "https://cdn.jsdelivr.net/npm/ol@latest/dist/ol.js"
    }
  }
</script>

Minimal HTML template

html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>OpenLayers Demo</title>

    <link rel="stylesheet" href="node_modules/ol/ol.css" />

    <style>
      html,
      body,
      #map {
        width: 100%;
        height: 100%;
        margin: 0;
      }
    </style>
  </head>

  <body>
    <div id="map"></div>

    <script type="module" src="main.js"></script>
  </body>
</html>

3. Quick overview of core concepts

Map

Map is a map object.

javascript

import Map from "ol/Map.js";

const map = new Map();

View

View Controls the map perspective.

javascript

import View from "ol/View.js";

const view = new View({
  center: [0, 0],
  zoom: 2,
});

Layer

Map layer.

Common types:

TileLayer
VectorLayer
ImageLayer

Example:

javascript

import TileLayer from "ol/layer/Tile.js";

Source

Data source.

For example:

OSM
XYZ
Vector
WMS

Example:

javascript

import OSM from "ol/source/OSM.js";

Feature

Feature is a map feature.

For example:

点
线
面

javascript

new Feature();

Geometry

Geometric objects:

Point
LineString
Polygon

Style

Control style.

javascript

new Style({
  stroke: new Stroke({
    color: "red",
  }),
});

Interaction

Interactive system:

Draw
Modify
Select

Overlay

Used for pop-up boxes.

4. Getting Started: Make the first map in 5 minutes

Provide a container with a nonzero height in index.html, then load the OpenLayers stylesheet from main.js:

html

<div id="map" style="height: 100vh"></div>

main.js

javascript

import "ol/ol.css";
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 { fromLonLat } from "ol/proj.js";

const map = new Map({
  target: "map",

  layers: [
    new TileLayer({
      source: new OSM(),
    }),
  ],

  view: new View({
    center: fromLonLat([121.47, 31.23]),
    zoom: 10,
  }),
});

After running you can see:

OpenStreetMap 地图

Add controls

javascript

import { ScaleLine, MousePosition } from "ol/control.js";

Add:

javascript

map.addControl(new ScaleLine());
map.addControl(new MousePosition());

5. Intermediate Advanced

5.1 Multiple basemaps

XYZ example:

javascript

import XYZ from "ol/source/XYZ.js";

new TileLayer({
  source: new XYZ({
    url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
  }),
});

⚠ NOTE

Domestic maps require Coordinate System Conversion (GCJ02).

5.2 WMS service

javascript

import TileWMS from "ol/source/TileWMS.js";

new TileLayer({
  source: new TileWMS({
    url: "http://localhost:8080/geoserver/wms",

    params: {
      LAYERS: "topp:states",
    },
  }),
});

5.3 Loading GeoJSON

javascript

import VectorSource from "ol/source/Vector.js";
import GeoJSON from "ol/format/GeoJSON.js";

javascript

const source = new VectorSource({
  url: "data.geojson",

  format: new GeoJSON(),
});

5.4 Style system

javascript

import Style from "ol/style/Style.js";
import Stroke from "ol/style/Stroke.js";

javascript

const style = new Style({
  stroke: new Stroke({
    color: "blue",
    width: 2,
  }),
});

5.5 Interaction

javascript

import Draw from "ol/interaction/Draw.js";

javascript

map.addInteraction(
  new Draw({
    type: "Polygon",
  }),
);

5.6 Pop-up box Overlay

javascript

import Overlay from "ol/Overlay.js";

javascript

const popup = new Overlay({
  element: document.getElementById("popup"),
});

map.addOverlay(popup);

5.7 Coordinate system conversion

javascript

import { fromLonLat, toLonLat } from "ol/proj.js";

javascript

fromLonLat([116.39, 39.9]);

6. Advanced practice: urban POI management system

Project goals:

城市 POI 管理平台

Support:

POI display
clustering
heat map
Query
Edit

Project structure

project
 ├ index.html
 ├ main.js
 ├ style.css
 └ data
     └ poi.geojson

Load POI data

javascript

const source = new VectorSource({
  url: "data/poi.geojson",

  format: new GeoJSON(),
});

clustering

javascript

import Cluster from "ol/source/Cluster.js";

const clusterSource = new Cluster({
  distance: 40,
  source: source,
});

heat map

javascript

import HeatmapLayer from "ol/layer/Heatmap.js";

javascript

const heatLayer = new HeatmapLayer({
  source: source,
});

Animation effects

javascript

map.on("postrender", function () {
  // 动画逻辑
});

Custom controls

javascript

class MyControl extends Control {
  constructor() {
    super({
      element: document.createElement("div"),
    });
  }
}

Expansion capabilities

Can access:

REST API
WebSocket
实时数据

For example:

javascript

fetch("/api/poi");

7. Performance optimization and production best practices

1 tile cache

Browser cache:

TileCache

2 lots of points

Recommended:

Cluster
WebGLPoints

3 Memory management

Destroy the map:

javascript

map.setTarget(null);

4 Mobile terminal adaptation

Note:

touch 事件
设备像素比

5 common bugs

white screen

Possible:

容器高度为0

coordinate offset

Reason:

GCJ02 / WGS84

Cross domain

Requires:

CORS

Package deployment

Recommended:

Vite
Webpack
Rollup

8. Learning resources

Official documentation:

OpenLayers official documentation

Example library:

OpenLayers examples

GitHub：

github.com/openlayers/openlayers

Advanced direction

Recommended study:

OpenLayers + Vue
OpenLayers + React
OpenLayers + Three.js
OpenLayers + Deck.gl
OpenLayers + Cesium

9. Conclusion

Through this article, you have mastered:

OpenLayers 基础
地图图层
矢量数据
交互系统
GIS 服务
项目架构
性能优化

Suggested learning paths:

OpenLayers 基础
↓
GIS 数据处理
↓
OGC 服务
↓
大型 GIS 平台

It is recommended that you:

Fork official examples
Implement new features yourself
Publish the project to GitHub

Ultimately, you will be able to develop:

企业级 WebGIS 平台

1. Introduction and positioning ​

Compare with other map libraries ​

Version and capabilities used here ​

What can you do after studying? ​

2. Development environment setup ​

Method 1: CDN (easiest) ​

Method 2: Recommended method (Vite + npm) ​

Method three: ESM + importmap ​

Minimal HTML template ​

3. Quick overview of core concepts ​

Map ​

View ​

Layer ​

Source ​

Feature ​

Geometry ​

Style ​

Interaction ​

Overlay ​

4. Getting Started: Make the first map in 5 minutes ​

main.js ​

Add controls ​

5. Intermediate Advanced ​

5.1 Multiple basemaps ​

⚠ NOTE ​

5.2 WMS service ​

5.3 Loading GeoJSON ​

5.4 Style system ​

5.5 Interaction ​

5.6 Pop-up box Overlay ​

5.7 Coordinate system conversion ​

6. Advanced practice: urban POI management system ​

Project structure ​

Load POI data ​

clustering ​

heat map ​

Animation effects ​

Custom controls ​

Expansion capabilities ​

7. Performance optimization and production best practices ​

1 tile cache ​

2 lots of points ​

3 Memory management ​

4 Mobile terminal adaptation ​

5 common bugs ​

white screen ​

coordinate offset ​

Cross domain ​

Package deployment ​

8. Learning resources ​

Advanced direction ​

9. Conclusion ​

1. Introduction and positioning

Compare with other map libraries

Version and capabilities used here

What can you do after studying?

2. Development environment setup

Method 1: CDN (easiest)

Method 2: Recommended method (Vite + npm)

Method three: ESM + importmap

Minimal HTML template

3. Quick overview of core concepts

Map

View

Layer

Source

Feature

Geometry

Style

Interaction

Overlay

4. Getting Started: Make the first map in 5 minutes

main.js

Add controls

5. Intermediate Advanced

5.1 Multiple basemaps

⚠ NOTE

5.2 WMS service

5.3 Loading GeoJSON

5.4 Style system

5.5 Interaction

5.6 Pop-up box Overlay

5.7 Coordinate system conversion

6. Advanced practice: urban POI management system

Project structure

Load POI data

clustering

heat map

Animation effects

Custom controls

Expansion capabilities

7. Performance optimization and production best practices

1 tile cache

2 lots of points

3 Memory management

4 Mobile terminal adaptation

5 common bugs

white screen

coordinate offset

Cross domain

Package deployment

8. Learning resources

Advanced direction

9. Conclusion