Python项目打包精简技巧

本文深入解析了Python项目精简打包的关键陷阱与正确实践，重点揭示了MANIFEST.in常被误用的三大痛点：它仅对sdist生效却常被误用于wheel、include默认不递归导致子目录文件遗漏、以及在pyproject.toml时代必须显式启用include-package-data = true才能激活其作用；文章直击开发者高频错误——盲目依赖setup.py中的find_packages()致使MANIFEST.in完全失效，并给出可落地的解决方案：改用显式packages声明或src布局+find_packages(where="src")配合package_dir解耦结构，辅以recursive-include和global-exclude精准控制文件收录，最后强调通过python setup.py sdist --dry-run实测验证而非凭空猜测，助你彻底告别冗余打包、缺失配置文件或构建失败的困扰。

setup.py里不写find_packages()，否则MANIFEST.in基本失效

很多项目一上来就在setup.py里调用find_packages()，以为这样就能自动包含所有.py文件——但实际打包时，MANIFEST.in的include或recursive-include规则根本不会生效。因为find_packages()会绕过MANIFEST.in，直接扫描目录结构并按包规则收集文件。

正确做法是：显式声明packages列表，或改用setuptools.find_packages(where="src")配合package_dir，让源码路径和包结构解耦，再由MANIFEST.in统一控制哪些文件进sdist。

• 删掉setup.py中类似packages=find_packages()的写法
• 改用packages=["myapp", "myapp.utils"]（手动列明）或find_packages(where="src") + package_dir={"": "src"}
• MANIFEST.in只对sdist（源码分发包）起作用，wheel默认只打包packages里的.py，不读MANIFEST.in

MANIFEST.in里include不递归，recursive-include才是真包含子目录

常见错误是写include myapp/*.py，结果myapp/utils/下的helper.py没被打包进去——因为include只匹配当前层，不进子目录。

真正需要递归包含时，必须用recursive-include，且路径要和项目根目录下看到的一致（即MANIFEST.in所在位置为基准）。

• include myapp/*.py → 只打包myapp/根目录下的.py文件
• recursive-include myapp *.py → 打包myapp/及其所有子目录下的.py文件
• global-exclude __pycache__ *.pyc *.pyo建议加在最前面，避免意外打包缓存文件
• 路径中不要用./前缀，MANIFEST.in不认相对路径符号

测试MANIFEST.in是否生效：用python setup.py sdist --dry-run

光看MANIFEST.in内容没法确认效果，必须实测生成的源码包里有什么。直接运行build可能产生脏文件，--dry-run才是安全验证方式。

它会模拟sdist过程，输出将被包含的全部文件路径，一眼就能看出漏了啥、多了啥。

• 执行python setup.py sdist --dry-run 2>&1 | grep "adding"可过滤出实际加入的文件
• 如果输出里没有你期望的myapp/config.yaml，说明MANIFEST.in里include myapp/config.yaml路径写错了，或文件根本不在该位置
• 注意：这个命令不生成dist/下的tar.gz，只是打印日志，放心跑

pyproject.toml用户别忘了配include-package-data = true

现在新项目多用pyproject.toml，但很多人只写[project]部分，忘了告诉构建后端“请尊重MANIFEST.in”。默认情况下，setuptools在pyproject.toml模式下会忽略MANIFEST.in，除非显式启用。

必须在[project]块里加这一行：

include-package-data = true

否则，哪怕MANIFEST.in写得再准，python -m build出来的sdist里也只会包含packages声明的.py文件，其他一概无视。

这个开关容易被跳过，尤其当从setup.py迁移到pyproject.toml时，旧习惯让人以为MANIFEST.in天然有效。

本篇关于《Python项目打包精简技巧》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！