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： 該套件已發布的最新版本（不含預覽版本）。

版本限制

• 使用 Caret 語法： 在 pubspec.yaml 設定相依套件時，一律使用插入符號語法（例如 ^1.2.3）。這能讓 pub 在解析時選擇較新且不具破壞性變更的版本（最高可升級至下一個主版本號之前的版本）。
• 收緊 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 變更。
  • [ ] 執行 dart test -> 檢視失敗項目 -> 修復退化問題（regressions）。

工作流程：解決版本衝突

當 pub 無法找到符合所有限制的具體套件版本組合，或是在處理已撤回的套件版本時，請對 lockfile 進行精準的操作。

切勿直接刪除整個 pubspec.lock 檔案並執行 dart pub get。這會導致整個相依套件圖發生不可控的大幅升級。

任務進度：

• [ ] 開啟 pubspec.lock。
• [ ] 找到發生衝突或已撤回套件的特定 YAML 區塊。
• [ ] 僅刪除該套件在 lockfile 中的條目。
• [ ] 執行 dart pub get，為該套件抓取最新相容且未被撤回的版本。
• [ ] 回饋驗證流程：
  • [ ] 執行 dart pub deps -> 確認相依套件圖已正確解析。
  • [ ] 若解析失敗，找出導致鎖定的間接相依套件（transitive dependency），在 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

精準刪除 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。