zipapp 打包前必须清理 pycache__、.pyc 和 IDE 元数据，确保入口文件含 if __name == "__main__":，依赖需提前安装，打包命令为 python -m zipapp . -o app.pyz -m "main:main"，生成的 .pyz 需 Python 3.7+ 运行且不包含第三方包。
zipapp 打包前必须确保项目结构干净
直接用 zipapp 打包失败，十有八九是因为项目里混了 __pycache__、.pyc 文件或 IDE 生成的元数据（比如 .idea/、.vscode/）。Python 3.7+ 的 zipapp 不会自动过滤这些，它们会被原样塞进 zip，导致运行时报 ImportError 或找不到模块。
实操建议：
- 先手动清理：运行
find . -name "__pycache__" -exec rm -r {} +（Linux/macOS）或del /s /q __pycache__（Windows） - 确认入口文件存在且可独立运行：比如
main.py顶层有if __name__ == "__main__":块 - 依赖必须已安装在当前环境——
zipapp不打包第三方包，只打包你项目目录下的 .py 文件
用 python -m zipapp 指定入口并生成可执行 zip
zipapp 本身不处理依赖，它只把你的源码和一个启动 stub 打包进 zip，并设置 zip 的 __main__.py。关键在于 -m 参数指定入口模块，否则生成的 zip 双击或 python xxx.pyz 会报 ValueError: No module named '__main__'。
假设项目根目录下有 main.py，内容含 if __name__ == "__main__": ...：
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
python -m zipapp . -o myapp.pyz -m "main:main"
说明：
-
.表示打包当前目录所有 .py 文件（不含子目录里的非 .py 内容） -
-o myapp.pyz输出文件名，后缀必须是.pyz（Python 识别可执行 zip 的约定） -
-m "main:main"格式为"module:function"，表示运行时调用main.py里的main()函数；若只需执行模块顶层逻辑，写成-m "main"即可
第三方依赖必须提前安装到目标环境
zipapp 不是 pipenv 或 pyinstaller，它不冻结依赖。你打包进去的只是自己的 .py 文件，运行时仍要靠 Python 解释器从 sys.path 找 requests、numpy 这类包。这意味着：
- 目标机器必须装好相同版本的依赖，且能被 Python 找到（通常靠
pip install -r requirements.txt） - 如果想“真正单文件”，得配合
pip install --target把依赖也复制进项目目录，再一起打包——但要注意许可证和二进制扩展（如cryptography的 .so/.dll）可能无法跨平台运行 - 常见翻车点：用了
pkg_resources或importlib.resources读取包内数据文件，而 zipapp 打包后这些 API 在某些 Python 版本下行为异常
运行 pyz 文件时 Python 版本和编码容易出问题
生成的 .pyz 文件本质是 zip，但头部加了 Python 解释器 shebang（Linux/macOS）或启动 stub（Windows）。实际运行时，系统调用的是你本地的 python 命令，不是打包时的环境。
几个硬性限制：
- Python 3.7+ 才原生支持
.pyz，旧版本需显式调用python myapp.pyz，不能直接./myapp.pyz - Windows 上双击无效，必须命令行运行
python myapp.pyz - 如果代码里用了非 UTF-8 编码（比如 GBK 的中文注释），在某些系统 locale 下运行会抛
UnicodeDecodeError，务必统一用 UTF-8 保存所有 .py 文件
最常被忽略的一点：zipapp 打包后的文件，无法用普通 zip 工具直接解压修改再重打包——Python 对 zip 的内部结构（如 __main__.py 位置、文件时间戳）有隐式要求，手动改完大概率报错。真要调试，得重新跑一遍 python -m zipapp。
