PyQt6 QWebEngineView加载谷歌地图API显示空白问题求助

1. 本地文件跨域限制：QWebEngineView对file://协议的资源加载有更严格的CORS（跨域资源共享）策略，谷歌地图API需要从远程服务器加载JS、图片等资源，本地文件协议下这类跨域请求可能被拦截，导致API加载失败。
2. API密钥配置问题：即使浏览器能正常加载，PyQt的WebEngine环境可能使用不同的用户代理或请求上下文，若API密钥设置了HTTP referrer限制，file://协议没有合法referrer，会触发密钥验证失败；另外需确认密钥已启用Google Maps JavaScript API、未超限或过期。
3. QWebEngineView设置缺失：默认配置下可能未完全允许第三方资源加载、JavaScript权限不足，导致地图API无法正常初始化。

方法1：通过本地HTTP服务器加载页面 #

绕过file://协议的跨域限制，将HTML文件放在本地HTTP服务器中，用http://localhost地址加载：

import sys
import threading
import os
from http.server import HTTPServer, SimpleHTTPRequestHandler
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QWebEngineView
from PyQt6.QtCore import QUrl

def run_local_server(html_dir):
    os.chdir(html_dir)
    server = HTTPServer(('localhost', 8000), SimpleHTTPRequestHandler)
    server.serve_forever()

if __name__ == "__main__":
    app = QApplication(sys.argv)
    package_path = get_package_path(package_name)  # 替换为你的实际路径

    # 启动后台HTTP服务器
    server_thread = threading.Thread(target=run_local_server, args=(package_path,), daemon=True)
    server_thread.start()

    window = QWidget()
    layout = QVBoxLayout()
    map_view = QWebEngineView()
    # 加载本地服务器上的地图页面
    map_view.load(QUrl("http://localhost:8000/map.html"))
    layout.addWidget(map_view)
    window.setLayout(layout)
    window.show()
    sys.exit(app.exec())

方法2：调整QWebEngineView的安全配置 #

修改WebEngine的配置，允许本地文件访问远程资源：

from PyQt6.QtWebEngineCore import QWebEngineProfile
from PyQt6.QtWebEngineWidgets import QWebEngineSettings

# 获取默认配置文件
profile = QWebEngineProfile.defaultProfile()
# 允许本地文件访问远程URL
profile.setHttpAllowAccessFromFileUrls(True)
profile.setHttpAccessControlAllowOriginEnabled(True)

# 确保JavaScript及相关权限开启
map_view = QWebEngineView()
settings = map_view.settings()
settings.setAttribute(QWebEngineSettings.WebAttribute.JavascriptEnabled, True)
settings.setAttribute(QWebEngineSettings.WebAttribute.JavascriptCanAccessClipboard, True)
settings.setAttribute(QWebEngineSettings.WebAttribute.JavascriptCanOpenWindows, True)
settings.setAttribute(QWebEngineSettings.WebAttribute.AllowRunningInsecureContent, True)  # 若加载HTTP资源时需要

方法3：检查并修正API密钥配置 #

• 登录谷歌云控制台，确认已启用Google Maps JavaScript API；
• 在密钥的「应用限制」中，添加http://localhost/*到允许的HTTP referrers列表（若用本地HTTP服务器）；
• 若坚持用file://协议，可尝试暂时取消密钥的referrer限制（仅测试用，生产环境不建议），或确认谷歌地图API支持file://协议的请求。

方案1：使用Qt Location原生组件 #

无需依赖WebEngine，直接用Qt官方的位置模块加载地图：

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout
from PyQt6.QtPositioning import QGeoCoordinate
from PyQt6.QtLocation import QGeoServiceProvider, QMapWidget

if __name__ == "__main__":
    app = QApplication(sys.argv)
    # 设置谷歌地图API密钥（需提前在环境变量或代码中配置）
    import os
    os.environ["QT_GOOGLE_MAPS_API_KEY"] = "你的谷歌API密钥"

    window = QWidget()
    layout = QVBoxLayout()
    # 初始化谷歌地图服务
    service_provider = QGeoServiceProvider("google")
    map_widget = QMapWidget()
    map_widget.setServiceProvider(service_provider)
    # 设置地图中心（示例为旧金山坐标）
    center = QGeoCoordinate(37.7749, -122.4194)
    map_widget.setCenter(center)
    map_widget.setZoomLevel(12)
    layout.addWidget(map_widget)
    window.setLayout(layout)
    window.show()
    sys.exit(app.exec())

注意：需确保PyQt6安装了qtlocation模块，若使用pip安装，可执行pip install pyqt6==<版本> pyqt6-qt6==<版本>（需对应版本）。

方案2：替换为OpenStreetMap #

若不需要谷歌地图的专属功能，OpenStreetMap无需API密钥，可直接通过QWebEngineView加载，或用Qt Location集成，避免密钥和跨域问题。

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