PyQGIS使用QgsRasterLayer加载HTTPS协议WMS服务失败如何解决

问题复现 #

使用QgsRasterLayer加载HTTPS协议WMS服务时，执行如下代码图层校验不通过，控制台输出error，无法成功加载图层：

uri = '''https://vmap0.tiles.osgeo.org/wms/vmap0?LAYERS=basic&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&FORMAT=image%2Fjpeg&SRS=EPSG%3A4326&BBOX=-90,45,-45,90&WIDTH=256&HEIGHT=256 '''
layer = QgsRasterLayer(uri, "RESA", "WMS")
if layer.isValid():
    pass
else:
    print('error')

查阅PyQGIS官方API文档未找到对应解决方案。

失败原因 #

传入的URI格式不符合QGIS WMS数据提供者的解析规则：

• 直接拼接了完整的单次GetMap请求地址，包含固定BBOX、宽高这类仅单次请求有效的参数，QGIS无法识别为可动态渲染的WMS图层
• QGIS的WMS提供者不会自动从完整GetMap URL中提取服务配置参数，必须按照指定键值对格式传入基础服务参数

修复代码 #

按照WMS提供者要求的格式构造URI，无需手动拼接GetMap请求的动态参数，QGIS会在渲染时自动根据画布范围生成对应请求：

from qgis.core import QgsProject, QgsRasterLayer

# 按QGIS WMS规则构造URI，仅传入基础服务参数
uri = (
    "url=https://vmap0.tiles.osgeo.org/wms/vmap0"
    "?layers=basic"
    "&styles="
    "&format=image/jpeg"
    "&srs=EPSG:4326"
    "&version=1.1.1"
)
layer = QgsRasterLayer(uri, "RESA", "wms")
if layer.isValid():
    # 加载成功后添加到当前项目
    QgsProject.instance().addMapLayer(layer)
else:
    # 打印具体错误信息方便排查
    print(f"图层加载失败：{layer.error().message()}")

补充说明 #

• 构造WMS图层URI时，不需要手动拼接REQUEST=GetMap、BBOX、WIDTH、HEIGHT这类动态参数，这类参数由QGIS在渲染过程中自动生成
• HTTPS协议本身不需要额外特殊配置，如果遇到SSL证书相关报错，可以在QGIS选项的SSL配置中调整证书验证规则，或导入服务对应的根证书
• 如果需要加载需要鉴权的WMS服务，可以在URI中追加username、password参数传入鉴权信息

内容的提问来源于stack exchange，提问作者elephant111