pyproject.toml 是现代 Python 包构建唯一入口，必须存在且格式正确；需正确定义 [build-system] 和 [project] 段，确保 packages、readme、name 等字段准确，源码结构与导入路径对齐，并在每次 version 变更后清空 dist/ 和 build/ 目录。
pyproject.toml 必须存在且格式正确，否则 build 会静默失败或报错 ModuleNotFoundError: No module named 'setuptools.build_meta'
现代 Python 包发布不再依赖 setup.py，pyproject.toml 是唯一入口。它同时定义构建系统和包元数据，缺一不可。
-
[build-system]段必须显式声明requires和build-backend，哪怕只用setuptools；漏掉build-backend会导致python -m build找不到构建器 -
[project]中的name决定 PyPI 上的包名（如my-utils），但导入时要用下划线（import my_utils），连字符仅用于发布名 -
readme字段必须指向真实存在的文件（如"README.md"），否则build会报FileNotFoundError - 如果源码放在
src/目录下，需在[project]中加packages = ["find:"] 或显式列出packages = ["my_package"]，否则打包后dist/里是空的
打包前必须验证 __init__.py 和导入路径
打包工具不检查模块能否实际导入，但用户安装后第一次 import 就会失败。常见问题不是配置错，而是结构没对齐。
- 确保
src/my_package/__init__.py存在且非空（哪怕只写__version__ = "0.1.0"） - 在项目根目录运行
python -c "import my_package"，应成功；失败说明src/没被 Python 路径识别，此时要配pyproject.toml的packages或改用find: - 不要把测试文件、示例脚本、Jupyter notebook 放进
src/目录——它们会被打包进去，且可能因缺失依赖导致安装失败
twine upload 失败的三个高频原因
上传卡在 403 或 401 不代表账号错，大概率是凭证或包名冲突问题。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
testpypi测试时，命令必须带--repository testpypi，且~/.pypirc或环境变量中不能混用正式 PyPI 的 token - 如果提示
HTTPError: 400 Client Error: This filename has already been used，说明同名同版本的.whl或.tar.gz已存在——PyPI 不允许覆盖，必须改version后重新build - 上传前未清空
dist/目录，导致旧包和新包一起传，而旧包已失效（如删了__init__.py又重建），PyPI 拒绝部分文件
MicroPython-lib 与标准 PyPI 包的关键区别
如果你的目标是 MicroPython 设备（如 ESP32），别直接套用标准流程——manifest.py 不是 pyproject.toml 的替代品，它是独立构建体系。
立即学习“Python免费学习笔记（深入）”；
-
manifest.py只用于mpy-cross编译和生成.mpy文件，不能上传到 PyPI；PyPI 只接受标准.whl或.tar.gz - 想让 MicroPython 用户用
pip install安装，你得额外提供一个兼容 CPython 的纯 Python 版本，并在pyproject.toml中通过classifiers标明"Programming Language :: Python :: 3"，否则会被过滤 -
metadata(pypi_publish=True)是 MicroPython 工具链的开关，不影响 PyPI 行为；真正决定能否上 PyPI 的，只有pyproject.toml和twine的操作
最容易被忽略的点：每次改 version 后，必须手动删掉 dist/ 和 build/ 目录再 build，否则旧二进制残留会导致上传失败或用户安装到错误版本。
