5分钟上手PyFuze：从安装到生成第一个跨平台Python可执行文件
项目地址: https://gitcode.com/gh_mirrors/py/pyfuze PyFuze是一款强大的Python项目打包工具，能够在5分钟内将你的Python代码转换为跨平台可执行文件。无论你是Python新手还是经验丰富的开发者，PyFuze都能帮助你轻松创建无需Python环境的独立应用程序。本文将为你提供完整的PyFuze入门指南，从安装到生成第一个可执行文件，让你快速掌握这个实用的打包工具。
📦 PyFuze是什么？
PyFuze是一个基于Cosmopolitan和uv构建的Python项目打包工具，它能够将你的Python项目打包成单个可执行文件。这意味着你可以将Python脚本分发给没有安装Python的用户，或者创建独立的桌面应用程序。
核心功能亮点：
- ✅ 一键打包：简单命令即可生成可执行文件
- ✅ 跨平台支持：支持Windows、Linux、macOS系统
- ✅ 三种打包模式：满足不同场景需求
- ✅ 依赖管理：自动处理Python包依赖
- ✅ 配置灵活：支持多种自定义选项
🚀 快速安装PyFuze
安装PyFuze非常简单，只需一行命令：
pip install pyfuze
或者使用uvx直接运行：
uvx pyfuze -h
安装完成后，你可以通过运行pyfuze --help查看所有可用选项。
🎯 PyFuze的三种打包模式
PyFuze提供三种不同的打包模式，每种模式都有其特点和适用场景：
| 模式 | 离线运行 | 跨平台 | 文件大小 | 兼容性 | 适用场景 |
|---|---|---|---|---|---|
| Bundle模式 (默认) | ✅ | ❌ | 🔴 较大 | 🟢 高 | 需要最高兼容性的场景 |
| Online模式 | ❌ | ✅ | 🟢 小 | 🟢 高 | 需要小体积跨平台分发 |
| Portable模式 | ✅ | ✅ | 🟡 中等 | 🔴 低 | 纯Python项目的便携式分发 |
Bundle模式详解
Bundle模式会将Python解释器和所有依赖项一起打包，生成的可执行文件只能在打包时相同的平台上运行。这是兼容性最高的模式，适合需要稳定运行环境的项目。
Online模式详解
Online模式生成小巧的跨平台包，运行时需要网络连接来下载依赖项。这种模式适合需要频繁更新的应用程序，或者希望保持包体积最小的场景。
Portable模式详解
Portable模式创建完全独立的跨平台可执行文件，无需解压或网络连接。它基于Cosmopolitan的python.com，目前固定使用Python 3.12.3版本。
🛠️ 5分钟创建你的第一个可执行文件
步骤1：准备简单的Python脚本
首先创建一个简单的Python脚本hello.py：
# hello.py
print("你好，PyFuze！")
print("这是我的第一个可执行文件！")
input("按Enter键继续...")
步骤2：使用Portable模式打包
对于简单的脚本，Portable模式是最佳选择：
pyfuze hello.py --mode portable --output-name myapp.com
步骤3：运行生成的可执行文件
打包完成后，你会在dist目录中找到myapp.com文件。直接运行它：
./dist/myapp.com
恭喜！你已成功创建了第一个跨平台Python可执行文件！🎉
📁 处理复杂项目
对于包含多个文件和依赖的复杂项目，PyFuze同样能轻松应对。以项目中的复杂示例为例：
项目结构
complex/
├── app.py # 主入口文件
├── pyproject.toml # 项目配置
├── uv.lock # 依赖锁定文件
├── config.txt # 配置文件
├── unix_part/ # Unix专用模块
└── windows_part/ # Windows专用模块
打包命令示例
pyfuze ./examples/complex \
--entry app.py \
--pyproject ./examples/complex/pyproject.toml \
--uv-lock ./examples/complex/uv.lock \
--include ./examples/complex/config.txt \
--exclude ./examples/complex/build.py \
--unzip-path complex \
--win-gui
🔧 高级配置选项
PyFuze提供了丰富的配置选项，让你可以精确控制打包过程：
常用选项速查表
| 选项 | 描述 | 示例 |
|---|---|---|
--mode | 指定打包模式 | --mode portable |
--output-name | 输出文件名 | --output-name myapp.com |
--entry | 主入口文件 | --entry main.py |
--reqs | 依赖文件 | --reqs requirements.txt |
--include | 包含额外文件 | --include config.ini |
--exclude | 排除文件 | --exclude test.py |
--win-gui | Windows隐藏控制台 | --win-gui |
环境变量配置
对于网络受限的环境，你可以配置镜像源：
pyfuze myproject \
--mode online \
--uv-install-script-windows <镜像URL> \
--env UV_PYTHON_INSTALL_MIRROR=<Python镜像> \
--env UV_DEFAULT_INDEX=<PyPI镜像>
💡 实用技巧与最佳实践
技巧1：处理工作目录
默认工作目录是<unzip-path>/src。如果需要切换到可执行文件所在目录：
import os
os.chdir(os.path.dirname(os.environ["PYFUZE_EXECUTABLE_PATH"]))
技巧2：获取用户调用目录
如果需要获取用户调用可执行文件的目录：
import os
os.chdir(os.environ["PYFUZE_INVOKE_DIR"])
技巧3：选择合适的打包模式
- 简单脚本 → 使用Portable模式
- 复杂桌面应用 → 使用Bundle模式
- 需要网络更新的应用 → 使用Online模式
⚠️ 重要注意事项
- 无代码加密：PyFuze不提供任何代码加密或混淆功能
- 平台限制：Bundle模式只能在打包时相同的平台上运行
- 依赖兼容性：Portable模式仅支持纯Python项目
- 文件大小：Bundle模式生成的文件较大，包含完整Python环境
📚 核心模块路径
- 主程序入口：src/pyfuze/main.py
- 命令行接口：src/pyfuze/cli.py
- 工具函数：src/pyfuze/utils.py
- 示例项目：examples/complex/
🎉 开始你的PyFuze之旅
现在你已经掌握了PyFuze的基本使用方法。无论是简单的脚本还是复杂的项目，PyFuze都能帮助你轻松创建跨平台的可执行文件。记住，实践是最好的学习方式，立即尝试将你的Python项目打包成可执行文件吧！
下一步建议：
- 尝试打包一个你自己的Python项目
- 测试在不同操作系统上的运行效果
- 探索更多高级配置选项
- 查看项目中的示例代码获取灵感
PyFuze让你的Python应用分发变得前所未有的简单！🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
