uv是Astral公司用Rust编写的Python包与环境管理工具，旨在统一替代pip、venv、poetry等工具链，具备极速安装、自动虚拟环境管理、依赖锁定（uv.lock）、Python版本自动安装与校验（uv python pin）等核心能力，强调团队强制统一使用以保障CI和本地环境一致性。
团队里只要有一人用 uv 而其他人还在用 pip 或 poetry，项目就大概率在 CI、新成员本地启动、甚至 git pull 后首次安装时出问题。统一不是“推荐用”，而是必须让 uv 成为唯一被允许的 Python 环境与依赖管理入口。
为什么 uv python pin 比 .python-version 手动写更可靠
很多团队把 .python-version 文件直接提交进 Git，但这个文件本身不带校验——它只是个字符串，没人保证里面写的 3.11.6 真的被安装了，也没法触发自动下载。而 uv python pin 3.11.6 做三件事：生成 .python-version、检查本地是否已装该版本、没装就自动 uv python install 3.11.6。CI 和新成员执行 uv sync 前，uv 会先读这个文件并确保 Python 可用。
- 必须禁用
pyenv或其他 Python 版本管理器共存，否则uv python list看不到它们管理的版本，pin会失败 - 团队应约定只使用 CPython 官方构建（不混用 PyPy），因为
uv python install pypy3.10虽然支持，但多数 CI 镜像和团队文档未覆盖其行为差异 -
.python-version文件必须提交进 Git，且不能加到.gitignore—— 它是环境声明的一部分，不是临时配置
uv lock 和 uv sync 必须替代所有 pip install -r requirements.txt
旧项目迁移到 uv 时，最容易踩的坑是“一半 uv 一半 pip”：比如用 uv lock 生成 uv.lock，但 CI 里仍跑 pip install -r requirements.txt。这会导致锁文件形同虚设，pip 会忽略 uv.lock 并重新解析依赖树，结果和本地不一致。
Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具，支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64，解压后可使用 uv 命令。
- CI 脚本中所有
pip install必须替换成uv sync（无参数即默认同步pyproject.toml+uv.lock） - 如果项目还保留
requirements.txt（例如供非 Python 服务调用），用uv export -o requirements.txt生成，而不是手写或靠pip freeze -
uv.lock必须提交进 Git；它不是构建产物，而是可复现性的契约——删掉它等于放弃环境一致性保障
如何让新成员第一次 git clone 就成功运行
新人克隆仓库后执行 uv sync 失败，90% 是因为没配国内镜像或没装对应 Python。这不是操作问题，是规范没前置落地。
- 团队必须提供一份
SETUP.md（不是 README），开头就写明：export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"，并说明该行要加进 shell 配置文件 - 在项目根目录放一个最小
pyproject.toml，哪怕只有[build-system]，也比空着强——uv对空目录的行为未定义，可能报错退出 - 禁止在
Makefile或scripts/里写python -m venv或virtualenv，所有环境创建必须走uv venv，确保缓存复用和路径统一
最难落地的其实是“谁来 enforce”。uv 本身不提供钩子，但你可以用 pre-commit 检查 .python-version 是否存在、uv.lock 是否更新、requirements.txt 是否由 uv export 生成——这些规则一旦写进 .pre-commit-config.yaml，就不再依赖人的自觉。
