UV包管理学习 - 解决Python包线上线下版本不一致的问题

背景

代码线下本地测试运行正常，线上返回结果与线下不一致，提示agent缺失解析失败。如下代码中没有返回agent，导致系统出错。

async for agent, _, event_data in graph.astream(
    input_,
    config={
        "thread_id": thread_id,
        "resources": resources,
        "max_plan_iterations": max_plan_iterations,
        "max_step_num": max_step_num,
        "max_search_results": max_search_results,
        "mcp_settings": mcp_settings,
    },
    stream_mode=["messages", "updates"],
    subgraphs=True,
):

随后翻看项目依赖管理，包管版本管理如下

xxx包>=0.3.8，版本指定的是一个范围，随即查阅资料

`> = 0.3.8 表示安装满足条件的最新可用版本，不同时间、不同环境会安装不同的具体版本，这可能导致环境不一致和兼容性问题

可能产生下列问题

• API 变化：新版本可能引入破坏性更改
• 行为差异：不同版本在相同代码下可能表现不同
• 调试困难：版本不一致使问题难以复现

解决方案

锁定版本

为了解决问题，保证线上版本与线下测试一致，因此流程可以归结为

本地调试 → 锁定版本 → 上传锁文件 → 同步依赖

1. 本地开发阶段

• 在 pyproject.toml 中声明依赖（使用 兼容性版本约束，如 >= 或 ^）：

  [project]
  name = "my-project"
  version = "0.1.0"
  
  [project.dependencies]
  requests = "^2.31.0"  # 允许 2.31.0 ≤ 版本 < 3.0.0
  numpy = ">=1.21.0"    # 允许 ≥1.21.0
  

• 运行 uv lock 生成 uv.lock（锁定所有依赖的精确版本）。
• 运行 uv install --locked 安装依赖（确保本地开发环境使用锁定的版本）。

2. 提交代码时

• 必须提交 pyproject.toml 和 uv.lock 到 Git：
  • pyproject.toml：声明依赖的兼容范围（供开发时参考）。
  • uv.lock：记录实际安装的精确版本（确保生产环境一致）。

3. 生产环境 / CI/CD 部署

• 在服务器或 CI/CD 环境（如 GitHub Actions、Docker）中：
  1. 克隆代码（包含 pyproject.toml 和 uv.lock）。
  2. 运行 uv install --locked：
     • uv 会 严格按照 uv.lock 中的版本 安装依赖，确保与本地开发环境完全一致。

依赖更新流程（当需要升级时）

如果需要升级某个依赖（例如 requests 升级到 2.32.0）：

1. 修改 pyproject.toml（放宽约束或指定新版本）：

   requests = "^2.32.0"  # 更新兼容范围
   

2. 运行 uv lock 重新生成 uv.lock（解析最新兼容版本）。
3. 运行 uv install --locked 安装新版本。
4. 测试本地环境，确认无误后提交更新的 pyproject.toml 和 uv.lock。

为什么这样设计？

• pyproject.toml：声明“我允许哪些版本”（灵活）。
• uv.lock：记录“本次安装的实际版本”（严格）。
• uv install --locked：确保生产环境 完全复现 本地调试通过的版本。

常见错误

❌ 错误做法 1：直接修改 uv.lock 并提交

• 为什么错：uv.lock 应该由 uv lock 自动生成，手动修改可能导致版本冲突。
• 正确做法：修改 pyproject.toml 后重新运行 uv lock。

❌ 错误做法 2：生产环境直接运行 uv install（不加 --locked）

• 为什么错：uv install 会忽略 uv.lock，根据 pyproject.toml 重新解析版本，可能导致不一致。
• 正确做法：生产环境必须用 uv install --locked。

❌ 错误做法 3：pyproject.toml 写死 == 版本

• 为什么错：无法自动获取 Bug 修复和安全更新。
• 正确做法：用 >= 或 ^ 声明兼容范围，由 uv.lock 锁定具体版本。

总结

这样既能 灵活开发（允许兼容性更新），又能 稳定生产（锁文件确保一致性）。