发布Python模块到PyPI需正确配置setup.py或pyproject.toml，用python -m build构建wheel，本地验证后通过twine upload上传；版本号必须递增，不可覆盖。

想把 Python 模块打包发布到 PyPI，让别人用 pip install 就能装？关键不在写代码，而在写对 setup.py（或现代替代方案），再正确构建 wheel 并上传。跳过这步，再好的库也走不出本地目录。

setup.py 不是可有可无的配置文件

它定义了包名、版本、依赖、入口点、数据文件等核心元信息，pip 安装时全靠它解析。哪怕只有一行 print("hello") 的脚本，想被 pip 识别为可安装包，也必须有合法的 setup.py。

• 必须调用 setuptools.setup()，不能只写变量
• name 要全局唯一（PyPI 上已存在会上传失败），建议加前缀如 myorg-mypkg
• packages 别手动列目录，用 find_packages() 自动发现（需先 from setuptools import find_packages）
• install_requires 写运行时依赖，格式如 ["requests>=2.25.0", "click"]；开发依赖放 extras_require 里
• 如果含非 Python 文件（如 config.json、templates/），用 package_data 或 MANIFEST.in 显式声明，否则不会打进 wheel

用 python -m build 替代老旧的 python setup.py sdist bdist_wheel

官方已弃用直接调用 setup.py 构建命令。推荐用 build 工具——轻量、标准、兼容 PEP 517。

• 先装： pip install build
• 在项目根目录执行：python -m build，自动构建 source distribution（.tar.gz）和 wheel（.whl）
• 生成物在 dist/ 目录下，wheel 文件名含平台标记（如 mylib-0.1.0-py3-none-any.whl 表示纯 Python、兼容所有 Python 3 版本）
• 构建前确保 pyproject.toml 存在（哪怕只有最基本的构建后端声明），否则 build 可能回退到旧逻辑

上传前：测试 wheel 是否真正可用

别急着上传 PyPI。本地验证能避免“上传成功但用户装不上”的尴尬。

• 新建虚拟环境：python -m venv testenv && source testenv/bin/activate（Windows 用 testenv\Scripts\activate）
• 用本地 wheel 安装：pip install dist/mylib-0.1.0-py3-none-any.whl
• 进 Python，尝试 import mylib，并运行关键函数或 CLI 入口点
• 检查 pip show mylib 输出：版本、依赖、Location 是否符合预期
• 若报 ModuleNotFoundError，大概率是 packages 或 package_data 漏配；若 CLI 命令找不到，检查 entry_points 中的 console_scripts 键值是否拼写正确

上传到 PyPI：twine 是唯一推荐方式

不用 setup.py upload（已移除），也不用网页手动上传。twine 安全、稳定、支持两次上传校验。

• 安装：pip install twine
• 注册 PyPI 账号（https://www./link/1f6325d1b1080e812e7b713ae61f4ebc），获取 API token（Settings → API tokens → Create new token）
• 上传：twine upload dist/*，提示输入用户名时填 __token__，密码粘贴 token 字符串
• 上传成功后，访问 https://pypi.org/project/your-package-name/ 即可查看页面，他人就能 pip install your-package-name 了
• 后续更新只需改 setup.py 中的 version，重新 build 和 upload —— PyPI 不允许覆盖同版本，所以版本号必须递增

不复杂但容易忽略：一个干净的 setup.py 或 pyproject.toml，一次本地 wheel 验证，一次 twine 上传，你的模块就真正“发布”了。