Python 这门语言写起来确实舒服，但一到交付环节，很多人就卡住了——脚本在自己电脑上跑得好好的，发给别人就各种报错，要么是环境不对，要么是依赖没装。把 Python 程序打包成 EXE 或 APK，本质上就是解决“代码怎么脱离开发环境独立运行”这个问题。EXE 面向 Windows 桌面用户，双击就能用；APK 面向 Android 手机，装到设备上就能跑。这两个方向覆盖了绝大多数个人工具、小软件、课程作业和内部脚本的分发需求。不管你是刚学 Python 的新手，还是已经写过几个小项目想分享给朋友用的开发者，打包这一步迟早都要过。我自己在这上面踩过的坑不算少，从 PyInstaller 的各种玄学报错，到 Kivy 打包 APK 时 Gradle 卡死，再到图标替换后程序打不开，基本都经历过一遍。下面就把这些经验完整梳理出来，从原理到实操，从命令到避坑，尽量让看到的人少走弯路。
1. 打包前必须想清楚的几件事
1.1 为什么要打包，而不是直接发源码
很多人第一反应是“我把 .py 文件发过去不就行了”。理论上可以，但实际场景里问题很多。对方需要装 Python 解释器，版本还得对得上；需要手动 pip install 一堆依赖，少一个就报 ImportError；如果代码里用了相对路径读取资源文件，换台电脑路径就失效。更别说有些场景你根本不想让对方看到源码。
打包成 EXE 或 APK 之后，解释器、依赖库、资源文件全部被塞进一个可执行文件或安装包里。对方拿到就能用，不需要任何环境配置。这是最核心的价值。另外从分发角度，一个 EXE 文件比一个文件夹加一堆 .py 文件要专业得多，也更容易通过邮件、网盘等渠道传递。
还有一个容易被忽略的点：打包能帮你做一次“环境冻结”。开发过程中你可能装了很多全局包，但项目实际只用到其中几个。打包工具会分析 import 关系，只把真正用到的模块收进去，这反过来也能帮你检查代码里有没有多余的依赖。
1.2 EXE 和 APK 的本质区别
这两个虽然都是“打包”，但底层机制完全不同，不能混为一谈。
EXE 打包的本质是“捆绑”。PyInstaller 这类工具会把 Python 解释器（pythonXX.dll）、你的脚本编译后的字节码（.pyc）、以及所有依赖库，一起塞进一个可执行文件里。运行时，这个 EXE 会先把内部文件解压到一个临时目录，然后启动一个内嵌的 Python 解释器来执行你的代码。所以 EXE 体积通常比较大，几十 MB 起步，因为解释器本身就占空间。
APK 打包的本质是“交叉编译 + 平台适配”。Android 上跑不了 CPython，需要用 Kivy 配合 Buildozer 或 python-for-android，把 Python 代码和依赖编译成 Android 能识别的原生库和字节码，再打包成 APK。这个过程涉及 NDK 编译、Gradle 构建，链路长得多，出错概率也高得多。
简单说，EXE 是“把 Python 环境搬过去”，APK 是“把 Python 代码翻译成 Android 能懂的形式”。理解这个区别，后面遇到问题时就更容易定位。
1.3 工具选型：PyInstaller、cx_Freeze、Nuitka、Kivy 怎么选
桌面端打包工具不止一个，选错了后面会很痛苦。我把几个主流方案的实际体验列出来：
| 工具 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| PyInstaller | 通用桌面打包 | 上手快，社区大，文档多 | 体积大，杀软误报多 |
| cx_Freeze | 需要精细控制 | 配置灵活，跨平台 | 配置复杂，文档少 |
| Nuitka | 追求性能 | 编译成 C，运行快，体积小 | 编译慢，兼容性偶有问题 |
| auto-py-to-exe | 新手图形化 | 界面操作，不用记命令 | 底层还是 PyInstaller |
我个人的建议是：新手直接用 PyInstaller，遇到体积或误报问题再考虑 Nuitka。auto-py-to-exe 适合完全不想碰命令行的人，但它只是 PyInstaller 的图形壳，遇到复杂问题还是得回到命令行。
APK 这边选择就少很多。Kivy + Buildozer 是目前最成熟的方案，虽然配置麻烦，但社区资料最全。另一个方向是 BeeWare，但成熟度还不如 Kivy。如果你只是想把一个简单脚本搬到手机上，也可以考虑用 Termux 直接跑，但那不算真正的 APK 打包。
注意：不要同时装多个打包工具然后混用，PyInstaller 和 cx_Freeze 的 hook 机制可能冲突，导致打包出来的东西行为异常。选定一个就坚持用。
2. PyInstaller 打包 EXE 核心实操
2.1 环境准备与安装
第一步永远是确认 Python 环境干净。我见过太多人打包失败，最后发现是全局环境里装了几百个包，PyInstaller 分析依赖时被干扰。
推荐做法是给每个项目建独立虚拟环境：
python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate激活后安装项目依赖，再装 PyInstaller：
pip install pyinstaller验证安装：
pyinstaller --version能正常输出版本号就行。这里有个细节：PyInstaller 的版本和 Python 版本有对应关系。Python 3.12 需要 PyInstaller 6.0 以上，Python 3.8 用 5.x 就够。如果版本不匹配，打包时可能报 “module not found” 之类的奇怪错误。
实操心得：在虚拟环境里先
pip freeze > requirements.txt记录依赖，打包出问题时可以对照检查是不是某个包没被正确识别。
2.2 最简打包命令与参数详解
假设你有一个main.py，最基础的打包命令是：
pyinstaller main.py执行后会生成build/和dist/两个目录。dist/main/里面就是打包结果，包含一个main.exe和一堆依赖文件。这种叫“文件夹模式”（onedir），启动快但文件多。
如果想让所有东西塞进一个文件：
pyinstaller -F main.py-F就是--onefile，生成单个 EXE。但要注意，onefile 模式下每次运行都会把内部文件解压到临时目录，启动会慢几秒，而且临时目录在某些安全软件监控下可能被拦截。
常用参数我整理成表：
| 参数 | 含义 | 使用场景 |
|---|---|---|
| -F / --onefile | 打包成单个文件 | 方便分发 |
| -D / --onedir | 打包成文件夹 | 启动快，调试方便 |
| -w / --windowed | 不显示控制台 | GUI 程序 |
| -c / --console | 显示控制台 | 命令行工具 |
| -i / --icon | 指定图标 | 替换默认图标 |
| -n / --name | 指定名称 | 自定义 EXE 名 |
| --add-data | 添加资源文件 | 图片、配置等 |
| --hidden-import | 强制导入模块 | 动态导入的包 |
一个典型的 GUI 程序打包命令：
pyinstaller -F -w -i app.ico -n MyApp --add-data "assets;assets" main.py注意--add-data在 Windows 上用分号分隔，Linux/macOS 上用冒号。这个差异坑过很多人。
2.3 资源文件路径处理（高频踩坑点）
这是 PyInstaller 打包最容易出问题的地方。开发时你用open("assets/logo.png")能正常读取，打包后运行就报 FileNotFoundError。
原因是 onefile 模式下，程序运行时会把资源解压到一个临时目录（sys._MEIPASS），而你的代码还在用相对路径找文件，自然找不到。
正确做法是写一个路径处理函数：
import sys import os def resource_path(relative_path): if hasattr(sys, '_MEIPASS'): return os.path.join(sys._MEIPASS, relative_path) return os.path.join(os.path.abspath("."), relative_path)然后所有资源读取都走这个函数：
icon = resource_path("assets/logo.png")sys._MEIPASS是 PyInstaller 运行时注入的属性，指向临时解压目录。开发环境下没有这个属性，就走正常路径。这样一套代码两边都能跑。
注意：
--add-data的源路径和目标路径要写对。"assets;assets"表示把项目里的 assets 文件夹复制到打包后的 assets 目录。如果写成"assets;."就会把 assets 里的文件散落到根目录，路径就对不上了。
2.4 隐藏导入与动态依赖处理
有些库不是通过常规 import 加载的，比如用importlib.import_module()动态导入，或者通过配置文件指定模块名。PyInstaller 静态分析发现不了这些，打包后运行就报 ModuleNotFoundError。
典型例子：pkg_resources、sqlalchemy 的方言、pandas 的某些可选后端。
解决办法是用--hidden-import显式告诉 PyInstaller：
pyinstaller -F --hidden-import=pkg_resources --hidden-import=sqlalchemy.dialects.sqlite main.py如果隐藏导入很多，可以写一个 hook 文件。在项目目录建hook-mymodule.py，内容：
hiddenimports = ['module_a', 'module_b']然后打包时用--additional-hooks-dir=.指定 hook 目录。
我打包过一个用 paddleocr 的项目，那个依赖链特别深，最后是靠--collect-all paddleocr才搞定。--collect-all会把指定包的所有子模块、数据文件、二进制文件全部收进去，简单粗暴但有效。
2.5 体积优化与杀软误报应对
PyInstaller 打出来的 EXE 动辄 50MB 以上，主要体积来自 Python 解释器和标准库。优化思路有几个：
第一，用虚拟环境打包，避免把全局装的无用包带进去。这是最有效的。
第二，用--exclude-module排除明确不用的模块：
pyinstaller -F --exclude-module tkinter --exclude-module unittest main.py第三，打包后用 UPX 压缩。先下载 UPX，然后：
pyinstaller -F --upx-dir=/path/to/upx main.pyUPX 能把体积压掉 30% 到 50%，但有时会导致程序无法启动，尤其是涉及加密库的时候。建议压缩后一定要完整测试。
杀软误报是另一个头疼问题。PyInstaller 的 bootloader 被很多杀软标记为可疑，因为它的行为（解压到临时目录再执行）和某些恶意软件类似。缓解办法：用--key加密字节码（注意这不能真正防逆向，只是增加误报门槛），或者用 Nuitka 替代。最彻底的办法是给 EXE 做代码签名，但个人开发者成本较高。
实操心得：如果 EXE 发给别人后被 Windows Defender 拦截，让对方在“Windows 安全中心”里添加排除项，或者右键属性里勾选“解除锁定”。这不是你的代码有问题，是 PyInstaller 的通用问题。
3. Kivy 打包 APK 完整流程
3.1 Kivy 环境搭建与项目结构
APK 打包比 EXE 复杂一个量级，因为涉及 Android SDK、NDK、Gradle 一整套工具链。目前最省心的方式是用 Buildozer，但它只支持 Linux 和 macOS。Windows 用户需要装 WSL 或者用虚拟机跑 Ubuntu。
先装 Buildozer：
pip install buildozer还需要装一些系统依赖（Ubuntu 下）：
sudo apt install -y git zip unzip openjdk-17-jdk python3-pip autoconf libtool pkg-config zlib1g-dev libncurses5-dev libncursesw5-dev libtinfo5 cmake libffi-dev libssl-dev一个最小的 Kivy 项目结构：
myapp/ ├── main.py ├── myapp.kv └── buildozer.specmain.py是入口，myapp.kv是界面描述文件，buildozer.spec是打包配置。
3.2 buildozer.spec 关键配置逐项说明
在项目目录执行buildozer init会生成默认的buildozer.spec。这个文件决定了打包的所有行为，几个关键项必须改：
[app] title = MyApp package.name = myapp package.domain = org.example source.dir = . source.include_exts = py,png,jpg,kv,atlas version = 0.1 requirements = python3,kivy orientation = portrait fullscreen = 0 android.permissions = INTERNET android.api = 33 android.minapi = 21 android.archs = arm64-v8a, armeabi-v7a逐项解释：
requirements里列出所有依赖，Kivy 必须写。如果用了 requests、pillow 等，也要加进去。注意这里写的是包名，Buildozer 会自动去 PyPI 下载并交叉编译。
android.api是目标 API 级别，33 对应 Android 13。android.minapi是最低支持版本，21 对应 Android 5.0。设太低兼容性好但可能缺新特性，设太高老设备装不上。
android.archs指定 CPU 架构。arm64-v8a 是现代手机主流，armeabi-v7a 兼容老设备。两个都打会让 APK 体积翻倍，只打 arm64 能省一半空间。
android.permissions按需添加。用网络就加 INTERNET，读存储加 READ_EXTERNAL_STORAGE。权限加多了应用商店审核可能有问题，加少了功能跑不起来。
3.3 打包命令与首次构建注意事项
配置好后执行：
buildozer -v android debug-v是 verbose，输出详细日志，方便排查问题。首次构建会下载 Android SDK、NDK、python-for-android 等一大堆东西，视网络情况可能要半小时到几小时。建议挂个稳定的网络，中途断了重来很痛苦。
构建成功后，APK 在bin/目录下，名字类似myapp-0.1-armeabi-v7a-debug.apk。
首次构建有几个高频卡点：
第一，SDK 下载慢或失败。Buildozer 默认从 Google 官方源下载，国内网络可能超时。可以在buildozer.spec里配置镜像，或者手动下载后放到~/.buildozer/android/platform/对应目录。
第二，NDK 版本不匹配。python-for-android 对 NDK 版本有要求，太新太旧都可能编译失败。如果报编译错误，先检查 NDK 版本。
第三，Gradle 卡在 “Downloading”。这是 Gradle 在下载依赖，同样可能网络问题。可以配置 Gradle 使用本地缓存或镜像。
注意：首次构建成功后，后续构建会快很多，因为 SDK、NDK 都缓存了。不要因为第一次慢就放弃。
3.4 权限、图标与签名配置
默认生成的 APK 用的是 debug 签名，可以安装测试但不能上架应用商店。正式发布需要生成 keystore 并配置签名。
生成 keystore：
keytool -genkey -v -keystore myapp.keystore -alias myapp -keyalg RSA -keysize 2048 -validity 10000然后在buildozer.spec里配置：
android.keystore = myapp.keystore android.keyalias = myapp android.keystore_password = yourpassword android.keyalias_password = yourpassword图标替换：在buildozer.spec里设置icon.filename = %(source.dir)s/icon.png，图标建议 512x512 PNG，Buildozer 会自动生成各尺寸。
权限这块要特别注意 Android 13 之后的变化。READ_EXTERNAL_STORAGE 在 Android 13 上已经废弃，要用 READ_MEDIA_IMAGES 等细分权限。如果应用需要访问相册，得同时声明新旧权限并做运行时判断。
3.5 打包后的测试与分发
APK 打出来后，先传到手机上安装测试。用adb install myapp.apk或者直接拷贝到手机点击安装。
测试重点：启动是否闪退、界面是否适配屏幕、权限请求是否正常、后台切换是否保持状态。Kivy 应用在 Android 上偶尔会有输入法遮挡输入框的问题，需要在 kv 文件里调整布局。
分发渠道：如果是内部使用，直接发 APK 文件即可。如果要上应用商店，需要 release 签名版本，并且满足各商店的审核要求。国内主流应用商店对个人开发者上架有一定门槛，通常需要软著等材料。
实操心得：Kivy 应用在低端 Android 设备上启动可能较慢，因为要初始化 Python 运行时。如果目标用户设备较老，建议在启动时加一个 splash 画面，避免用户以为卡死。
4. 常见问题与排查技巧实录
4.1 EXE 打包高频问题速查
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 运行报 ModuleNotFoundError | 动态导入未被识别 | 加 --hidden-import |
| 找不到资源文件 | 路径未用 _MEIPASS | 改用 resource_path 函数 |
| EXE 体积过大 | 全局环境打包 | 用虚拟环境重新打包 |
| 杀软报毒 | bootloader 特征 | 加排除项或换 Nuitka |
| 启动闪退无提示 | 缺少控制台输出 | 先用 -c 模式打包看报错 |
| 图标不生效 | 图标格式或尺寸问题 | 用 .ico 格式，256x256 |
| 打包后运行慢 | onefile 解压耗时 | 改用 onedir 模式 |
闪退问题特别说一下。GUI 程序用-w打包后没有控制台，出错时什么都看不到。排查方法是先用-c打包一个带控制台的版本，运行看具体报错，定位后再改回-w。
4.2 APK 打包常见报错与解决
Buildozer 的报错信息通常很长，关键信息往往在最后几十行。几个典型错误：
Command failed: ... gradle ...多半是 Gradle 下载或编译问题。检查网络，清理~/.gradle缓存后重试。
NDK not found或编译错误，检查buildozer.spec里的 NDK 版本配置，或者删除~/.buildozer重新下载。
requirements里的某个包编译失败，通常是该包没有 Android 平台的预编译版本，需要手动处理。可以尝试换用纯 Python 实现的替代库。
APK 安装后闪退，用adb logcat看日志，过滤 Python 相关输出。常见原因是权限没声明、资源文件没打包进去、或者用了 Android 不支持的库。
4.3 跨平台打包的坑与经验
Windows 上打包的 EXE 只能在 Windows 跑，macOS 上打包的只能在 macOS 跑，这是 PyInstaller 的限制——它不支持交叉编译。要给不同平台分发，得在对应平台上分别打包。
Linux 上打包的 EXE 在 Windows 上跑不了，反过来也一样。如果项目需要多平台分发，建议用 GitHub Actions 配置多平台构建，每个平台用对应的 runner 打包。
APK 倒是可以在 Linux 上打出来给所有 Android 设备用，因为 Android 是统一的运行环境。但要注意 CPU 架构，arm64 和 x86 的 APK 不通用。
还有一个容易忽略的点：Python 版本。用 Python 3.12 打包的 EXE，在没装 Python 的机器上能跑，但如果目标机器是 Windows 7，可能因为缺少某些系统 DLL 而失败。PyInstaller 6.x 已经不支持 Windows 7，如果需要兼容老系统，得用旧版本 PyInstaller 和 Python 3.8。
5. 进阶技巧与效率提升
5.1 用 spec 文件管理复杂打包配置
当打包参数越来越多时，每次敲命令行很累也容易出错。PyInstaller 首次打包会生成.spec文件，之后可以直接编辑这个文件，然后用：
pyinstaller main.specspec 文件本质是一个 Python 脚本，可以写逻辑。比如根据环境变量决定是否包含调试模块：
import os debug = os.environ.get('DEBUG', '0') == '1' a = Analysis(['main.py'], ...) if debug: a.datas += [('debug_config.json', 'config/debug.json', 'DATA')]这样一套配置能同时管理开发和发布两种打包模式，比维护多个命令清爽得多。
5.2 自动化打包脚本编写
如果项目需要频繁打包，写个脚本能省很多事。一个 Windows 下的批处理示例：
@echo off call venv\Scripts\activate pip install -r requirements.txt pyinstaller -F -w -i app.ico -n MyApp main.py echo Build complete: dist\MyApp.exe pauseLinux/macOS 下用 shell 脚本类似。更进一步可以用 Makefile 或 Python 脚本管理，把清理、打包、测试串起来。
对于 APK，Buildozer 本身命令就一条，但可以在外面包一层脚本处理版本号自增、日志归档等。
5.3 打包产物的版本管理与更新策略
打包产物不建议提交到 Git，体积大且每次构建都变。正确做法是把buildozer.spec、.spec文件、requirements.txt纳入版本管理，产物通过 Release 或网盘分发。
版本号管理：在代码里维护一个__version__，打包时读取并写入 EXE 属性或 APK 的 versionName。这样用户能清楚知道用的是哪个版本。
更新策略：桌面端可以做一个简单的检查更新逻辑，启动时请求版本接口，有新版本提示下载。移动端如果上架了应用商店，走商店更新即可；如果是侧载分发，同样需要自己做更新提示。
实操心得：打包时在 EXE 或 APK 里嵌入构建时间戳，排查问题时能快速确认用户用的是哪个构建。方法是在代码里写一个
BUILD_TIME常量，打包脚本自动替换。
5.4 从脚本到产品的最后一公里
打包只是第一步，真正要让别人用得舒服，还得考虑几件事。
错误处理要完善。打包后的程序出错时用户看不到 traceback，所以关键操作都要 try-except 并给出友好提示，同时把详细错误写到日志文件。
配置文件要外置。不要把用户配置写死在代码里，用%APPDATA%或应用私有目录存配置，这样更新版本时不会覆盖用户设置。
首次启动引导。如果程序需要配置才能用，加一个首次启动向导，比让用户自己摸索强得多。
卸载清理。Windows 上如果程序写了注册表或用户目录文件，最好提供卸载脚本。Android 卸载会自动清理应用私有目录，但外部存储的文件需要自己处理。
这些东西看起来和打包无关，但决定了打包出来的东西是“能跑”还是“好用”。我见过太多项目打包没问题，但用户拿到后不知道怎么用，最后反馈一堆本可以避免的问题。
最后分享一个我常用的检查清单，打包完成后逐项过一遍：在干净机器上测试、检查所有资源文件是否正常加载、确认权限声明完整、验证图标和版本信息、测试异常场景下的表现。这几步做完，基本就能放心分发了。
