uv sync 是基于 uv.lock 文件重建完全一致依赖环境的命令，确保跨平台依赖精确复现；支持 --dev、--extra、--frozen、--python 等参数实现开发依赖同步、冻结校验和多版本管理。

当你在 Python 项目中反复遇到“本地能跑、CI 失败、服务器报错”这类问题，根本原因往往是依赖版本不一致——uv sync 就是专为终结这种混乱而生的命令，它直接依据锁文件重建完全一致的依赖环境，跳过手动 pip install 和版本猜解。

理解 uv sync 的核心作用

uv sync 不是简单地安装包，它是以 uv.lock 文件为唯一权威来源，强制将当前环境拉回到该文件所记录的精确依赖状态。只要锁文件存在且未被篡改，无论在哪台机器上运行 uv sync，最终安装的每个包名、版本号、甚至二进制分发包的哈希值都完全相同。

这一步操作起来很简单，直接在项目根目录执行即可，但它的前提是：你必须已有 pyproject.toml 或 uv.lock 文件。没有锁文件时，uv sync 会自动触发解析并生成 uv.lock，但这属于隐式行为，不可控；生产环境务必确保先有稳定锁文件再执行 sync。

基础同步：从零开始构建可复现环境

第一步：确认项目根目录下存在 pyproject.toml（现代 Python 项目的标准配置文件）。

第二步：执行同步命令：uv sync。

第三步：uv 自动检测是否存在 uv.lock。若不存在，它会基于 pyproject.toml 中的 [project.dependencies] 解析出完整依赖树，并生成新的 uv.lock；若已存在，则严格按该锁文件安装所有包，跳过任何版本协商过程。

这一步完成后，当前目录下的 .venv 虚拟环境（如未指定其他路径）即完成初始化，所有依赖已就位，且与锁文件逐字节一致。

包含开发依赖的同步

方法一：添加 --dev 参数
执行 uv sync --dev，uv 会同时读取 pyproject.toml 中 [project.optional-dependencies] 下的 dev 分组（或 [tool.uv.dev-dependencies]），并将其中定义的包一并安装。

方法二：显式指定 extras
如果项目定义了 extras（如 [project.optional-dependencies] 中的 "test" 或 "docs"），可用 uv sync --extra test --extra docs 精确控制安装范围。

注意：--dev 和 --extra 不会相互覆盖，可同时使用；但 --dev 默认不包含 extras，需额外声明。

锁定环境：禁止任何版本漂移

① 运行 uv sync --frozen。
② uv 将跳过所有锁文件校验逻辑，直接拒绝生成或更新 uv.lock。
③ 如果当前 uv.lock 与 pyproject.toml 中声明的依赖不兼容（例如删掉了某个依赖但 lock 文件里还记着），命令立即失败并报错，不会尝试修复或降级。

这个模式专用于 CI/CD 流水线或生产部署脚本——它把“环境一致性”变成一个硬性门禁，任何未经批准的依赖变更都会在 sync 阶段被拦截，而不是悄悄引入新版本导致线上异常。

指定 Python 版本与 extras 一次性同步

执行 uv sync --python 3.10 --all-extras。
uv 会先检查系统是否已安装 Python 3.10；若未安装，自动下载并配置；随后解析 pyproject.toml 中所有 [project.optional-dependencies] 下的分组，并全部安装。
该命令等效于手动指定 --extra 逐个列出所有 extras，但更简洁，适合需要完整功能集的开发环境初始化。

【重要前提】：pyproject.toml 中必须正确定义 optional-dependencies，否则 --all-extras 不生效。