在使用 uv 时,我遇到一个典型的“提示文案 vs 配置格式”不一致问题:错误提示里会显示 30s,于是用户很自然会尝试 UV_HTTP_TIMEOUT=120s,但实际上 uv 期望的是纯整数秒。这个问题被整理在 issue #16940。
我提交了 PR #17868,让 uv 对这些超时相关环境变量接受可选的 s 后缀(仍然只表示秒,不引入 m/h 等单位)。
🔍 分析 (Analyze)
这是一个“很小但很烦”的 DX 问题:
- 提示里出现
30s,会让人误以为环境变量格式也支持s。 - 用户一旦写了
120s,就会立刻得到“解析失败”的报错,体验割裂。
维护者的讨论方向也很明确:要么在解析阶段更友好地处理 s,要么给出更明确的错误信息;但不需要支持复杂的多单位解析。
📍 定位 (Locate)
超时环境变量的解析集中在 crates/uv-settings/src/lib.rs:
UV_HTTP_TIMEOUT/UV_REQUEST_TIMEOUT/HTTP_TIMEOUTUV_UPLOAD_HTTP_TIMEOUT
原先这些值都通过统一的“整数环境变量解析”逻辑读取。
🛠️ 执行 (Execute)
我做了两件事:
- 解析层兼容:在整数解析失败时,额外尝试去掉末尾
s(仅小写),再按整数解析一次。 - 单元测试:在
uv-settings增加了最小覆盖测试,确保"30"与"30s"都能被解析为相同的秒数。
✅ 总结 (Summary)
这次贡献的目标很单纯:把“用户自然会写的配置”变成“uv 可以接受的配置”,避免因提示展示 30s 而造成的误用。