cx_Freeze 的 setup.py 配置文件全面详解

以下为 cx_Freeze 的 setup.py 配置文件全面详解，涵盖所有核心配置项及其用法，结合多篇权威文档整理而成：

🔧 ​​一、Executable 可执行文件配置​​

用于定义生成的可执行文件属性，核心参数如下：

python

运行

from cx_Freeze import Executable

executable = Executable(
    script="main.py",          # 主入口脚本路径 [1,3](@ref)
    base="Win32GUI",           # Windows GUI应用隐藏控制台（None为控制台应用）[1,6](@ref)
    targetName="MyApp.exe",    # 输出文件名（默认同脚本名）[4,6](@ref)
    icon="app.ico",            # 应用图标（.ico或.icns）[1,4](@ref)
    copyright="Copyright 2025", # 版权信息（Windows生效）[6](@ref)
    shortcutName="MyApp",      # 快捷方式名称（安装包生效）[6](@ref)
    shortcutDir="ProgramMenuFolder"  # 快捷方式目录（如DesktopFolder）[6](@ref)
)

📦 ​​二、setup() 基础元数据配置​​

定义项目基础信息：

python

from cx_Freeze import setup

setup(
    name="MyApp",              # 应用名称 [1,3](@ref)
    version="1.0.0",           # 版本号 [1](@ref)
    description="App Description", # 描述信息 [3](@ref)
    author="Your Name",         # 作者 [6](@ref)
    url="https://example.com",  # 项目主页 [6](@ref)
    options={...},             # 构建选项（见第三节）
    executables=[executable]   # 绑定可执行文件配置 [1](@ref)
)

⚙️ ​​三、build_exe 构建选项详解​​

通过 options 字典配置打包细节，所有参数均位于 "build_exe" 键下：

options = {
    "build_exe": {
        # --- 依赖管理 ---
        "packages": ["numpy", "requests"],  # 强制包含的Python包 [1,4](@ref)
        "excludes": ["tkinter", "unittest"],# 排除的模块（减小体积）[4,6](@ref)
        "includes": ["module.utils"],       # 显式包含的特定模块 [6](@ref)
        "namespace_packages": ["zope"],     # 包含命名空间包 [6](@ref)

        # --- 文件处理 ---
        "include_files": ["data/", "config.ini"],  # 包含非代码文件/文件夹 [1,3](@ref)
        "zip_include_packages": ["*"],      # 压缩所有包为ZIP（减小体积）[4,6](@ref)
        "zip_exclude_packages": ["PyQt5"],  # 排除压缩的包（需解压运行时）[6](@ref)
        "bin_includes": ["libssl.so"],      # 包含二进制文件（Linux/macOS）[6](@ref)
        "bin_excludes": ["vcruntime140.dll"], # 排除系统二进制文件 [6](@ref)

        # --- 路径与优化 ---
        "path": ["src/", "/custom/path"],   # 扩展模块搜索路径 [6](@ref)
        "replace_paths": [("*/dev/*", "")], # 路径替换规则（隐藏敏感路径）[6](@ref)
        "optimize": 2,                      # 字节码优化级别（0-2）[1](@ref)
        "silent": True,                     # 静默模式（抑制非必要输出）[6](@ref)

        # --- 平台特定 ---
        "include_msvcr": True,              # 包含MSVC运行时库（Windows）[1,6](@ref)
        "append_script_to_exe": False,       # 是否将脚本嵌入exe（默认False）[6](@ref)
    }
}

python

🛠️ ​​四、高级配置技巧​​

1. ​​资源文件路径处理​​
   在代码中动态获取资源路径，避免硬编码：

   python

   import sys, os
   if hasattr(sys, '_MEIPASS'):
       resource_path = os.path.join(sys._MEIPASS, "data/file.txt")  # 打包后路径 [1](@ref)
   else:
       resource_path = "data/file.txt"  # 开发环境路径

2. ​​多平台适配​​

   python

   运行

   base = "Win32GUI" if sys.platform == "win32" else None  # 自动切换GUI模式 [3,6](@ref)

3. ​​虚拟环境打包​​
   推荐在 venv 中安装最小依赖，避免无关库增大体积：

   bash

   复制

   python -m venv build_env
   source build_env/bin/activate
   pip install cx_Freeze numpy ...
   python setup.py build

🌐 ​​五、跨平台打包注意事项​​

• ​​Windows​​：需设置 base="Win32GUI" 隐藏控制台；图标用 .ico 
• ​​macOS​​：图标需 .icns 格式；生成无后缀可执行文件 
• ​​Linux​​：需安装依赖 libxcb-xinerama0 等（视GUI库而定）

💎 ​​完整配置示例​​

python

运行

import sys
from cx_Freeze import setup, Executable

# 可执行文件配置
base = "Win32GUI" if sys.platform == "win32" else None
executables = [Executable(
    script="app.py",
    base=base,
    targetName="MyApp",
    icon="icon.ico"
)]

# 构建选项
build_options = {
    "build_exe": {
        "packages": ["numpy", "PyQt5"],
        "excludes": ["tkinter", "test"],
        "include_files": ["assets/", "settings.json"],
        "zip_include_packages": ["*"],
        "include_msvcr": True,
        "optimize": 1
    }
}

# 元数据
setup(
    name="MyApp",
    version="1.0",
    description="Cross-platform App",
    options=build_options,
    executables=executables
)

运行打包命令：

bash

复制

python setup.py build  # 生成目录
python setup.py bdist_msi  # 生成Windows安装包（需安装msilib）[1](@ref)

⚠️ ​​常见问题解决​​

• ​​依赖缺失​​：在 packages 中显式添加遗漏库 

  1

• ​​图标无效​​：确认图标格式正确（Windows: .ico, macOS: .icns）

  4

• ​​文件路径错误​​：使用 sys._MEIPASS 动态定位资源 

  1

• ​​体积过大​​：通过 excludes 移除无用库，启用 zip_include_packages