twine upload是pypi官方唯一推荐的上传方式，因python setup.py upload已被弃用且不安全：它使用http明文传输凭据、无法校验包内容，2026年起pypi彻底拒绝该协议；twine必须配合预构建分发包（.whl或.tar.gz），因其本身不构建只上传，跳过构建会报错“no such file or directory: 'dist/'”；构建后须运行twine check验证long_description渲染，否则readme格式错误将导致pypi页面崩溃且不可修改；认证应使用api token配合.pypirc文件或环境变量，严禁明文传参；上传testpypi需显式指定-r testpypi且token与pypi不通用；--skip-existing仅按文件名而非逻辑版本跳过，wheel标签变更会导致409冲突。
twine upload 是唯一推荐的上传方式，直接用 python setup.py upload 已被弃用且不安全——它走 HTTP、明文传凭据、无法校验包内容，2026 年起 PyPI 官方已彻底拒绝该协议。
为什么 twine upload 必须配合预构建分发包？
Twine 本身不构建包，只上传。如果你跳过构建步骤直接运行 twine upload dist/*，会报错 No such file or directory: 'dist/'。
必须先生成合法的分发文件（.whl 或 .tar.gz），否则 Twine 拒绝操作。
常见构建命令：
- python -m build（推荐，现代标准，自动处理 pyproject.toml）
- python setup.py sdist bdist_wheel（兼容旧项目，但需确保 setup.py 正确）
构建后检查：ls dist/ 应至少看到一个 .whl 和/或一个 .tar.gz 文件。
twine check 不是可选项，是上线前必跑的验证
这个命令专门检查 long_description（通常是 README）能否在 PyPI 页面正确渲染。格式错误（比如 Markdown 中混用 reStructuredText 语法、缺少空行、非法字符）会导致整个包页面崩溃，且上传后无法修改描述。
运行：twine check dist/*
若提示 Failed，别急着上传——它不会告诉你哪一行错，只报整体失败。常见原因：
- README 被设为 text/markdown，但用了 .. code:: python 这类 rst 语法
- README 里有未转义的 _ 或 * 在非代码块中
- 使用了 PyPI 不支持的扩展（如 GitHub Flavored Markdown 的表格对齐符）
加 --strict 参数能触发更严苛的校验：twine check --strict dist/*认证凭据怎么放才既安全又省事？
明文写在命令里（twine upload -u myuser -p mypass dist/*）绝对不行——密码会留在 shell 历史、进程列表、CI 日志里。
靠谱做法只有两种：
- 用 API token + .pypirc 文件（本地开发）：
[pypi] 下设 username = __token__，password = pypi-AbcDef123456...（从 https://pypi.org/manage/account/token/ 创建）
- 用环境变量（CI/CD 场景）：
TWINE_USERNAME=__token__TWINE_PASSWORD=pypi-AbcDef123456...
注意：__token__ 是固定字符串，不是占位符；密码字段必须是完整 token 值，不能带空格或换行。
上传到 PyPI 和 TestPyPI 的关键区别
TestPyPI（https://test.pypi.org/legacy/）是沙盒环境，所有包名可重用、不索引、不被 pip 默认安装。
上传命令必须显式指定仓库：
- twine upload -r testpypi dist/*（前提是 .pypirc 里定义了 [testpypi]）
- 或直接给 URL：twine upload --repository-url https://test.pypi.org/legacy/ dist/*
PyPI 生产环境默认就是 -r pypi，所以 twine upload dist/* 等价于 twine upload -r pypi dist/*。
⚠️ 重要：TestPyPI 和 PyPI 的 token **不通用**，必须分别创建；.pypirc 里两个 section 的 password 字段要填各自对应的 token。
真正容易被忽略的是：PyPI 对包名+版本号组合做全局唯一校验，但 --skip-existing 只对完全相同的文件名生效（比如 mylib-1.0.0-py3-none-any.whl），不是按逻辑版本跳过。如果改了 wheel 的构建参数（比如 Python tag、ABI tag），哪怕版本号一样，也会被当作新文件上传——而 PyPI 不允许同名文件重复上传，此时会报错 409 Conflict，必须删掉旧文件或改名。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
