PyOxidizer:将 Python 应用打包成单一可执行文件的神器

三、PyOxidizer 基本使用

使用 PyOxidizer 打包应用的基本流程如下：

1. 创建新项目

首先，我们使用 pyoxidizer init 命令创建一个新的 PyOxidizer 项目：

pyoxidizer init myapp

这会创建一个名为 myapp 的目录，其中包含 PyOxidizer 所需的配置文件和基本项目结构。

2. 了解配置文件

项目中最重要的文件是 pyoxidizer.bzl，这是一个使用 Starlark 语言（类似 Python）编写的配置文件。这个文件定义了如何打包你的 Python 应用。

让我们看一个简单的配置示例：

def make_dist():
    return default_python_distribution()

def make_exe(dist):
    policy = dist.make_python_packaging_policy()
    policy.resources_location = "in-memory"

    python_config = dist.make_python_interpreter_config()
    python_config.run_module = "myapp"

    exe = dist.to_python_executable(
        name="myapp",
        packaging_policy=policy,
        config=python_config,
    )

    # 添加我们的Python包
    exe.add_python_package("myapp")

    return exe

def make_embedded_resources(exe):
    return exe.to_embedded_resources()

def make_install(exe):
    files = FileManifest()
    files.add_python_resource(".", exe)
    return files

register_target("exe", make_exe)
register_target("resources", make_embedded_resources, depends=["exe"], default=True)
register_target("install", make_install, depends=["exe"], default=True)

resolve_targets()

3. 添加你的 Python 代码

在项目目录中创建你的 Python 代码。例如，我们可以创建一个简单的 myapp 包：

myapp/
  __init__.py
  main.py

在 main.py 中写入：

def main():
    print("Hello from PyOxidizer!")

if __name__ == "__main__":
    main()

然后在 __init__.py 中添加：

from .main import main

if __name__ == "__main__":
    main()

4. 构建可执行文件

现在，我们可以使用 PyOxidizer 构建可执行文件：

cd myapp
pyoxidizer build

成功构建后，可执行文件通常位于 build/ 目录下。

四、进阶配置

PyOxidizer 提供了丰富的配置选项，让我们来看一些常用的进阶配置：

1. 打包第三方依赖

如果你的应用依赖第三方库，只需在配置文件中添加：

# 添加特定的包
exe.add_python_package("requests")
exe.add_python_package("numpy")

# 或者从requirements.txt添加
exe.add_python_requirements(Path("requirements.txt"))

2. 设置入口点

你可以设置应用的入口点，有多种方式：

# 运行模块
python_config.run_module = "myapp"

# 运行特定脚本
python_config.run_filename = "myapp/main.py"

# 运行Python代码
python_config.run_command = "from myapp import main; main()"

3. 资源处理

你可以控制 Python 资源的存储位置：

# 资源加载到内存中（启动快，内存占用大）
policy.resources_location = "in-memory"

# 资源保存在文件系统中（启动稍慢，内存占用小）
policy.resources_location = "filesystem-relative:lib"

注意事项：内存模式启动更快，但会占用更多内存；文件系统模式启动略慢，但内存占用较少。

五、实战示例：打包一个简单的 Web 应用

让我们看一个实际的例子，将一个使用 Flask 的简单 Web 应用打包：

1.首先创建项目结构：

webapp/
  __init__.py
  app.py
  static/
    style.css
  templates/
    index.html

2.编写 Flask 应用代码 (app.py)：

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/')
def index():
    return render_template('index.html')

def main():
    app.run(host='0.0.0.0', port=8000)

if __name__ == '__main__':
    main()

3.创建 PyOxidizer 项目并配置：

pyoxidizer init flask-webapp
cd flask-webapp

4.修改 
pyoxidizer.bzl 文件：

def make_dist():
    return default_python_distribution()

def make_exe(dist):
    policy = dist.make_python_packaging_policy()
    policy.resources_location = "in-memory"

    python_config = dist.make_python_interpreter_config()
    python_config.run_module = "webapp"

    exe = dist.to_python_executable(
        name="webapp",
        packaging_policy=policy,
        config=python_config,
    )

    # 添加我们的应用和依赖
    exe.add_python_package("webapp")
    exe.add_python_package("flask")

    # 处理静态文件
    exe.add_python_resources(exe.pip_install(["--no-binary", ":all:", "flask"]))

    return exe

# 其他函数保持不变...

5.构建应用：

pyoxidizer build

小贴士：对于包含静态文件的 Web 应用，有时需要特别关注资源的打包方式，确保静态文件和模板能够被正确加载。

六、常见问题与解决方案

1. 打包大小问题

PyOxidizer 生成的可执行文件可能比较大，因为它包含了 Python 解释器。如果想减小体积，可以：

# 在配置中排除不需要的模块
policy.include_distribution_resources = False
policy.include_test = False

2. 平台兼容性

通常需要在目标平台上构建可执行文件，或使用交叉编译：

# 指定目标平台
build_target = 'x86_64-pc-windows-msvc'

3. 调试问题

如果打包的应用出现问题，可以启用调试：

# 启用调试输出
python_config.debug_build = True

七、总结与展望

PyOxidizer 是一个强大的 Python 打包工具，它解决了 Python 应用分发的许多痛点。通过将 Python 解释器和应用代码打包成单一可执行文件，不仅简化了分发过程，还提高了启动性能。

虽然 PyOxidizer 相对较新，但它代表了 Python 打包领域的一个重要进步。随着工具的发展，相信它会变得更加强大和易用。

对于有打包需求的 Python 开发者来说，PyOxidizer 绝对值得一试！