使用PyInstaller打包PySide6 QMediaPlayer程序时的运行异常问题

问题场景 #

使用PySide6的QMediaPlayer开发的音频播放器，在Windows x64系统控制台执行python3 myplayer.py时，GUI界面及功能均正常运行。但通过pyinstaller -w --onedir myplayer.py打包为Windows可执行文件后，生成的.exe文件无法运行且无任何错误提示。演示代码如下：

import os
import sys
import PySide6
from PySide6.QtCore import Qt,QUrl
from PySide6.QtWidgets import QApplication,QMainWindow,QWidget
from PySide6.QtWidgets import QHBoxLayout
from PySide6.QtMultimedia import QSoundEffect, QMediaPlayer, QAudioOutput
from PySide6.QtWidgets import QPushButton

class PlugPlayer(QMainWindow):
    def __init__(self, parent=None, flags=Qt.Widget):
        super(PlugPlayer, self).__init__(parent)
        self.main_widget = QWidget(self)
        self.layout = QHBoxLayout(self.main_widget)
        self.player = QMediaPlayer()
        self.audioOutput = QAudioOutput()
        self.player.setAudioOutput(self.audioOutput)
        
        self.loadwavfile = r'D:\test\demo.wav'
        self.player.setSource(QUrl.fromLocalFile(self.loadwavfile))
        self.audioOutput.setVolume(20)

        self.plbtn = QPushButton("Play")
        self.stbtn = QPushButton("Stop")
        self.pabtn = QPushButton("Pause")
        self.layout.addWidget(self.plbtn)
        self.layout.addWidget(self.stbtn)
        self.layout.addWidget(self.pabtn)
        #widget action
        self.plbtn.clicked.connect(self.PlaySound)
        self.stbtn.clicked.connect(self.StopSound)
        self.pabtn.clicked.connect(self.PauseSound)


    def PlaySound(self):
        if self.loadwavfile is not None:
            self.player.play()

    def StopSound(self):
        self.player.stop()
    def PauseSound(self):
        self.player.pause()

def main():
    app = QApplication(sys.argv)
    widget = PlugPlayer()
    widget.show()
    return app.exec()

if __name__ == '__main__':
    main()

解决方法 #

1. 打包时收集Qt多媒体依赖 #

PyInstaller默认不会自动打包QMediaPlayer所需的多媒体插件（如解码器、音频驱动相关组件），需要显式指定收集相关数据。修改打包命令为：

pyinstaller -w --onedir --collect-data PySide6.QtMultimedia myplayer.py

--collect-data参数会确保PySide6.QtMultimedia下的所有资源和插件被复制到打包后的目录中。

2. 修复音频文件路径问题 #

代码中使用了绝对路径D:\test\demo.wav，打包后如果exe文件和音频文件不在对应位置，会导致程序找不到音频文件而静默失败。建议改为相对路径，确保exe和音频文件在同一目录：

# 替换原路径代码
self.loadwavfile = os.path.join(os.path.dirname(os.path.abspath(__file__)), "demo.wav")
self.player.setSource(QUrl.fromLocalFile(self.loadwavfile))

3. 临时关闭无控制台模式排查错误 #

打包时去掉-w参数，保留控制台窗口，这样运行exe时可以看到详细的错误输出，帮助定位问题：

pyinstaller --onedir myplayer.py

运行生成的exe文件，控制台会显示具体的错误信息（如缺失插件、文件找不到等），便于针对性解决。

4. 手动指定Qt插件路径 #

如果打包后仍无法找到多媒体插件，可以在代码中手动设置Qt的插件路径，确保程序能正确加载所需组件。在main函数开头添加以下代码：

def main():
    # 设置Qt插件路径，适配开发和打包环境
    if hasattr(sys, '_MEIPASS'):
        # 打包后的运行环境
        plugin_path = os.path.join(sys._MEIPASS, 'PySide6', 'plugins')
    else:
        # 开发环境
        plugin_path = os.path.join(os.path.dirname(PySide6.__file__), 'plugins')
    PySide6.QtCore.QCoreApplication.addLibraryPath(plugin_path)
    
    app = QApplication(sys.argv)
    widget = PlugPlayer()
    widget.show()
    return app.exec()

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