使用.spec文件时PyInstaller splash启动屏不显示问题排查

问题原因 #

当使用自定义.spec文件打包时，命令行传入的--splash参数不会自动同步到spec配置中，PyInstaller会优先遵循spec文件内的设置，导致启动屏配置被忽略。

解决步骤 #

方法1：手动修改.spec文件添加启动屏配置 #

1. 在.spec文件开头导入Splash类：

from PyInstaller.utils.win32.splash import Splash

2. 在PYZ代码块之后、EXE代码块之前，添加启动屏实例化代码：

# 初始化启动屏，duration为显示时长（单位毫秒），可按需调整
splash = Splash(
    "splash_image.png",
    duration=5000,
    always_on_top=True
)

注意：确保splash_image.png的路径正确，若图片不在当前打包目录，需填写绝对路径。

3. 修改EXE代码块，将splash对象作为参数传入：

executable = EXE(
    python_archive,
    analysis.scripts,
    analysis.binaries,
    analysis.zipfiles,
    analysis.datas,
    splash,  # 添加这一行引入启动屏配置
    [],
    name="AutomationSAP_v3_3",
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=True,
    disable_windowed_traceback=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon="Resources/application.ico",
)

4. 重新执行打包命令：

pyinstaller -F app_build.spec

方法2：重新生成包含启动屏配置的.spec文件 #

1. 先基于主脚本生成带启动屏配置的初始spec文件：

pyinstaller --splash splash_image.png -F main.py

2. 将原app_build.spec中的自定义配置（如datas、hiddenimports、路径设置等）复制到新生成的spec文件中。

3. 使用新的spec文件完成打包：

pyinstaller -F main.spec

额外注意事项 #

• 单文件模式（-F）下，启动屏图片建议使用PNG格式，且尺寸不宜过大，避免加载延迟。
• 若启动屏仍不显示，可尝试关闭UPX压缩（将spec文件中upx=True改为upx=False），部分场景下UPX压缩会干扰启动屏资源加载。

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