使用cx_Freeze将Python转为MSI后安装无法运行的问题

问题现象 #

使用cx_Freeze打包Python程序生成MSI文件，安装后控制面板显示程序已安装，但无法找到快捷方式，程序也无法正常运行。

原打包代码 #

import sys
from cx_Freeze import setup, Executable

company_name = 'AI Production'
product_name = 'AI'

bdist_msi_options = {
    'upgrade_code': '{66620F3A-DC3A-11E2-B341-002219E9B01E}',
    'add_to_path': False,
    'initial_target_dir': r'[ProgramFilesFolder]\%s\%s' % (company_name, product_name),
    }

build_exe_options = {"bdist_msi":{"packages":["tkinter", "tkcalendar", "PIL", "random", "speech_recognition", "time", "sqlite3", 
                                            "pyttsx3", "threading", "datetime", "AppOpener", "wave", "pyaudio", "wikipedia", "requests",
                                            "numpy", "cv2", "autocorrect", "pyautogui", "webbrowser", 'bs4', 'GoogleNews',
                                            'winsound', 'pywhatkit'],
                    "include_files":['Animation/bow_animation.gif', 'Animation/hand_waving_animation.gif', 
                                    'Animation/idle_animation.gif', 'Animation/logo_animation.gif',
                                    'Animation/start_walking_animation.gif', 'database/text.txt',
                                    'document/text.txt', 'icons/desktop.ico', 'icons/logo.ico',
                                    'icons/mic_off.ico', 'icons/mic.ico', 'icons/person.ico',
                                    'icons/save.ico', 'icons/sending icon.ico', 'icons/setting_icon.ico',
                                    'icons/user.ico', 'Image/bg.png', 'Image/bg/color_circle_deb3e0.png',
                                    'Image/bg/color_pallet_212b2a.png', 'Image/bg/color_pallet_custom.png',
                                    'Image/bg/color_pallet_404a4c.png', 'Image/bg/color_pallet_d6e6ff.png',
                                    'Image/bg/color_pallet_d7f9f8.png', 'Image/bg/color_pallet_e5d4ef.png',
                                    'Image/bg/color_pallet_f9d7f8.png', 'Image/bg/color_pallet_fbb8ed.png',
                                    'Image/bg/color_pallet_fbe0e0.png', 'Image/gr.png', 'voice/mic_starter.mp3',
                                    'voice/timer_alarm.wav']},
    }

base = 'Win32GUI'

exe = Executable(script='AI.pyw',
                 base=base,
                 icon='icons\logo.ico',
                )

setup(name=product_name,
      version='1.0.0',
      description='blah',
      executables=[exe],
      options={
          'bdist_msi': bdist_msi_options,
          'build_exe': build_exe_options})

问题根源分析 #

1. build_exe_options结构错误：原代码将packages和include_files嵌套在bdist_msi子键下，导致cx_Freeze无法识别这些构建配置，打包时缺失依赖包和资源文件，程序无法运行。
2. 未配置快捷方式生成：cx_Freeze默认不会自动创建开始菜单/桌面快捷方式，需手动配置相关参数。
3. 路径转义问题：图标路径使用单反斜杠icons\logo.ico，在Python字符串中会被解析为转义字符，可能导致图标加载失败。
4. 潜在依赖缺失：cv2、pyaudio等第三方库依赖系统级DLL文件，cx_Freeze可能无法自动检测并包含。

修复后的代码 #

import sys
from cx_Freeze import setup, Executable

company_name = 'AI Production'
product_name = 'AI'

bdist_msi_options = {
    'upgrade_code': '{66620F3A-DC3A-11E2-B341-002219E9B01E}',
    'add_to_path': False,
    'initial_target_dir': r'[ProgramFilesFolder]\%s\%s' % (company_name, product_name),
    # 配置开始菜单快捷方式
    'shortcuts': [
        {
            'name': product_name,
            'description': 'AI Application',
            'target': '[ProgramFilesFolder]\\%s\\%s\\AI.exe' % (company_name, product_name),
            'directory': 'ProgramMenuFolder',
            'icon': '[ProgramFilesFolder]\\%s\\%s\\icons\\logo.ico' % (company_name, product_name)
        }
    ]
}

build_exe_options = {
    "packages": ["tkinter", "tkcalendar", "PIL", "random", "speech_recognition", "time", "sqlite3", 
                 "pyttsx3", "threading", "datetime", "AppOpener", "wave", "pyaudio", "wikipedia", "requests",
                 "numpy", "cv2", "autocorrect", "pyautogui", "webbrowser", 'bs4', 'GoogleNews',
                 'winsound', 'pywhatkit'],
    "include_files": [
        ('Animation/bow_animation.gif', 'Animation/bow_animation.gif'),
        ('Animation/hand_waving_animation.gif', 'Animation/hand_waving_animation.gif'),
        ('Animation/idle_animation.gif', 'Animation/idle_animation.gif'),
        ('Animation/logo_animation.gif', 'Animation/logo_animation.gif'),
        ('Animation/start_walking_animation.gif', 'Animation/start_walking_animation.gif'),
        ('database/text.txt', 'database/text.txt'),
        ('document/text.txt', 'document/text.txt'),
        ('icons/desktop.ico', 'icons/desktop.ico'),
        ('icons/logo.ico', 'icons/logo.ico'),
        ('icons/mic_off.ico', 'icons/mic_off.ico'),
        ('icons/mic.ico', 'icons/mic.ico'),
        ('icons/person.ico', 'icons/person.ico'),
        ('icons/save.ico', 'icons/save.ico'),
        ('icons/sending icon.ico', 'icons/sending icon.ico'),
        ('icons/setting_icon.ico', 'icons/setting_icon.ico'),
        ('icons/user.ico', 'icons/user.ico'),
        ('Image/bg.png', 'Image/bg.png'),
        ('Image/bg/color_circle_deb3e0.png', 'Image/bg/color_circle_deb3e0.png'),
        ('Image/bg/color_pallet_212b2a.png', 'Image/bg/color_pallet_212b2a.png'),
        ('Image/bg/color_pallet_custom.png', 'Image/bg/color_pallet_custom.png'),
        ('Image/bg/color_pallet_404a4c.png', 'Image/bg/color_pallet_404a4c.png'),
        ('Image/bg/color_pallet_d6e6ff.png', 'Image/bg/color_pallet_d6e6ff.png'),
        ('Image/bg/color_pallet_d7f9f8.png', 'Image/bg/color_pallet_d7f9f8.png'),
        ('Image/bg/color_pallet_e5d4ef.png', 'Image/bg/color_pallet_e5d4ef.png'),
        ('Image/bg/color_pallet_f9d7f8.png', 'Image/bg/color_pallet_f9d7f8.png'),
        ('Image/bg/color_pallet_fbb8ed.png', 'Image/bg/color_pallet_fbb8ed.png'),
        ('Image/bg/color_pallet_fbe0e0.png', 'Image/bg/color_pallet_fbe0e0.png'),
        ('Image/gr.png', 'Image/gr.png'),
        ('voice/mic_starter.mp3', 'voice/mic_starter.mp3'),
        ('voice/timer_alarm.wav', 'voice/timer_alarm.wav')
    ],
    # 可选：包含VC运行时库（若程序依赖）
    # "include_msvcr": True
}

base = 'Win32GUI' if sys.platform == 'win32' else None

exe = Executable(
    script='AI.pyw',
    base=base,
    icon='icons/logo.ico',  # 改用正斜杠避免转义问题
)

setup(
    name=product_name,
    version='1.0.0',
    description='AI Application',
    executables=[exe],
    options={
        'bdist_msi': bdist_msi_options,
        'build_exe': build_exe_options
    }
)

关键修复点说明 #

1. 修正build_exe结构：将packages和include_files设为build_exe_options的顶级键，确保cx_Freeze正确包含依赖和资源。
2. 添加快捷方式配置：在bdist_msi_options中定义shortcuts，指定快捷方式的名称、目标路径和所在目录。
3. 修复路径转义：将所有路径中的单反斜杠替换为正斜杠，避免转义错误。
4. 补充依赖DLL：若cv2、pyaudio等库依赖额外DLL（如opencv_worldXXX.dll、portaudio.dll），需手动添加到include_files中。

额外排查建议 #

• 前往安装目录（C:\Program Files\AI Production\AI），双击AI.exe查看具体错误提示，根据提示补充缺失文件。
• 检查build目录下的打包日志，定位未被正确包含的资源或依赖。
• 确保程序代码中使用的资源路径与include_files中的路径一致，避免运行时找不到文件。

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