DEBUG.WIKI
Evoxt;最高 6.0GHz CPU;高频云服务器 · 免费每周备份;查看配置 →
PanstarCloud:部署应用,接入 AI,云服务器与 AI 网关
京东云;让 AI 进入真实业务;零售 · 物流 · 客服 · 硬件;查看方案 →

uv 0.13.0 构建 sdist 报 invalid ustar gname field

uv 0.13.0 新 tar 后端拒绝满长度组名字段,0.13.1 已恢复兼容。核对 CI 真正运行版本,保留原 sdist 验证源码包到 wheel。

同一个源码包,旧环境能构建 wheel,CI 换到 uv 0.13.0 后却在解包阶段失败:

Invalid tar file
invalid ustar gname field: missing NUL terminator

若归档由 Python tarfile 或依赖它的构建工具生成,并且构建用户的组名较长,先检查 tar 头的 gname 字段。0.13.0 默认启用的新 tar 后端会拒绝这里没有 NUL 终止符的字段;32 字节字段被组名占满时,就可能遇到这个边界。

uv 0.13.1 已恢复对这种满长度用户、组名字段的兼容,当前 0.13.5 也包含对应修复。应先选择符合项目约束的修复版,再核对 CI 实际运行的 uv。

报错不一定来自 Python 包元数据

这次失败发生在归档解析阶段,通常还没进入包的构建后端。检查报错指向的压缩包、uv 版本、产物生成方式和归档成员头,不要先去改包名、版本号或 pyproject.toml 的依赖。

组名超过字段长度时,PAX 扩展头可能另存完整值,但基础 ustar 头仍包含一个填满的短字段。因此不同归档可能在不同字节位置失败,不能根据报错 offset 判断是不是同一个 wheel 或某个特定源文件损坏。

只读检查自己构建的原始归档,保留其校验值及生成日志。外部未知压缩包不要为了排查随意解包或执行安装脚本。这个兼容边界也不代表所有 Invalid tar file 都可忽略;真正截断、损坏或格式异常的归档仍要单独处理。

升级的是 CI 中真正运行的 uv

按原工具链更新流程采用至少包含 0.13.1 修复的版本,检查工作流下载入口、容器镜像、工具缓存与 PATH。如果外层升级成功,任务内部仍调用另一个固定的 0.13.0,可见报错不会改变。

暂时不能升级且确认使用 0.13.0 时,可在受影响的单个构建进程启用旧后端。下面是 POSIX shell 的命令形式,dist/demo-0.1.0.tar.gz 必须换成已核对、可信的实际源码包:

UV_LEGACY_TAR_BACKEND=1 uv build --wheel dist/demo-0.1.0.tar.gz

这会执行包的构建过程,只适合项目已有的受控构建环境;Windows 原生 shell 的环境变量设置写法不同。变量只应用于该次命令,不要作为所有后续 uv 版本的永久配置。升级后移除临时选项,再用同一份原归档确认正常。

从源码树直接构建 wheel 是另一个不同入口,会跳过这份 sdist 的读取,不能凭它成功就判定源码包已经修好。若用户实际安装的是 sdist,验收仍必须走源码包到 wheel 的路径。

保留原归档,避免用重打包掩盖问题

不需要为绕过检查,把文件所属组改成特权组或全局修改构建机的用户设置。手工重打包也会改变归档校验值和可追溯性;确有重建需求,应由原发行流程生成,并保留原产物。

复查时使用同一份 sdist,确认修复版 uv 不再拒绝 gname 字段,wheel 中包名、版本和文件清单符合预期,并能按项目原有流程安装使用。保存原工具版本、临时变量与产物记录;回退工具链时也要识别哪些构建任务仍会读到受影响归档,不能只恢复一个二进制文件就丢掉兼容处理。