1. 为什么需要打包Python项目当你写了一个实用的Python工具或库想让其他人也能方便地使用时最直接的方式就是把它发布到PyPIPython Package Index上。PyPI是Python官方的包托管平台全球开发者都可以通过pip install 你的包名来安装你的作品。想象一下这个场景你写了一个自动整理电脑桌面文件的脚本同事看到后也想用。如果直接发.py文件给对方他需要手动下载依赖、处理路径问题。但如果你把代码打包上传到PyPI对方只需要一行命令就能安装使用——这才是真正的程序员友好。2. 项目结构规划一个标准的Python包目录结构应该像这样your_package/ ├── pyproject.toml # 构建配置文件核心 ├── src/ # 源码目录 │ └── your_package/ # 你的包名 │ ├── __init__.py │ └── module.py ├── tests/ # 测试代码 ├── LICENSE # 开源许可证 └── README.md # 项目说明这里有个新手常踩的坑很多人喜欢把代码直接放在项目根目录但这会导致后续打包和导入出现问题。正确的做法是使用src布局所有代码放在src/包名下。我刚开始时就犯过这个错误调试了半天导入失败的问题。3. 编写核心配置文件pyproject.toml是现代Python打包的核心配置文件它取代了旧的setup.py。下面是一个完整的配置示例[build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name example_package_你的用户名 # 必须是唯一的 version 0.1.0 authors [ {name 你的名字, email 你的邮箱}, ] description 一个简短的描述 readme README.md requires-python 3.8 classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, ] [project.urls] Homepage https://github.com/yourname/yourpackage几个关键点说明name必须全局唯一建议加上你的用户名version遵循语义化版本规范MAJOR.MINOR.PATCHclassifiers是PyPI的分类标签完整的列表可以在PyPI官网找到4. 处理依赖和许可证4.1 依赖管理如果你的包依赖其他库在pyproject.toml中添加dependencies [ requests2.25.0, numpy2.0.0, # 可以指定版本范围 ]建议使用宽松的版本范围如2.25.0而不是2.25.0避免与其他包的依赖冲突。4.2 选择开源许可证常见的许可证有MIT最宽松允许任意使用Apache 2.0包含专利授权条款GPL要求衍生作品也必须开源创建LICENSE文件复制你选择的许可证文本。MIT许可证示例Copyright (c) 2023 你的名字 Permission is hereby granted... [此处省略完整许可证文本]5. 构建包5.1 安装构建工具pip install --upgrade build5.2 执行构建在项目根目录运行python -m build这会生成dist目录包含两个文件.tar.gz源码分发版.whl构建好的wheel文件第一次构建时我遇到了ERROR: Unknown distribution option: long_description_content_type错误后来发现是因为pyproject.toml格式不对。建议复制上面的模板避免这类问题。6. 上传到PyPI6.1 注册PyPI账号访问 pypi.org 注册账号在账号设置中创建API Token作用域选整个账户6.2 安装上传工具pip install --upgrade twine6.3 创建配置文件在用户目录下创建.pypircWindows在C:\Users\你的用户名\[pypi] username __token__ password pypi-你的API令牌6.4 上传包twine upload dist/*上传成功后你会看到类似这样的输出Uploading example_package-0.1.0-py3-none-any.whl 100%|█████████████████████| 5.25k/5.25k [00:0100:00, 3.05kB/s]7. 验证和版本更新7.1 安装测试pip install example-package-你的用户名7.2 版本更新流程修改代码后更新pyproject.toml中的version重新构建python -m build上传新版本twine upload dist/*记住永远不要重复上传同一个版本号的文件PyPI不允许覆盖已发布的版本。如果上传出错必须增加版本号重新发布。8. 高级技巧和常见问题8.1 包含非Python文件如果需要打包数据文件如CSV、图片等创建MANIFEST.in文件include src/your_package/data/*.csv8.2 测试PyPI正式发布前可以先用测试平台验证twine upload --repository testpypi dist/*测试PyPI地址https://test.pypi.org8.3 常见错误解决403 Forbidden检查API Token是否正确400 File already exists增加版本号重新构建导入错误确保__init__.py文件存在我第一次上传时因为网络问题失败了三次后来发现用国内镜像源可能会出现问题建议直接连接PyPI主站。