如何用PyInstaller打包含QML地图的PySide2独立可执行程序？

我开发了一个简易Python程序，用QQuickWidget创建了包含QML地图的Qt Widget应用。直接运行源码python main.py时功能完全正常，但用PyInstaller打包成单文件可执行程序后，地图显示为空，控制台输出错误：

1, "The geoservices provider is not supported."

如果移除QML中的地图组件，打包后的程序就能正常运行。我使用的打包命令是：

pyinstaller --add-data "view.qml:." --onefile main.py

同时附上了相关代码文件：main.spec、main.py和view.qml，希望能解决这个打包异常问题。

这个问题我之前帮不少开发者排查过，核心原因是PyInstaller默认不会自动识别并打包Qt Location模块依赖的地理服务插件，导致打包后的程序找不到地图服务提供者。下面是一步步的解决方法：

1. 先找到Qt地理服务插件的位置 #

首先得定位你Python环境里Qt Location插件的存放路径，不同的Qt绑定库路径略有不同：

• 如果你用PyQt5：打开Python安装目录下的Lib/site-packages/PyQt5/Qt/plugins/geoservices
• 如果你用PyQt6：路径是Lib/site-packages/PyQt6/Qt6/plugins/geoservices
• PySide2/PySide6的话，把上面的PyQtX换成PySideX就行

这个目录里会有一堆动态库文件（Windows是.dll，Linux是.so，macOS是.dylib），这些就是地图服务的核心插件，PyInstaller没把它们打包进去，所以程序运行时找不到。

2. 修改打包配置，把插件加进去 #

方式一：直接修改打包命令 #

在你原来的命令基础上，多添加一个--add-data参数，把geoservices目录打包进去。比如用PyQt5的话，命令改成这样：

pyinstaller --add-data "view.qml:." --add-data "Lib/site-packages/PyQt5/Qt/plugins/geoservices:geoservices" --onefile main.py

记得把路径换成你自己电脑上的实际路径哦。

方式二：修改spec文件（更靠谱） #

自动生成的main.spec文件能更精细地控制打包过程，打开它后，在datas列表里添加geoservices的映射，同时在hiddenimports里加上Qt Location的相关模块：

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[
        ('view.qml', '.'),
        # 这里替换成你自己的geoservices路径
        ('C:/Python39/Lib/site-packages/PyQt5/Qt/plugins/geoservices', 'geoservices')
    ],
    # 强制让PyInstaller包含这些Qt模块
    hiddenimports=['PyQt5.QtLocation', 'PyQt5.QtPositioning'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
)
# 后面的exe配置保持不变

这样打包时就能确保插件和依赖模块都被包含进去了。

3. 检查QML里的地图配置 #

打开你的view.qml，确认地图的plugin属性指定了正确的服务提供者，比如常用的OpenStreetMap：

Map {
    anchors.fill: parent
    plugin: Plugin {
        name: "osm"  // 这里要和你打包的插件名称对应，osm是默认的开源地图插件
    }
    center: QtPositioning.coordinate(59.91, 10.75)
    zoomLevel: 10
}

如果你用了其他地图服务插件，要确保对应的插件文件也在geoservices目录里，并且名字匹配。

4. 测试打包后的程序 #

重新打包后运行生成的exe文件，如果还是有问题，可以试试去掉--onefile参数，打包成文件夹模式，这样能直接查看打包后的目录里有没有geoservices子目录，以及里面的插件文件是否完整。另外也要确保你的PyQt/PySide版本和Qt版本是匹配的，版本不兼容也可能导致这类问题。

内容的提问来源于stack exchange，提问作者P. Arias