扬州WebGIS开发如何从零到一？WebGIS开发实战项目源码与部署教程（附：三维场景搭建指南）

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

《扬州WebGIS开发如何从零到一？WebGIS开发实战项目源码与部署教程（附：三维场景搭建指南）》这篇文章面向想做城市级 WebGIS 项目的同学：不空谈概念，而是用一个“扬州文旅与基础地理信息展示平台”的实战思路，把数据准备、前端地图、后端服务、空间接口、部署上线和三维场景搭建串起来。

引言：扬州WebGIS开发从零到一到底要做什么

很多 GIS 初学者学过 QGIS、ArcGIS Pro，也写过一点 JavaScript，但真正开始做 WebGIS 项目时，常常卡在三个问题上：

• 不知道 WebGIS 项目的目录结构应该怎么设计。
• 不知道矢量数据、影像底图、三维模型分别如何发布和加载。
• 不知道开发完成后如何部署到服务器，让别人通过浏览器访问。

本文以“扬州城市 WebGIS 示例项目”为主线，给出一套可复用的开发流程。你可以把扬州替换成任意城市，例如南京、苏州、杭州，核心方法基本一致。

建议读者具备基础 HTML、JavaScript、坐标系和矢量数据概念。如果你已经用过 QGIS 或 ArcGIS Pro，会更容易理解数据处理环节。

背景：为什么很多WebGIS开发项目做不起来

WebGIS 开发并不是“前端加一张地图”这么简单。一个可运行的 WebGIS 项目通常包含以下部分：

• 空间数据：行政区、道路、水系、POI、景区边界、影像底图、三维建筑等。
• 空间数据库：常用 PostGIS 存储矢量数据，支持空间查询。
• 地图服务：常用 GeoServer 发布 WMS、WFS、WMTS 等服务。
• 前端框架：二维可用 OpenLayers、Leaflet；三维可用 Cesium。
• 业务接口：例如景点查询、路线查询、图层控制、属性弹窗。
• 部署环境：Nginx、Node.js、Docker、Linux 服务器、域名和 HTTPS。

新手项目失败，通常不是因为某一个工具不会用，而是没有把这些环节按正确顺序连起来。本文的重点就是建立一条清晰的 WebGIS 项目流水线。

原理：WebGIS开发实战项目的基本架构

一个典型的 WebGIS 项目可以拆成三层：数据层、服务层和表现层。

层级	作用	常用工具
数据层	存储行政区、道路、POI、三维模型等空间数据	QGIS、ArcGIS Pro、PostGIS、GeoPackage、Shapefile
服务层	把空间数据发布成前端可访问的地图服务或接口	GeoServer、PostGIS、Node.js、Spring Boot
表现层	在浏览器中展示地图、图层、查询结果和三维场景	OpenLayers、Leaflet、Cesium、Vue、React

在扬州 WebGIS 项目中，可以采用一个比较稳妥的组合：

• 二维地图：OpenLayers 加载底图、行政区、景点点位和道路。
• 空间服务：GeoServer 发布扬州市行政区和景区图层。
• 空间数据库：PostGIS 存储需要查询和编辑的数据。
• 三维场景：Cesium 加载地形、影像和 3D Tiles。
• 前端工程：Vue 3 或原生 JavaScript 均可，初学者建议先用原生或轻量 Vue 项目。
• 部署：Nginx 托管静态前端，反向代理后端接口和 GeoServer 服务。

这里有一个关键原则：不要一开始就追求大而全。先让一个行政区图层和一个景点点位图层在浏览器中正确显示，再逐步加入查询、统计、三维和部署。

步骤：扬州WebGIS开发实战项目从零到一

步骤一：准备项目数据

建议先准备以下几类数据，足够完成一个入门级扬州 WebGIS 项目：

• 扬州市行政区边界数据，格式可以是 Shapefile、GeoJSON 或 GeoPackage。
• 扬州主要道路或水系数据，用于增强地图语义。
• 景点 POI 点位，例如瘦西湖、个园、何园、东关街等。
• 在线底图，例如天地图、高德、OpenStreetMap 或自建 WMTS。
• 可选三维数据，例如 3D Tiles 建筑模型、倾斜摄影或 Cesium 地形。

在正式开发前，建议先用 QGIS 检查数据：

1. 打开所有图层，确认数据能正常显示。
2. 检查坐标系，常见为 EPSG:4326 或 EPSG:3857。
3. 检查属性字段，删除无用字段，保留名称、类型、编码、简介等业务字段。
4. 修复无效几何，避免发布服务后出现渲染失败或查询异常。
5. 导出统一格式，推荐 GeoPackage 或导入 PostGIS。

如果你的数据来自不同来源，坐标系不一致是最常见的问题。WebGIS 前端通常使用 EPSG:3857 显示在线瓦片底图，而很多政务或测绘数据可能是 CGCS2000、高斯投影或地方坐标。必须先明确数据坐标系，再做转换。

步骤二：创建前端项目目录

一个简单但清晰的 WebGIS 前端项目目录可以这样设计：

yangzhou-webgis/
├── public/
│   └── data/
│       ├── yangzhou_boundary.geojson
│       └── scenic_spots.geojson
├── src/
│   ├── map/
│   │   ├── initMap.js
│   │   ├── layers.js
│   │   └── popup.js
│   ├── styles/
│   │   └── map.css
│   └── main.js
├── index.html
└── package.json

如果只是学习 WebGIS 开发，不必一开始就引入复杂的状态管理和组件库。先把地图初始化、图层加载、弹窗查询拆清楚，后续维护会更容易。

步骤三：使用OpenLayers初始化二维地图

下面是一个最小可运行的 OpenLayers 地图初始化示例，适合用来验证项目是否能正常启动：

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import VectorLayer from 'ol/layer/Vector.js';
import OSM from 'ol/source/OSM.js';
import VectorSource from 'ol/source/Vector.js';
import GeoJSON from 'ol/format/GeoJSON.js';
import { fromLonLat } from 'ol/proj.js';

const baseLayer = new TileLayer({
  source: new OSM()
});

const boundaryLayer = new VectorLayer({
  source: new VectorSource({
    url: '/data/yangzhou_boundary.geojson',
    format: new GeoJSON()
  })
});

const map = new Map({
  target: 'map',
  layers: [baseLayer, boundaryLayer],
  view: new View({
    center: fromLonLat([119.412, 32.394]),
    zoom: 10
  })
});

其中 fromLonLat([119.412, 32.394]) 表示把经纬度坐标转换成 Web Mercator 坐标。扬州中心点大致位于东经 119.4 度、北纬 32.4 度附近，实际项目中可以根据行政区范围重新计算中心点。

步骤四：加载扬州景点点位并添加弹窗

景点点位可以先用 GeoJSON 存放，字段设计尽量简单：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "瘦西湖",
        "type": "景区",
        "level": "国家级旅游景区",
        "intro": "扬州代表性湖上园林景区"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [119.421, 32.413]
      }
    }
  ]
}

前端加载点位后，可以通过点击事件读取属性，实现景点弹窗：

map.on('singleclick', function (evt) {
  map.forEachFeatureAtPixel(evt.pixel, function (feature) {
    const props = feature.getProperties();
    const name = props.name || '未命名';
    const type = props.type || '未知类型';
    const intro = props.intro || '暂无简介';

    console.log('景点名称：', name);
    console.log('景点类型：', type);
    console.log('简介：', intro);
  });
});

实际项目中可以把 console.log 替换成 HTML 弹窗组件。需要注意，属性弹窗不是地图功能的终点，后续还可以扩展为路线规划、周边查询、分类筛选和专题统计。

步骤五：使用PostGIS管理空间数据

当数据量较大，或者需要按条件查询、空间相交、缓冲区分析时，不建议继续把所有数据放在 GeoJSON 文件中。此时可以把数据导入 PostGIS。

例如创建景点表：

CREATE TABLE scenic_spots (
  id SERIAL PRIMARY KEY,
  name TEXT,
  type TEXT,
  level TEXT,
  intro TEXT,
  geom geometry(Point, 4326)
);

CREATE INDEX scenic_spots_geom_idx
ON scenic_spots
USING GIST (geom);

插入一个景点点位：

INSERT INTO scenic_spots (name, type, level, intro, geom)
VALUES (
  '瘦西湖',
  '景区',
  '国家级旅游景区',
  '扬州代表性湖上园林景区',
  ST_SetSRID(ST_MakePoint(119.421, 32.413), 4326)
);

查询某个范围内的景点，可以使用 PostGIS 空间函数：

SELECT name, type, level
FROM scenic_spots
WHERE ST_Intersects(
  geom,
  ST_MakeEnvelope(119.2, 32.2, 119.6, 32.6, 4326)
);

这里的 GIST 空间索引用于提升空间查询速度。如果数据达到几万、几十万条，没有空间索引会明显拖慢 WebGIS 查询接口。

步骤六：使用GeoServer发布地图服务

GeoServer 适合把 PostGIS 或文件型数据发布成标准地图服务。常见服务类型如下：

• WMS：返回渲染好的地图图片，适合展示行政区、道路、水系等图层。
• WFS：返回矢量要素，适合前端查询属性、选中要素和少量编辑。
• WMTS：返回切片瓦片，适合大范围高性能浏览。

发布扬州行政区图层的一般流程：

1. 在 GeoServer 中创建工作区，例如 yangzhou。
2. 添加 PostGIS 数据存储，填写数据库地址、端口、库名、用户名和密码。
3. 选择行政区表，点击发布。
4. 确认图层坐标参考系统，例如 EPSG:4326。
5. 计算边界框，保存图层。
6. 在 Layer Preview 中测试 WMS 或 WFS 是否能正常访问。

前端加载 GeoServer WMS 的示例：

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

const districtWmsLayer = new TileLayer({
  source: new TileWMS({
    url: 'https://your-domain.com/geoserver/yangzhou/wms',
    params: {
      LAYERS: 'yangzhou:district',
      TILED: true
    },
    serverType: 'geoserver'
  })
});

如果出现空白地图，优先检查图层名、坐标系、边界框和跨域配置，不要急着改前端代码。

步骤七：搭建三维场景

三维场景搭建可以使用 Cesium。对初学者来说，先完成三个目标即可：

• 加载全球三维地球并定位到扬州。
• 加载影像底图或地形服务。
• 加载 3D Tiles 建筑模型或倾斜摄影数据。

Cesium 初始化示例：

const viewer = new Cesium.Viewer('cesiumContainer', {
  terrainProvider: await Cesium.createWorldTerrainAsync()
});

viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(119.412, 32.394, 3000),
  orientation: {
    heading: Cesium.Math.toRadians(0),
    pitch: Cesium.Math.toRadians(-45),
    roll: 0
  }
});

加载 3D Tiles 数据：

const tileset = await Cesium.Cesium3DTileset.fromUrl(
  '/data/tileset/tileset.json'
);

viewer.scene.primitives.add(tileset);
viewer.zoomTo(tileset);

三维场景最容易遇到的问题是模型偏移、模型不显示和加载很慢。模型偏移通常与坐标系、模型原点和高度基准有关；加载慢则通常与 3D Tiles 切片层级、纹理大小和服务器带宽有关。

步骤八：编写后端查询接口

如果项目需要“按名称搜索景点”或“查询当前视图范围内的点位”，可以用 Node.js 或 Java 编写接口。以下是 Node.js 查询 PostGIS 的简化示例：

import express from 'express';
import pg from 'pg';

const app = express();
const pool = new pg.Pool({
  host: '127.0.0.1',
  port: 5432,
  database: 'webgis',
  user: 'postgres',
  password: 'your_password'
});

app.get('/api/scenic-spots', async (req, res) => {
  const keyword = req.query.keyword || '';

  const sql = `
    SELECT id, name, type, level, intro,
           ST_AsGeoJSON(geom) AS geometry
    FROM scenic_spots
    WHERE name ILIKE $1
    LIMIT 50
  `;

  const result = await pool.query(sql, [`%${keyword}%`]);
  res.json(result.rows);
});

app.listen(3000, () => {
  console.log('API server running on port 3000');
});

这个接口返回的是数据库记录，不是标准 GeoJSON。实际项目中建议封装成 FeatureCollection，这样前端可以直接用 OpenLayers 的 GeoJSON 格式读取。

步骤九：部署到服务器

部署 WebGIS 项目时，常见结构如下：

• Nginx：托管前端静态文件。
• Node.js 或 Java：运行业务接口。
• GeoServer：发布地图服务。
• PostgreSQL/PostGIS：存储空间数据。

Nginx 示例配置：

server {
  listen 80;
  server_name your-domain.com;

  root /var/www/yangzhou-webgis;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:3000/api/;
  }

  location /geoserver/ {
    proxy_pass http://127.0.0.1:8080/geoserver/;
  }
}

部署后建议按这个顺序测试：

1. 访问首页，确认前端能打开。
2. 打开浏览器控制台，确认没有 JavaScript 报错。
3. 访问 GeoServer WMS 预览地址，确认地图服务正常。
4. 访问后端 API，确认返回 JSON 数据。
5. 检查地图图层是否有跨域、404、坐标偏移或加载超时问题。

常见坑：扬州WebGIS开发中最容易踩的错误

坑一：坐标系不一致导致图层偏移

这是 WebGIS 开发最常见的问题。行政区、景点点位、在线底图看起来不重合，通常不是数据“坏了”，而是坐标系不一致。

• GeoJSON 常见为 EPSG:4326，经纬度单位是度。
• 在线瓦片底图常见为 EPSG:3857，单位是米。
• 地方测绘数据可能是 CGCS2000、高斯投影或地方独立坐标。

排查方法：先在 QGIS 中加载所有数据，确认是否能叠加；再检查前端是否使用了正确的投影转换函数。

坑二：GeoJSON文件过大导致页面卡顿

如果把几百 MB 的 GeoJSON 直接放到前端加载，浏览器很容易卡死。GeoJSON 适合小数据量演示，不适合承载大规模业务数据。

优化方向：

• 小数据：可继续使用 GeoJSON。
• 中等数据：使用 GeoServer WMS 或矢量瓦片。
• 大量数据：入库 PostGIS，并按视图范围或条件分页查询。
• 大面数据：做几何简化，减少顶点数量。

坑三：GeoServer能预览，前端却加载失败

这种情况多半与 URL、图层名、跨域或代理有关。检查下面几项：

• LAYERS 参数是否写成了完整的 工作区:图层名。
• Nginx 是否正确代理了 /geoserver/ 路径。
• 浏览器控制台是否出现 CORS 跨域错误。
• 服务地址是否从内网地址误写成了公网不可访问地址。
• HTTPS 页面是否调用了 HTTP 地图服务，导致混合内容被拦截。

坑四：三维模型位置不对

Cesium 中 3D Tiles 偏移通常与模型坐标、模型中心点、高程基准和转换参数有关。不要只在前端强行平移模型，应该先确认模型生产环节是否正确。

• 确认 3D Tiles 的源数据坐标系。
• 确认模型是否带有正确的地理参考。
• 确认高度是椭球高、海拔高还是相对高度。
• 小范围偏移可以在 Cesium 中做矩阵修正，大范围偏移应回到数据生产环节处理。

方法比较：OpenLayers、Leaflet、Cesium和GeoServer怎么选

工具	适合场景	优点	限制
OpenLayers	二维专业 WebGIS、WMS/WFS、复杂图层控制	GIS 能力强，服务兼容好，适合工程项目	API 相对多，新手需要适应
Leaflet	轻量地图、移动端、简单点线面展示	上手快，插件丰富，代码简洁	复杂投影和专业 GIS 能力较弱
Cesium	三维地球、倾斜摄影、3D Tiles、地形分析	三维能力强，适合城市级场景展示	数据处理和性能优化门槛较高
GeoServer	地图服务发布、WMS、WFS、样式管理	开源成熟，和 PostGIS 配合稳定	高并发和大数据场景需要缓存与调优
PostGIS	空间数据存储、空间查询、空间分析	空间函数丰富，适合后端分析和查询	需要掌握 SQL、索引和数据库维护

如果你是第一次做扬州 WebGIS 开发实战项目，推荐路线是：OpenLayers 做二维地图，GeoServer 发布图层，PostGIS 管理数据，Cesium 作为三维展示模块逐步加入。这样学习曲线较平稳，也更接近真实项目。

检查清单：WebGIS开发源码与部署前必须确认

数据检查

• 行政区、道路、景点点位是否能在 QGIS 中正常打开。
• 所有图层是否有明确坐标系。
• 是否存在无效几何、自相交、多余字段或乱码字段。
• 面数据是否过于复杂，是否需要简化。
• POI 点位是否有名称、类型、简介等必要字段。

服务检查

• GeoServer 图层是否能在 Layer Preview 中预览。
• WMS、WFS 地址是否能通过浏览器直接访问。
• PostGIS 表是否创建了空间索引。
• 后端 API 是否限制了返回数量，避免一次返回过多数据。
• Nginx 是否正确代理 API 和 GeoServer。

前端检查

• 地图中心点和缩放级别是否适合扬州范围。
• 图层加载顺序是否正确，底图是否在最底层。
• 点击查询是否能返回正确属性。
• 浏览器控制台是否存在 404、CORS、投影转换或资源加载错误。
• 移动端或不同分辨率下地图容器高度是否正常。

三维检查

• Cesium 容器是否有明确宽高。
• 地形、影像、3D Tiles 地址是否可访问。
• 模型是否与底图重合。
• 模型纹理是否过大，是否影响加载速度。
• 相机定位是否准确，是否存在进入场景后黑屏或空白问题。

FAQ：扬州WebGIS开发常见问题

1. 扬州WebGIS开发一定要用真实政务数据吗？

不一定。学习阶段可以使用公开数据、手工整理的 POI 数据或自己在 QGIS 中绘制的示例数据。真实政务数据通常涉及权限、保密和授权问题，不建议随意传播。

2. WebGIS开发实战项目源码应该包含哪些内容？

至少应包含前端地图初始化代码、图层加载代码、示例数据、接口说明和部署说明。更完整的源码还应包含数据库建表 SQL、GeoServer 发布说明、Nginx 配置和三维场景加载示例。

3. 扬州WebGIS项目用OpenLayers还是Leaflet更合适？

如果只是做景点点位展示，Leaflet 足够轻量；如果要加载 WMS、WFS、处理多坐标系、做图层控制和专业 GIS 操作，OpenLayers 更合适。本文推荐 OpenLayers，是因为它更适合工程化 WebGIS 开发。

4. 三维场景搭建必须使用Cesium吗？

不一定，但 Cesium 是目前 WebGIS 三维地球和 3D Tiles 场景中非常常见的选择。如果你的项目只需要二维地图，不必强行加入三维；如果要展示城市建筑、倾斜摄影、地形和飞行浏览，Cesium 更适合。

5. GeoJSON、WMS和WFS应该怎么选？

小数据量、前端交互强的数据可以用 GeoJSON；只需要地图展示的大图层适合 WMS；需要返回矢量要素并读取属性时可以用 WFS。数据量继续变大时，应考虑矢量瓦片、PostGIS 查询接口或 WMTS 缓存。

6. 部署后地图空白，最先检查哪里？

先打开浏览器开发者工具，看 Network 和 Console。重点检查地图服务是否 404、是否跨域、是否 HTTPS 调 HTTP、图层名是否写错、GeoServer 是否能公网访问。不要盲目修改样式或重写前端代码。

7. WebGIS项目可以只用前端完成吗？

可以完成演示版，例如加载 GeoJSON、在线底图和简单弹窗。但如果涉及数据更新、权限控制、空间查询、统计分析和大数据量展示，就需要后端服务、数据库和地图服务支撑。

结论：从一个可运行小项目开始，逐步扩展到完整WebGIS系统

扬州 WebGIS 开发从零到一的关键，不是一次性堆满所有功能，而是先跑通最小闭环：准备一份可靠数据，发布一个地图服务，在前端正确加载，再完成查询和部署。

推荐你按这个顺序推进项目：

1. 用 QGIS 整理扬州行政区和景点 POI 数据。
2. 用 OpenLayers 完成二维地图和图层加载。
3. 用 PostGIS 管理需要查询的数据。
4. 用 GeoServer 发布 WMS 或 WFS 服务。
5. 用 Cesium 增加三维场景搭建能力。
6. 用 Nginx 把前端、接口和地图服务部署到服务器。

只要这条链路跑通，后续无论是做文旅地图、城市管理平台、自然资源展示系统，还是校园 WebGIS 项目，都可以在同一套架构上继续扩展。真正有价值的 WebGIS 开发实战项目，不是页面多炫，而是数据可靠、服务稳定、交互清楚、部署可复现。