uv publish 发布需三步：先确保 pyproject.toml 含 name、version、description、readme、requires-python、license 字段；再配置 UV_PYPI_TOKEN 环境变量；最后 uv build 后执行 uv publish --timeout 600 dist/*。
直接用 uv publish 就能发，但必须提前配好 pyproject.toml、索引源和 API 令牌——漏掉任一环节都会卡在认证或上传失败。
pyproject.toml 必须包含哪些字段
uv 不读 setup.py，只认 pyproject.toml 中的 [project] 段。缺字段会导致 uv publish 报错或上传后元信息为空。
-
name：PyPI 上唯一标识，不能含下划线（_），建议全小写加短横线（my-cli-tool） -
version：语义化版本，如"0.1.0"，带引号（toml 要求） -
description：简短一句话描述，必填 -
readme：指向README.md或字符串内容，否则 PyPI 页面无介绍 -
requires-python：如">=3.9"，不写可能被旧版 pip 拒绝安装 -
license：推荐用 SPDX ID，如{text = "MIT"}
发布前必须配置 PyPI 认证方式
uv 默认不存密码，必须显式提供凭据。用 API token 是唯一安全做法，明文账号密码已被 PyPI 禁用。
- 去 https://www.php.cn/link/0e1ceaca3e404ed57c3d9d6eaa2928a3 创建 token（scope 选
Entire account或限制到具体项目） - 把 token 存进环境变量：
export UV_PYPI_TOKEN=__token__<your-token-here></your-token-here> - Windows 用户用
$env:UV_PYPI_TOKEN="__token__<your-token-here>"</your-token-here>（PowerShell） - 不要写进
pyproject.toml或 git 提交——token 泄露等于包被劫持
构建命令与发布命令要分开执行
uv publish 不会自动构建，它只上传已存在的 .tar.gz 和 .whl 文件。先构建再发布，顺序错了就报 No such file or directory: 'dist/*.whl'。
立即学习“Python免费学习笔记（深入）”；
- 构建命令：
uv build（生成dist/my_pkg-0.1.0-py3-none-any.whl和.tar.gz） - 检查构建结果：
ls dist/确认两个文件都存在 - 发布命令：
uv publish dist/*（注意通配符*，不是dist/目录名） - 若只想发到 TestPyPI 测试：
uv publish --index testpypi dist/*，前提是pyproject.toml里已配好[[tool.uv.index]]段
国内网络环境下容易卡在上传阶段
PyPI 官方上传接口对国内 IP 响应慢，且 uv 默认不走镜像源上传——上传阶段不支持换源，只能靠调参绕过超时。
- 加
--timeout 600（单位秒），避免默认 30 秒超时中断：uv publish --timeout 600 dist/* - 如果反复失败，先用
twine upload --repository testpypi dist/*验证 token 和网络是否正常（twine对超时更宽容） - 确认没开代理软件全局模式——某些代理会干扰
uv的 HTTP/2 连接
真正容易被忽略的是 uv.lock 文件的存在与否：它不影响发布，但如果你用 uv sync 开发，又没提交 uv.lock，协作同事拉代码后 uv build 可能解析出不同依赖树，导致本地可运行、PyPI 安装后报 ModuleNotFoundError。
