企业官网建设流程全解析

• 开发工具
• CLI

PyOxidizer 不仅负责把 Python 应用构建成单个可执行文件、把 Python 资源打包进二进制，还提供了一套完整的分发（distribution）能力，帮助你把产物安装到目标机器上。本文基于 pyoxidizer_distributing_overview.rst 展开，介绍 PyOxidizer 的分发架构——Tugger 工具、Starlark 分发方言、二进制可移植性评估以及 Windows 安装包生成，读完后你将掌握 PyOxidizer 从"产出二进制"到"产出可安装交付物"的完整技术路径，并能针对 Linux、macOS、Windows 分别规划分发策略。

分发（Distribution）与构建、打包是两个不同的领域

PyOxidizer 官方文档将应用生命周期明确划分为三个相互独立的领域：

• 构建（building）：关心的是"产出构成应用的哪些文件"——运行时需要的可执行文件和支持文件；
• 打包（packaging）：关心的是把 Python 解释器、标准库、第三方依赖等资源组织进二进制的形态（这部分由PythonExecutable等类型在 pyoxidizer/docs/pyoxidizer_packaging.rst 系列文档中阐述）；
• 分发（distribution）：关心的是"把这些文件安装到其他机器上"——生成安装包、处理目标平台的运行时依赖、评估二进制可移植性。

理解这个边界很重要：一个构建得很完美的二进制，如果分发环节没有处理好目标机器的运行时依赖（例如缺少 Visual C++ Redistributable），到了用户手里依然无法运行。PyOxidizer 的分发能力正是为了解决这一"最后一公里"问题而设计的。

Tugger：PyOxidizer 的分发引擎

PyOxidizer 将大部分分发功能委托给Tugger工具实现（见 tugger/docs/tugger.rst）。Tugger 是随 PyOxidizer 同步开发的 Rust crate 与 Starlark 方言集合，专注于应用分发所需的通用能力。它在技术上是一个独立项目——即使不用 PyOxidizer，也可以单独使用 Tugger 来制作分发产物；而 PyOxidizer 则完整继承了 Tugger 的 Starlark 功能，并对其做了 Python 应用专属的扩展，使分发 Python 应用更加简单。

平台无关与"文件中心"的设计理念

根据 tugger/docs/tugger_overview.rst，Tugger 的设计有两个显著特点：

1. 平台无关、进程内实现：Tugger 的目标是尽可能在进程内完成所有打包逻辑，不依赖rpmbuild、debuild这类外部工具。例如，RPM 和 Debian 包是通过 Rust 代码直接构造原始归档文件生成的，因此理论上可以在 Windows 上生成 Linux.deb、在 macOS 上生成 Windows MSI 安装器、在 Linux 上生成 macOS DMG。
2. 文件中心视角（file-centric）：Tugger 的大多数打包设施以"一组输入文件 + 一种输出分发格式"的方式工作，而不是像传统打包工具那样内置一套定制构建系统。这带来的副作用是：Tugger 通常不关心文件是怎么构建出来的，需要由你（通过 Starlark 脚本）先产出待分发的文件，再交给 Tugger 组装。

模块化的 Rust crate 架构

Tugger 由一系列领域专属的 Rust crate（文档中称为fleet）组成，每个 crate 提供单一领域能力。官方文档列出的核心 crate 包括：

在当前仓库中，可以观察到这套 crate 体系的实际布局：tugger-binary-analysis/、tugger-common/、tugger-windows/、tugger-wix/、tugger-rpm/、tugger-snapcraft/、tugger-apple/、tugger-code-signing/、tugger-rust-toolchain/ 等均作为独立目录存在，印证了"每个 crate 独立、可复用"的设计初衷。

用 Starlark 方言描述分发：通用原语 + Python 专属扩展

Tugger 使用 Starlark）。

PyOxidizer 配置文件（pyoxidizer.bzl）可以使用完整的 Tugger Starlark 方言，并且有两种使用层次：

• Tugger 提供的通用原语：通常比较底层、通用，与具体语言无关，例如FileManifest（文件清单）、WiXMSIBuilder、WiXBundleBuilder、FileContent等类型；
• PyOxidizer 提供的扩展：Python 应用专属，往往能让配置文件更简洁——例如不必手动组装 WiX 安装器，而是直接调用PythonExecutable上的方法把它"一键"转换成安装器构建器。

PyOxidizer 对 Tugger 方言的扩展清单

根据 pyoxidizer/docs/pyoxidizer_distributing_wix.rst，PyOxidizer 提供了以下关键扩展与集成：

• FileManifest.add_python_resource：向 Tugger 的FileManifest添加一个 Python 资源类型；
• FileManifest.add_python_resources：向FileManifest添加一组（iterable）Python 资源类型；
• PythonExecutable.to_file_manifest：把PythonExecutable转换为FileManifest，从而把可执行程序/应用物化为一组文件，供 Tugger 直接操作；
• PythonExecutable.to_wix_bundle_builder：把PythonExecutable转换为预先配置好的WiXBundleBuilder，产出的.exe安装器"开箱即用"；
• PythonExecutable.to_wix_msi_builder：把PythonExecutable转换为预先配置好的WiXMSIBuilder，安装 Python 应用及其全部支持文件（不含系统级依赖）。

这些方法的签名与参数细节收录在 pyoxidizer/docs/pyoxidizer_config_type_python_executable.rst 中。

源码视角：这些方法是如何实现的

从源码可以看到这些扩展的实际调用链（pyoxidizer/src/starlark/python_executable.rs#L860-L966）：

• to_wix_msi_builder()首先调用to_file_manifest(type_values, ".".to_string())把可执行程序物化为文件清单，再创建WiXMsiBuilderValue，最后调用builder.add_program_files_manifest(...)把文件清单注册为"Program Files"安装目录下的内容；
• to_wix_bundle_builder()则在内部先调用to_wix_msi_builder()生成 MSI 构建器（并可传入msi_builder_callback函数对 MSI 做二次定制），随后根据目标三元组（target triple）自动附加 VC++ Redistributable：目标为i686-pc-windows-msvc时附加 x86 版、x86_64-pc-windows-msvc时附加 x64 版，最后把 MSI 构建器包进WiXBundleBuilder并add_wix_msi_builder(...)。这就是"生成的.exe安装器会自带 VC++ Redistributable 安装器并自动执行"的底层来源。

分发前的质量关卡：评估二进制可移植性

二进制可移植性（binary portability）指在机器/环境 X 上构建的二进制，能否在不做修改的情况下直接拷贝到机器/环境 Y 上运行。PyOxidizer 能构建高度可移植的二进制，但具体做法因操作系统与目标平台而异，官方专门编写了 pyoxidizer_distributing_binary_portability.rst 讲述通用策略。

用pyoxidizer analyze评估产物

pyoxidizer analyze命令是 PyOxidizer 提供的可移植性评估工具，用于分析可执行文件与库的内容。以 ELF 二进制（Linux 格式）为例，它会：

• 列出所有共享库依赖；
• 分析 glibc 符号版本；
• 打印它认为该二进制兼容的 Linux 发行版版本范围。

需要说明的是，官方文档提示该命令尚未在所有平台上功能完备。

Linux：构建环境会"泄漏"进产物

pyoxidizer_distributing_linux.rst 给出了 Linux 分发的关键结论：

• musl libc 是例外：针对x86_64-unknown-linux-musl构建的二进制完全静态链接、自包含，几乎可以在任何支持该架构的 Linux 机器上运行。如果ldd /path/to/binary输出not a dynamic executable，说明二进制很可能高度可移植（静态链接的构建方法见 pyoxidizer_packaging_static_linking.rst）；
• 默认 Python 发行版本身很可移植：*-unknown-linux-gnu构建只依赖libc.so.6，且构建时校验所引用 glibc 符号版本不高于 glibc 2.19（2014 年发布），因此兼容 Fedora 21+、RHEL/CentOS 7+、openSUSE 13.2+、Debian 8+（Jessie）、Ubuntu 14.04+ 等常见发行版；
• 但你自己的二进制不一定：用 PyOxidizer 编译的新代码是在本机环境完成的，构建机的编译设置会泄漏进产物。文档给出的实例是：在 Ubuntu 20.10 上pyoxidizer build出的 ELF 二进制会依赖libgcc_s.so.1并引用 glibc 2.32 符号版本，尽管默认 Python 发行版只要求 glibc 2.19；
• 管理策略：glibc 会记录符号版本，链接时采用链接机 glibc 的版本。要最大化可移植性，应在较旧的 glibc 环境构建（默认 Python 发行版使用 Debian 8 作为构建环境，Ubuntu 14.04、openSUSE 13.2/42.1、RHEL/CentOS 7、Fedora 21 也是候选），或干脆产出完全静态链接的二进制。

macOS：SDK 与部署目标管理

pyoxidizer_distributing_macos.rst 说明：

• 默认 Python 发行版针对 x86_64 要求 macOS 10.9+、针对 aarch64 要求 11.0+；
• 构建机必须使用不早于 Python 发行版所用版本的 Apple SDK，否则链接时可能出现未定义符号错误。PyOxidizer 会自动定位/校验 Apple SDK（基于xcode-select --print-path指向的目录，通常是/Applications/Xcode.app/Contents/Developer），可用DEVELOPER_DIR指定替代目录，或用SDKROOT强制指定某个 SDK，例如：

DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer pyoxidizer build SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk pyoxidizer build

• PyOxidizer 目前只产出单架构二进制，不支持原生universal/fat二进制；要让 Intel 与 ARM 机器都能运行，需分别维护两份产物或在 PyOxidizer 之外制作 fat 二进制；
• 构建环境同样会向产物引入较新的 macOS SDK 特性，通常通过设置MACOSX_DEPLOYMENT_TARGET指定支持的最老 macOS 版本来规避，例如MACOSX_DEPLOYMENT_TARGET=10.15 pyoxidizer build。PyOxidizer 会自动将部署目标设置为与所用 Python 发行版一致，多数情况下无需手动设置。

Windows：运行时 DLL 依赖是重中之重

Windows 分发的详细考量记录在 pyoxidizer_distributing_windows.rst，要点如下：

• 操作系统要求：默认 Python 发行版要求 Windows 8 / Windows Server 2012 或更新版本（官方 Python 3.8 支持 Windows 7，但 PyOxidizer 为简化支持放弃了对 Windows 7 的支持）；
• 运行时依赖：默认发行版依赖 Microsoft Visual C++ Redistributable 与 Universal CRT（UCRT）。standalone_dynamic（默认发行版口味）还依赖 OpenSSL、SQLite3 等第三方 DLL，但它们是 Python 发行版的一部分，PyOxidizer 会在需要时自动安装；
• 应用专属依赖：安装自定义 Python 包时，PyOxidizer 会尽量识别并安装其中的编译扩展与.dll依赖，但仍存在边界情况；官方建议用 Dependency Walker 或pyoxidizer analyze检查二进制是否有缺失 DLL 引用，并在全新安装的 Windows 环境（而非预装了大量软件的虚拟机）中实测。

Windows 安装包实战：VC++ Redistributable 与 WiX 集成

Windows 上最常见的两个分发问题是Visual C++ Redistributable与UCRT。

Visual C++ Redistributable 的两种管理方式

PyOxidizer 构建的二进制常依赖文件名形如vcruntime140.dll、vcruntime140_1.dll的 DLL。VC++ Redistributable 不是 Windows 核心组件，全新安装的系统上可能缺失，必须在分发时主动处理。PyOxidizer 提供两种内置方案：

方式一：随安装器安装（installer 模式）

PyOxidizer 内部记录了vc_redist<arch>.exe安装器的下载 URL 与 SHA-256。在源码 tugger-windows/src/vc_redistributable.rs#L23-L45 中可以找到这些记录：VC_REDIST_X86、VC_REDIST_X64、VC_REDIST_ARM64三个常量均包含指向 Microsoft 官方下载地址的url字段与对应sha256字段。构建应用安装器时，这些文件会从 Microsoft 服务器下载并内嵌进新的 meta-installer；安装时如果系统缺少这些文件，嵌入的安装器会被自动执行，把 VC++ 文件安装到系统级位置，供任何应用使用。若系统已存在更新版本，安装器会 no-op，不会降级。

对应的 Starlark 入口为PythonExecutable.to_wix_bundle_builder与WiXBundleBuilder.add_vc_redistributable。

方式二：把 DLL 放在二进制旁边（本地文件模式）

另一种方式是直接把vcruntime140[_1].dll拷贝到myapp.exe同目录下——Windows 会优先从可执行文件所在目录加载 DLL，因此"开箱即用"。控制该行为的 Starlark 属性是PythonExecutable.windows_runtime_dlls_mode（详见 pyoxidizer/docs/pyoxidizer_config_type_python_executable.rst），支持三个取值：

该模式依赖vswhere.exe定位本机 Visual Studio 安装中的Microsoft.VisualCPP.Redist.<version>.Latest组件（<version>对vcruntime140.dll是14），因此要求本机装有支持 C/C++ 开发的 Visual Studio 2017/2019；找不到时可在 Visual Studio Installer → Modify → Individual Components 中勾选 redistributable 相关组件。开启后，VC++ 文件会像普通补充文件一样被物化到文件系统，也会出现在to_file_manifest、to_wix_msi_builder等方法的文件列表中。

重要提示：两种方式可以同时存在但属于冗余。官方建议：当安装器已内嵌 VC++ Redistributable 时，把windows_runtime_dlls_mode设为"never"，避免重复安装（本地文件通常会被优先使用）。源码中的测试用例也覆盖了这三个取值与非法值的校验（pyoxidizer/src/starlark/python_executable.rs#L1389-L1408）。

Universal CRT（UCRT）

UCRT 是 Windows 操作系统组件，在 Windows 10、Windows Server 2016 及更新版本中始终存在。结合 PyOxidizer 的 Windows 版本要求，只有目标为 Windows 8 / Server 2012 时才需要额外部署 UCRT。PyOxidizer 目前不提供 UCRT 的自动物化能力，需要部署时可参考 Microsoft 官方 UCRT 部署文档。

选择安装器创建方式：Bundle 还是 MSI？

pyoxidizer_distributing_wix.rst 建议按如下方式选择：

• PythonExecutable.to_wix_bundle_builder：产出.exe引导安装器，会内嵌官方VC_Redist*.exe并在安装时执行，适合需要系统级安装 VC++ 运行时的场景；
• PythonExecutable.to_wix_msi_builder：产出.msi，Tugger 会尝试定位本机vcruntimeXXX.dll（需要安装 Visual Studio）并拷贝到安装后的可执行文件旁。注意 MSI 安装器不会物化 VC++ 运行时 DLL 文件（对 MSI 路径，DLL 是以"旁边文件"形式处理的）；
• 如果绕开上述 API 手工构造安装器，则需显式调用WiXMSIBuilder.add_visual_cpp_redistributable或WiXBundleBuilder.add_vc_redistributable添加 VC++ Redistributable——PyOxidizer 的封装方法本质上就是在内部调用这些方法。

无论选择哪种方式，都建议在全新安装的目标系统上实测一遍，以确认所有运行时依赖都已就位。

分发指南文档导航

本主题的完整分发指南目录为 pyoxidizer/docs/pyoxidizer_distributing.rst，包含以下子文档：

• pyoxidizer_distributing_overview.rst：本文对应的概述，讲解构建/打包/分发的领域划分与 Tugger 架构；
• pyoxidizer_distributing_binary_portability.rst：二进制可移植性通用策略与pyoxidizer analyze用法；
• pyoxidizer_distributing_wix.rst：用 WiX Toolset 构建 Windows 安装器；
• pyoxidizer_distributing_linux.rst：Linux 分发考量；
• pyoxidizer_distributing_macos.rst：macOS 分发考量；
• pyoxidizer_distributing_windows.rst：Windows 分发考量。

配套的 Tugger 文档位于 tugger/docs/tugger.rst（项目总览）与 tugger/docs/tugger_overview.rst（设计理念与 crate 架构）。若需要深入定制安装器细节，可继续阅读 Tugger 的 Starlark 类型文档，如WiXMSIBuilder、WiXBundleBuilder、FileManifest等类型的完整 API 参考。

• 开发工具
• CLI