本文详解如何配置 uv，使其在执行 uv sync 时主动更新 Git 仓库类依赖（如 git+https://...），解决因远程仓库提交变更后本地依赖未同步导致的代码陈旧问题。核心方案是结合 --upgrade 标志触发锁文件重解析与依赖刷新。
本文详解如何配置 uv，使其在执行 `uv sync` 时主动更新 git 仓库类依赖（如 `git+https://...`），解决因远程仓库提交变更后本地依赖未同步导致的代码陈旧问题。核心方案是结合 `--upgrade` 标志触发锁文件重解析与依赖刷新。
在 Python 项目开发中，将 Git 仓库作为直接依赖（例如 git+https://github.com/PowerInsight/quantstats.git）是一种常见做法，尤其适用于尚未发布到 PyPI 的内部库或正在快速迭代的开源组件。然而，uv 默认的 uv sync 行为是“确定性同步”——它严格依据当前 uv.lock 文件安装依赖，不会主动检查远程 Git 仓库是否有新提交。这意味着即使你已向 quantstats 推送了关键修复，本地 .venv/Lib/site-packages/quantstats/ 中的代码仍保持旧版本，除非手动干预。
✅ 正确解决方案：使用 --upgrade 强制刷新 Git 依赖
要使 uv sync 具备“拉取最新 Git 提交”的能力，必须显式启用升级模式：
uv sync --upgrade
该命令等价于先执行 uv lock --upgrade（重新解析并更新 uv.lock 中所有依赖的版本信息，包括 Git 仓库的最新 commit hash），再执行 uv sync（根据更新后的锁文件重装依赖）。对于 Git 依赖，uv 会：
- 检查远程仓库
HEAD（或指定分支/标签）的最新 commit； - 将新 commit hash 写入
uv.lock； - 清理旧安装、重新克隆/拉取并安装该 commit 对应的代码。
? 验证效果：运行
uv sync --upgrade后，可查看uv.lock中对应依赖项的git字段是否已更新 commit hash；同时检查.venv/Lib/site-packages/quantstats/__init__.py等文件内容，确认已同步最新修改。
⚠️ 注意事项与最佳实践
-
不要依赖
--frozen：若项目中使用了uv sync --frozen（如 CI 环境要求绝对可重现），则--upgrade会被禁用。此时需权衡：生产环境应冻结依赖，而开发/测试环境推荐使用--upgrade保障实时性。 -
分支 vs. Commit 锁定：
- 使用
--branch main是便捷但非锁定的方式，每次--upgrade都会获取该分支最新 commit； - 若需稳定可重现，应在
pyproject.toml中显式指定 commit（推荐）：[project.dependencies] quantstats = { git = "https://github.com/PowerInsight/quantstats.git", rev = "a1b2c3d" }此时
uv sync --upgrade仅在rev显式更改时才更新，避免意外引入不兼容变更。
- 使用
-
reinstall-package不适用 Git 依赖：[tool.uv].reinstall-package仅控制已安装包是否强制重装，不触发远程 Git 拉取；它无法替代--upgrade对锁文件的更新逻辑。 -
cache-keys非必需：[tool.uv].cache-keys主要用于自定义缓存失效策略（如基于文件内容哈希），对 Git 依赖的自动更新无直接影响；默认行为已足够。
? 进阶建议：自动化开发工作流
为简化日常开发，可在 pyproject.toml 中定义脚本别名（需 uv ≥0.2.0）：
[project.scripts] sync-dev = "uv sync --upgrade --dev"
之后只需运行 uv run sync-dev，即可一键完成 Git 依赖拉取 + 开发依赖安装。
总之，uv sync --upgrade 是解锁 Git 依赖动态更新的关键开关。它既保持了 uv 的高性能与确定性优势，又赋予了开发者对上游变更的敏捷响应能力——无需手动 git pull 子模块，也无需反复 uv add，一条命令即刻同步真实世界中的代码演进。
