《Windows 下 uv add 失败？我用“pip 安装 + 手动锁定”3 分钟救火成功》

在 Windows 上绕过 uv 构建失败安装 esdk-obs-python

背景

在 Windows 环境里执行 uv add esdk-obs-python 时，我遇到了经典报错：

Call to setuptools.build_meta:__legacy__.get_requires_for_build_wheel failed:
expected value at line 1 column 1

同时还会看到警告：

Warning: 'keywords' should be a list, got type 'tuple'

这通常不是项目代码问题，而是目标包的老旧构建元数据和 uv 构建流程兼容性问题。

我的可落地处理方案

核心思路是：安装阶段走 pip，声明阶段走 uv。

1. 先给当前项目环境补齐 pip
2. 再在项目虚拟环境里直接安装目标包
3. 用 uv pip list 确认版本
4. 手动写入 pyproject.toml
5. 最后 uv lock --frozen 固定当前状态

实操步骤

1. 安装 pip 到 uv 环境

uv add pip

2. 在虚拟环境中安装目标包

.venv/Scripts/pip3 install esdk-obs-python

3. 确认已安装版本

uv pip list

示例结果：

esdk-obs-python 3.26.2

4. 在 pyproject.toml 中添加依赖

在 dependencies 里添加并建议固定版本：

"esdk-obs-python==3.26.2"

5. 冻结 lock 文件

uv lock --frozen

为什么这样有效

• uv add 触发的是包解析 + 构建流程，容易踩到老包 setup.py 兼容问题
• .venv/Scripts/pip3 install 可以直接把包安装进当前虚拟环境
• 手动写入 pyproject.toml 后，再用 uv lock --frozen 固定状态，就能保持项目依赖可追踪

注意事项

1. dependencies 中不要重复写同一个包，否则后续维护容易混乱。
2. 建议写精确版本（==），避免后续在其他机器拉到新版本又触发构建问题。
3. uv lock --frozen 只做冻结和有效性检查，不会帮你自动升级依赖。

一键复用命令清单

uv add pip
.venv/Scripts/pip3 install esdk-obs-python
uv pip list
uv lock --frozen

总结

当 uv add esdk-obs-python 在 Windows 上失败时，这套流程本质是在做一件事：

把“安装成功”与“依赖声明可维护”拆成两个步骤处理。

这样既能先跑起来，也能把依赖记录回项目配置，适合需要快速恢复开发节奏的场景。