dart-resolve-package-conflicts

Dart の依存関係を管理する

目次

• 基本概念
• バージョン制約
• ワークフロー：依存関係の監査
• ワークフロー：依存関係のアップグレード
• ワークフロー：バージョンの競合を解決する
• 例

基本概念

Dart では、依存関係に厳密な単一バージョンルールが適用されます。プロジェクトとそのすべての推移的依存関係では、特定のパッケージのバージョンを 1 つに統一して解決する必要があります。これにより実行時の型の不一致を防げますが、「バージョンロック」のリスクが生じます。

バージョンロックを軽減するため、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 を実行します。