dart-resolve-package-conflicts

Dart 依赖项管理指南

目录

• 核心概念
• 版本约束
• 工作流：依赖项审计
• 工作流：升级依赖项
• 工作流：解决版本冲突
• 示例

核心概念

Dart 对依赖项实行严格的“单一版本”规则：项目及其所有传递依赖（transitive dependencies）必须解析并使用同一个包的唯一共享版本。这虽然避免了运行时类型不匹配的问题，但也带来了“版本锁定（version lock）”的风险。

为了缓解版本锁定，Dart 推荐在 pubspec.yaml 中使用版本约束，而非直接指定死固定版本。而 pubspec.lock 文件则会记录最终解析出的确切版本，以保障构建的可复现性（reproducible builds）。

理解 dart pub outdated 输出各列的含义：

• Current（当前版本）： pubspec.lock 中当前记录的版本。
• Upgradable（可升级版本）： 在 pubspec.yaml 版本约束许可范围内的最新版本，运行 dart pub upgrade 会升级到该版本。
• Resolvable（可解析版本）： 综合考虑项目中所有其它依赖项限制后，当前能解析出来的最高版本。
• Latest（最新版本）： 该包已发布的最新版本（不含预发布版/Prerelease）。

版本约束

• 优先使用脱字符语法（Caret Syntax）： 在 pubspec.yaml 中配置依赖时，始终推荐使用脱字符（如 ^1.2.3）。这样可以允许 pub 在解析时自动选择兼容的较新版本（最高支持到但不包含下一个大版本/Major Version）。
• 收紧开发依赖（Dev Dependencies）： 将 dev_dependencies 的版本下限设定为当前实际使用的确切版本。这能降低版本解析的复杂度，避免选到老旧或不兼容的开发工具。
• 在 CI 中强制校验 Lockfile： 在 CI/CD 流水线中使用 dart pub get --enforce-lockfile，确保生产环境构建所使用的依赖版本与本地测试验证过的版本完全一致。

工作流：依赖项审计

定期运行此工作流，找出可能影响稳定性或性能的陈旧依赖包。

任务进度：

• [ ] 运行 dart pub outdated。
• [ ] 查看 Upgradable 列，找出无需修改 pubspec.yaml 即可直接更新的包。
• [ ] 查看 Resolvable 列，找出需要修改 pubspec.yaml 中的版本约束才能升级的包。
• [ ] 检查是否有被标记为已被撤回（retracted）或已弃用（discontinued）的包。

工作流：升级依赖项

根据审计结果按需执行以下升级逻辑。

任务进度：

• [ ] 若升级到“Upgradable（可升级）”版本：
  • [ ] 运行 dart pub upgrade。
  • [ ] 运行 dart pub upgrade --tighten，自动更新 pubspec.yaml 中的版本下限，使其与最新解析出的版本保持同步。
• [ ] 若升级到“Resolvable（可解析）”版本（涉及大版本更新）：
  • [ ] 手动修改 pubspec.yaml，提高版本约束以匹配 Resolvable 列（例如将 ^0.11.0 修改为 ^0.12.1）。
  • [ ] 运行 dart pub upgrade 来解析新的版本约束并更新 pubspec.lock。
• [ ] 反馈闭环：
  • [ ] 运行 dart analyze -> 检查报错 -> 修复不兼容的 API 破坏性变更（breaking changes）。
  • [ ] 运行 dart test -> 查看失败项 -> 修复功能退化（regressions）。

工作流：解决版本冲突

当 pub 无法找到同时满足所有约束条件的具体版本组合，或者遇到某个包版本被官方撤回（retracted）时，需要精准操作 Lockfile 来手工解包。

绝对不要直接删掉整个 pubspec.lock 文件然后再跑 dart pub get！这会导致整个依赖树发生不可控的全量更新。

任务进度：

• [ ] 打开 pubspec.lock。
• [ ] 找到冲突或被撤回包对应的 YAML 配置块。
• [ ] 只删除该目标包在 Lockfile 中的条目。
• [ ] 运行 dart pub get，只为该特定包获取最新兼容且未被撤回的版本。
• [ ] 反馈闭环：
  • [ ] 运行 dart pub deps -> 验证依赖图谱是否已正确解析。
  • [ ] 如果依然解析失败，排查出导致锁定的传递依赖（transitive dependency），在 pubspec.yaml 中更新其版本约束后重试。

示例

自动收紧版本约束

当 dart pub outdated 显示某个包可以解析到更高的次版本/小版本（minor/patch version）时，使用 --tighten 标记自动更新 pubspec.yaml。

输入（pubspec.yaml）：

dependencies:
  http: ^0.13.0

命令：

dart pub upgrade --tighten http

输出（pubspec.yaml）：

dependencies:
  http: ^0.13.5

精准删除 Lockfile 冲突条目

如果 package_a 被撤回或者陷入版本冲突，仅从 pubspec.lock 中删除该包对应的代码块。

修改前（pubspec.lock）：

packages:
  package_a:
    dependency: "direct main"
    description:
      name: package_a
      url: "https://pub.dev"
    source: hosted
    version: "1.0.0" # Retracted version
  package_b:
    dependency: "direct main"
    # ...

操作： 完全删除 package_a 代码块，保持 package_b 不变。随后运行 dart pub get。