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。