dart-resolve-package-conflicts

管理 Dart 依赖项

目录

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

核心概念

Dart 对依赖项实施严格的单版本规则：项目及其所有传递依赖项必须将任意给定的包解析为同一个共享版本。这可以避免运行时类型不匹配，但也带来了“版本锁定”的风险。

为缓解版本锁定问题，Dart 在 pubspec.yaml 中依赖版本约束，而非固定版本。pubspec.lock 文件会记录确切的已解析版本，以确保构建可复现。

了解 dart pub outdated 输出列的含义：

• Current（当前版本）： pubspec.lock 中当前记录的版本。
• Upgradable（可升级版本）： pubspec.yaml 中的约束所允许的最新版本。dart pub upgrade 会解析到此版本。
• Resolvable（可解析版本）： 综合考虑项目中的所有其他依赖项后，可以解析到的最高版本。
• Latest（最新版本）： 已发布的该包的最新版本（不包括预发布版本）。

版本约束

• 使用插入符语法： pubspec.yaml 中的依赖项始终使用插入符语法（例如 ^1.2.3）。这样在解析期间，pub 可以选择更新且不会造成破坏的版本（最高不超过下一个主版本）。
• 收紧开发依赖项： 将 dev_dependencies 的下限设为当前使用的确切版本。这可以降低解析复杂度，并避免选择较旧且不兼容的开发工具。
• 在 CI 中强制使用锁定文件： 在 CI/CD 流水线中使用 dart pub get --enforce-lockfile，以确保生产环境使用与本地测试完全相同的版本。

工作流：审计依赖项

定期运行此工作流，以发现可能影响稳定性或性能的过时包。

任务进度：

• 运行 dart pub outdated。
• 查看 Upgradable 列，找出无需修改 pubspec.yaml 即可更新的包。
• 查看 Resolvable 列，找出需要修改 pubspec.yaml 中的约束才能更新的包。
• 找出被标记为已撤回或已停止维护的包。

工作流：升级依赖项

根据审计结果采用条件逻辑升级依赖项。

任务进度：

• 如果更新到“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 更改。
  • 运行 dart test -> 查看失败项 -> 修复回归问题。

工作流：解决版本冲突

当 pub 无法找到一组满足所有约束的具体版本，或需要处理已撤回的软件包版本时，请精准修改锁定文件。

切勿删除整个 pubspec.lock 文件并运行 dart pub get。这会导致整个依赖关系图发生不可控的升级。

任务进度：

• 打开 pubspec.lock。
• 找到冲突或已撤回软件包对应的 YAML 块。
• 仅删除锁定文件中该软件包的条目。
• 运行 dart pub get，为该特定软件包获取最新的兼容且未撤回的版本。
• 反馈循环：
  • 运行 dart pub deps -> 验证依赖关系图是否正确解析。
  • 如果解析失败，找出导致锁定的传递依赖，在 pubspec.yaml 中更新其约束，然后重试。

示例

收紧约束

当 dart pub outdated 显示某个软件包可以解析到更高的小版本或补丁版本时，使用 --tighten 标志自动更新 pubspec.yaml。

输入（pubspec.yaml）：

dependencies:
  http: ^0.13.0

命令：

dart pub upgrade --tighten http

输出（pubspec.yaml）：

dependencies:
  http: ^0.13.5

精准移除锁定文件条目

如果 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。