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" # 撤回的版本
  package_b:
    dependency: "direct main"
    # ...

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