QGIS Web Client怎么装?前端地图如何展示?

别再被“QGIS Web Client”搞晕了——它早就不推荐用了

你是不是在某个老教程里看到“QGIS Web Client”，兴冲冲下载安装，结果发现报错满屏、文档缺失、社区无人应答？别慌，这不是你的问题——是工具本身已经“退休”了。我在2018年参与某智慧城市项目时，就踩过这个坑：团队花两周搭好环境，最后发现性能差、扩展难，被迫推倒重来。

好消息是：现在有更好的替代方案。坏消息是：你需要忘掉“QGIS Web Client”这个名字。

为什么官方早已放弃 QGIS Web Client？

简单说，它是个“过渡品”。诞生于WebGIS刚兴起的年代（约2010年前后），基于PHP+ExtJS开发，架构老旧、依赖繁杂、移动端支持差。随着Leaflet、OpenLayers、MapLibre等现代前端地图库崛起，以及QGIS Server能力增强，官方早在QGIS 3.x时代就停止维护Web Client，转而推荐更轻量、灵活的组合方案。

类比一下：就像你现在不会用诺基亚塞班系统去开发App一样，技术栈需要与时俱进。

现代替代方案：QGIS Server + 前端地图库

真正的生产级方案是：QGIS Server 发布服务 + 前端用 Leaflet/OpenLayers 加载展示。这套组合拳我带研究生团队做过不下十个项目，稳定、高效、易扩展。

第一步：安装并配置 QGIS Server

QGIS Server 是一个能通过HTTP请求返回地图图片或矢量数据的服务端程序。安装方式因系统而异：

• Windows用户：最简单是用OSGeo4W 安装器，勾选 qgis-server 组件。
• Linux用户（Ubuntu为例）：

  sudo apt update
  sudo apt install qgis-server
  

安装后，需配置Web服务器（如Apache或Nginx）代理请求。以Apache为例，启用模块并设置虚拟主机：

sudo a2enmod cgi
sudo systemctl restart apache2

然后在 /etc/apache2/sites-available/qgis.conf 中添加：

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html
    ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
    <Directory "/usr/lib/cgi-bin/">
        AllowOverride None
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
        Require all granted
    </Directory>
</VirtualHost>

第二步：发布你的第一个地图服务

准备一个QGIS工程文件（.qgs 或 .qgz），比如叫 myproject.qgz，放到服务器可访问目录，如 /home/user/qgis/projects/。

测试服务是否正常：

http://your-server.com/cgi-bin/qgis_mapserv.fcgi?MAP=/home/user/qgis/projects/myproject.qgz&SERVICE=WMS&REQUEST=GetCapabilities

如果返回XML结构的元数据，恭喜你，服务已通！

前端怎么加载？用 Leaflet 三行代码搞定

前端展示部分，推荐使用 Leaflet —— 轻量、文档全、插件多。新建一个HTML文件，引入Leaflet CSS/JS：

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

然后初始化地图并加载WMS图层：

const map = L.map('map').setView([30.27, 120.15], 10);
L.tileLayer.wms('http://your-server.com/cgi-bin/qgis_mapserv.fcgi?', {
    layers: 'your_layer_name',
    format: 'image/png',
    transparent: true,
    version: '1.3.0'
}).addTo(map);

其中 your_layer_name 是你在QGIS工程里图层的名称，务必与工程文件内一致。

进阶技巧：用 QWC2 快速搭建管理后台（可选）

如果你需要带图层控制、查询、打印等功能的完整WebGIS应用，可以试试 QGIS Web Client 2 (QWC2) —— 这才是官方目前推荐的“接班人”。

QWC2 基于React + OpenLayers，支持主题配置、权限管理、移动端适配。部署稍复杂，但有Docker镜像可用：

git clone https://github.com/qgis/qwc2-demo-app.git
cd qwc2-demo-app
docker-compose up

默认访问 http://localhost:8088 即可看到完整界面。适合中大型项目快速原型开发。

总结：别回头，向前看

记住：

• ❌ 不要再折腾老版 QGIS Web Client
• ✅ 用 QGIS Server + Leaflet/OpenLayers 搭建现代WebGIS
• 🚀 需要完整功能？上 QWC2

这套架构我亲自用于国土空间规划、灾害应急响应等多个实战项目，稳定支撑日均十万+访问量。

你在部署过程中卡在哪一步了？是Apache配置报错，还是前端加载空白？留言告诉我，我帮你诊断！