GIS基础理论 GIS开发 Linux

WebGIS开发入门教程十: 项目怎么部署?Nginx如何配置?

2025-12-11 GIS基础理论

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

《WebGIS开发入门教程十: 项目怎么部署?Nginx如何配置?》这篇文章解决一个非常实际的问题：本地能跑的 WebGIS 项目，如何部署到服务器上，并用 Nginx 正确配置静态资源、接口代理、地图瓦片和跨域访问。

引言：WebGIS项目部署到底要做什么

很多同学在本地开发 WebGIS 项目时，一切都很顺利：前端页面能打开，Leaflet、OpenLayers 或 Cesium 能正常加载底图，后端接口也能返回 GeoJSON、矢量瓦片或业务数据。

但一部署到服务器，就容易出现这些问题：

页面打开是空白，控制台提示资源 404。
地图底图加载失败，瓦片请求跨域。
接口在本地能访问，线上访问报 502 或 504。
刷新页面后变成 Nginx 404。
GeoJSON、MVT、3D Tiles 等静态数据文件无法正确下载或解析。

WebGIS项目部署的核心，不只是把文件上传到服务器，而是要让浏览器、Nginx、前端静态资源、后端 API、地图服务之间的访问路径全部对应起来。

WebGIS项目部署 Nginx配置流程示意图 — WebGIS项目部署时，Nginx通常负责前端静态资源、接口代理、地图数据和瓦片服务的统一入口。

背景：为什么WebGIS部署比普通前端项目更容易出问题

普通管理系统通常只需要部署前端页面和业务接口。但 WebGIS 项目还会涉及地图底图、空间数据文件、瓦片服务、坐标服务、地理编码接口、三维模型等资源。

这些资源的访问方式不同，导致部署时更容易出错：

前端页面一般是 HTML、JS、CSS 静态文件。
业务接口通常由 Java、Node.js、Python、Go 等后端服务提供。
GeoJSON、KML、Shapefile 压缩包、MBTiles 导出的瓦片可能作为静态文件提供。
XYZ 瓦片、WMTS、WMS、MVT、3D Tiles 可能来自独立地图服务。
浏览器会严格检查跨域、HTTPS、MIME 类型和请求路径。

所以，WebGIS项目部署时，Nginx配置必须同时考虑静态站点、接口转发、地图资源访问、路由回退和大文件传输。

原理：Nginx在WebGIS部署中的作用

Nginx 可以理解为服务器上的“入口调度器”。浏览器访问域名后，请求先到 Nginx，再由 Nginx 决定把请求交给谁处理。

在 WebGIS 部署中，Nginx 常见作用有四类：

托管前端静态资源：把 Vue、React、Vite、OpenLayers、Leaflet 项目打包后的文件发布出来。
反向代理后端接口：把浏览器访问的 /api/ 转发到真实后端服务，例如 http://127.0.0.1:8080/。
发布地图静态数据：提供 GeoJSON、瓦片图片、MVT、3D Tiles、配置文件等资源访问。
处理前端路由：解决 Vue Router 或 React Router 刷新后 404 的问题。

一个常见的请求分发方式如下：

浏览器访问路径	Nginx处理方式	典型用途
`/`	读取前端打包目录	WebGIS主页面
`/assets/`	读取静态资源	JS、CSS、图片
`/api/`	代理到后端服务	业务接口、空间查询接口
`/data/`	读取静态数据目录	GeoJSON、配置文件、3D Tiles
`/tiles/`	读取瓦片目录或代理瓦片服务	XYZ瓦片、MVT矢量瓦片

步骤：从打包到Nginx配置的完整流程

步骤一：确认项目在本地可以正常打包

部署之前，先确认 WebGIS 前端项目可以正常构建。以常见 Vite 项目为例：

npm install
npm run build

打包完成后，通常会生成 dist 目录。这个目录就是要部署到服务器的前端静态文件目录。

如果你使用的是 Vue CLI，打包命令可能是：

npm run build

如果你使用 React 项目，构建结果可能在 build 目录中。

需要重点检查两个配置：

生产环境接口地址是否已经改为线上路径，例如 /api。
地图资源路径是否使用相对路径或正确的线上绝对路径。

步骤二：准备服务器目录

假设我们把 WebGIS 项目部署到 Linux 服务器，推荐使用清晰的目录结构：

/var/www/webgis/
├── dist/
│   ├── index.html
│   ├── assets/
│   └── favicon.ico
├── data/
│   ├── city.geojson
│   └── config.json
└── tiles/
    └── z/x/y.png

其中：

dist：前端打包后的页面文件。
data：GeoJSON、JSON配置、静态空间数据。
tiles：本地瓦片目录，如果项目使用本地离线瓦片，可以放在这里。

上传文件可以使用 scp、rsync、SFTP 工具或 CI/CD 流水线。

scp -r dist root@your_server_ip:/var/www/webgis/
scp -r data root@your_server_ip:/var/www/webgis/
scp -r tiles root@your_server_ip:/var/www/webgis/

步骤三：安装并启动Nginx

在 Ubuntu 或 Debian 系统上，可以这样安装 Nginx：

sudo apt update
sudo apt install nginx
sudo systemctl enable nginx
sudo systemctl start nginx

检查 Nginx 是否运行：

sudo systemctl status nginx

如果服务器防火墙开启，需要放行 HTTP 和 HTTPS 端口：

sudo ufw allow 80
sudo ufw allow 443

步骤四：配置WebGIS前端静态站点

创建一个 Nginx 配置文件：

sudo nano /etc/nginx/conf.d/webgis.conf

写入基础配置：

server {
    listen 80;
    server_name example.com;

    root /var/www/webgis/dist;
    index index.html;

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

这里最关键的是：

root 指向前端打包目录。
index 指定首页文件。
try_files $uri $uri/ /index.html; 用于支持前端路由。

如果你的 WebGIS 前端使用 Vue Router 的 history 模式，或者 React Router 的 BrowserRouter，刷新页面后 404 通常就是因为没有配置 try_files。

步骤五：配置后端API反向代理

假设后端服务运行在服务器本机的 8080 端口，接口路径统一为 /api/，可以这样配置：

server {
    listen 80;
    server_name example.com;

    root /var/www/webgis/dist;
    index index.html;

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

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

注意 proxy_pass 后面的斜杠很重要。上面这个写法表示：

浏览器请求 /api/user/list。
Nginx 转发到 http://127.0.0.1:8080/user/list。

如果你的后端本身也带 /api 前缀，可以改成：

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

部署时最常见的问题，就是前端、Nginx、后端三者对 /api 是否保留理解不一致。

步骤六：配置GeoJSON、JSON和静态空间数据目录

WebGIS项目经常会加载 GeoJSON、JSON、CSV、3D Tiles 配置文件等静态数据。可以用 alias 单独映射数据目录：

location /data/ {
    alias /var/www/webgis/data/;
    autoindex off;
}

这样浏览器访问：

https://example.com/data/city.geojson

实际读取的是：

/var/www/webgis/data/city.geojson

如果 GeoJSON 文件较大，可以适当开启 gzip 压缩：

gzip on;
gzip_types text/plain application/json application/geo+json application/javascript text/css;

对于 GeoJSON，部分服务器没有正确识别 MIME 类型时，也可能导致前端解析异常。可以补充：

types {
    application/geo+json geojson;
    application/json json;
}

步骤七：配置XYZ瓦片或离线地图瓦片

如果你的瓦片目录结构是常见的 z/x/y.png，例如：

/var/www/webgis/tiles/10/843/421.png

可以配置：

location /tiles/ {
    alias /var/www/webgis/tiles/;
    expires 30d;
    add_header Cache-Control "public";
}

前端 Leaflet 示例：

L.tileLayer('https://example.com/tiles/{z}/{x}/{y}.png', {
    minZoom: 3,
    maxZoom: 18
}).addTo(map);

OpenLayers 示例：

new ol.layer.Tile({
    source: new ol.source.XYZ({
        url: 'https://example.com/tiles/{z}/{x}/{y}.png'
    })
});

如果你使用的是矢量瓦片 MVT，建议补充 MIME 类型：

types {
    application/vnd.mapbox-vector-tile mvt;
}

步骤八：配置跨域访问

如果前端页面和地图服务不在同一个域名、协议或端口下，就会触发跨域限制。比如：

前端：https://webgis.example.com
接口：https://api.example.com
瓦片：https://tiles.example.com

如果你能通过 Nginx 把接口和地图服务统一到同一个域名下，这是最推荐的方式。例如前端统一访问：

/api/
/tiles/
/data/

如果确实需要开启跨域，可以在对应 location 中添加：

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Allow-Headers "Origin, Content-Type, Accept, Authorization";

if ($request_method = OPTIONS) {
    return 204;
}

生产环境不建议无脑使用 *，尤其是涉及登录态、令牌、敏感空间数据接口时，应限制为可信域名。

步骤九：检查并重载Nginx配置

每次修改 Nginx 配置后，都要先测试配置是否正确：

sudo nginx -t

如果提示成功，再重载：

sudo systemctl reload nginx

不要直接重启服务排错。先用 nginx -t 检查语法，可以避免因为配置错误导致整个站点不可用。

步骤十：一个适合入门项目的完整Nginx配置

下面是一份适合 WebGIS 入门项目的完整配置，可以根据实际域名、目录和后端端口修改：

server {
    listen 80;
    server_name example.com;

    root /var/www/webgis/dist;
    index index.html;

    gzip on;
    gzip_types text/plain application/json application/geo+json application/javascript text/css;

    types {
        application/geo+json geojson;
        application/vnd.mapbox-vector-tile mvt;
        application/json json;
    }

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

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 60s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }

    location /data/ {
        alias /var/www/webgis/data/;
        autoindex off;
        add_header Access-Control-Allow-Origin *;
    }

    location /tiles/ {
        alias /var/www/webgis/tiles/;
        expires 30d;
        add_header Cache-Control "public";
        add_header Access-Control-Allow-Origin *;
    }
}

常见坑：WebGIS部署后最容易遇到的问题

问题一：页面能打开，但地图不显示

先打开浏览器开发者工具，检查 Network 面板。重点看：

瓦片请求是否 404。
GeoJSON 请求是否 404 或 403。
接口是否跨域失败。
地图容器是否高度为 0。
HTTPS 页面是否请求了 HTTP 地图资源。

如果页面是 HTTPS，而底图地址是 HTTP，浏览器通常会拦截，这叫混合内容问题。解决方法是把底图、接口和数据资源全部改成 HTTPS。

问题二：刷新子页面后出现404

这是前端路由问题。只要使用 history 模式，就需要 Nginx 回退到 index.html：

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

如果没有这行配置，浏览器访问 /map/project/1 时，Nginx 会去服务器目录里找真实的 /map/project/1 文件，找不到就返回 404。

问题三：接口502 Bad Gateway

502 通常表示 Nginx 找不到后端服务，或者后端服务没有正常响应。检查顺序：

后端服务是否启动。
后端端口是否正确。
proxy_pass 地址是否写错。
后端是否只监听了 localhost 或错误网卡。
服务器安全组或防火墙是否阻止访问。

可以在服务器上直接测试：

curl http://127.0.0.1:8080/

如果服务器本机访问都失败，问题不在 Nginx，而在后端服务。

问题四：GeoJSON能下载但地图不加载

这种情况通常不是 Nginx 访问问题，而是数据本身或前端解析问题。检查：

GeoJSON 是否是合法 JSON。
坐标顺序是否为经度、纬度。
坐标系是否为 WGS84，经纬度坐标。
文件是否太大，导致浏览器解析卡顿。
响应头是否为合理的 JSON 或 GeoJSON 类型。

很多 WebGIS 初学者会把投影坐标系数据直接导出为 GeoJSON，再在 Leaflet 或常规 Web 地图中加载，结果图层飞到错误位置。原因是多数 Web 地图前端默认使用经纬度坐标或 Web Mercator 显示逻辑，数据坐标系必须提前处理好。

问题五：瓦片路径明明存在，还是404

优先检查 root 和 alias 的区别。对于瓦片目录，推荐使用：

location /tiles/ {
    alias /var/www/webgis/tiles/;
}

注意 location /tiles/ 和 alias /var/www/webgis/tiles/ 末尾都建议保留斜杠。

如果使用错误，Nginx 可能会拼出错误的真实文件路径。

方法比较：几种常见WebGIS部署方式怎么选

部署方式	适合场景	优点	注意事项
Nginx静态部署	纯前端WebGIS、静态GeoJSON、离线瓦片	简单、稳定、性能好	不适合复杂动态空间查询
Nginx + 后端API	带登录、业务数据、空间查询的WebGIS	结构清晰，生产常用	要处理代理路径和跨域
Nginx + GeoServer	WMS、WFS、WMTS地图服务	适合标准OGC服务发布	需要理解图层、样式和服务权限
Docker Compose部署	前端、后端、PostGIS、GeoServer一起部署	环境一致，便于迁移	入门成本略高，需要管理容器网络
对象存储 + CDN	大量静态瓦片、影像切片、三维瓦片	访问快，适合大规模分发	动态接口仍需要后端服务

对于入门阶段，建议先掌握 Nginx静态部署 + API反向代理。这是多数 WebGIS 项目从本地开发走向线上演示和小型生产环境的基础方案。

检查清单：部署完成后逐项验证

WebGIS项目上线后，不要只看首页能不能打开。建议按下面清单逐项检查。

域名是否能正常访问首页。
浏览器控制台是否没有明显 JS 报错。
刷新二级路由是否不会 404。
/assets/ 下的 JS、CSS 是否加载成功。
/api/ 接口是否返回正确数据。
GeoJSON、JSON 配置文件是否能访问。
地图瓦片是否没有大量 404。
HTTPS 页面是否没有请求 HTTP 资源。
大数据量 GeoJSON 加载是否卡顿。
Nginx 错误日志是否没有持续报错。

常用日志查看命令：

sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

如果某个资源加载失败，先看浏览器 Network 面板中的请求 URL，再到 Nginx 日志中确认服务器实际如何处理这个请求。

FAQ：WebGIS项目部署和Nginx配置常见问题

Q1：WebGIS项目必须用Nginx部署吗？

不是必须，但非常推荐。Nginx 适合托管前端静态文件、代理后端接口、发布静态地图数据和处理 HTTPS，是 WebGIS 项目上线最常见的基础组件之一。

Q2：前端接口地址应该写服务器IP，还是写/api？

生产环境更推荐写 /api 这类相对路径，然后由 Nginx 代理到真实后端服务。这样可以减少跨域问题，也方便以后更换后端地址。

Q3：为什么本地地图正常，部署后底图加载失败？

常见原因包括瓦片地址写死为本地地址、线上服务器不能访问外部地图服务、HTTPS 页面请求 HTTP 瓦片、跨域被拦截、Nginx 瓦片目录配置错误等。

Q4：GeoJSON文件应该放在前端dist目录里吗？

小型示例可以放在 dist 中，但更推荐单独放在 /data/ 目录，并用 Nginx 的 alias 映射。这样后续更新数据时，不一定需要重新打包前端项目。

Q5：Nginx配置修改后为什么没有生效？

通常是没有重载 Nginx，或者修改的不是正在加载的配置文件。建议执行：

sudo nginx -t
sudo systemctl reload nginx

如果仍然不生效，可以使用下面命令查看 Nginx 实际加载的完整配置：

sudo nginx -T

Q6：WebGIS部署后地图很慢，应该先优化哪里？

先区分是接口慢、瓦片慢，还是前端渲染慢。可以从浏览器 Network 面板查看耗时。如果 GeoJSON 文件很大，应考虑简化几何、切片、使用矢量瓦片或后端分页查询，而不是直接把超大 GeoJSON 一次性加载到浏览器。

结论：WebGIS部署的关键是路径、代理和地图资源管理

WebGIS项目部署并不复杂，但细节很多。你需要同时处理前端静态资源、后端 API、GeoJSON 数据、地图瓦片、跨域、HTTPS 和前端路由。

入门阶段可以记住一个实用原则：前端页面由 Nginx 托管，接口通过 /api/ 代理，空间数据放到 /data/，瓦片资源放到 /tiles/，所有路径都在浏览器 Network 面板中逐项验证。

当你能看懂每一个请求最终由 Nginx 转发到哪里，WebGIS部署和Nginx配置就不再是黑盒问题，而是可以逐步排查、稳定上线的工程流程。