dart-resolve-package-conflicts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Dart Dependencies

Dart依赖管理

Core Concepts

核心概念

Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock."

To mitigate version lock, Dart relies on version constraints rather than pinned versions in the

pubspec.yaml

. The

pubspec.lock

file maintains the exact resolved versions for reproducible builds.

Understand the output columns of

dart pub outdated

Current: The version currently recorded in
```
pubspec.lock
```
.
Upgradable: The latest version allowed by the constraints in
```
pubspec.yaml
```
.
```
dart pub upgrade
```
resolves to this.
Resolvable: The absolute latest version that can be resolved when factoring in all other dependencies in the project.
Latest: The latest published version of the package (excluding prereleases).

Dart对依赖强制执行严格的单版本规则：项目及其所有传递依赖必须解析为某个包的单一共享版本。这避免了运行时类型不匹配，但会带来“版本锁定”的风险。

为了缓解版本锁定问题，Dart在

pubspec.yaml

中依赖版本约束而非固定版本。

pubspec.lock

文件维护了确切的解析版本，以实现可复现的构建。

了解

dart pub outdated

的输出列：

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

Version Constraints

版本约束

Use Caret Syntax: Always use caret syntax (e.g.,
```
^1.2.3
```
) for dependencies in
```
pubspec.yaml
```
. This allows
```
pub
```
to select newer, non-breaking versions (up to, but not including, the next major version) during resolution.
Tighten Dev Dependencies: Set the lower bound of
```
dev_dependencies
```
to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected.
Enforce Lockfiles in CI: Use
```
dart pub get --enforce-lockfile
```
in CI/CD pipelines to ensure the exact versions tested locally are used in production.

**使用脱字符语法：**在
```
pubspec.yaml
```
中始终为依赖使用脱字符语法（例如：
```
^1.2.3
```
）。这允许
```
pub
```
在解析期间选择较新的非破坏性版本（直至但不包含下一个主版本）。
**收紧开发依赖：**将
```
dev_dependencies
```
的下限设置为当前使用的确切版本。这降低了解析复杂度，并避免选择旧的、不兼容的开发工具。
**在CI中强制使用锁定文件：**在CI/CD流水线中使用
```
dart pub get --enforce-lockfile
```
，确保生产环境使用与本地测试完全相同的版本。

Workflow: Auditing Dependencies

工作流：审计依赖

Run this workflow periodically to identify stale packages that may impact stability or performance.

Task Progress:

Run
```
dart pub outdated
```
.
Review the Upgradable column to identify packages that can be updated without modifying
```
pubspec.yaml
```
.
Review the Resolvable column to identify packages that require constraint modifications in
```
pubspec.yaml
```
to update.
Identify any packages marked as retracted or discontinued.

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

任务进度：

运行
```
dart pub outdated
```
。
查看Upgradable列，识别无需修改
```
pubspec.yaml
```
即可更新的包。
查看Resolvable列，识别需要修改
```
pubspec.yaml
```
中的约束才能更新的包。
识别任何被撤回或已停止维护的包。

Workflow: Upgrading Dependencies

工作流：升级依赖

Use conditional logic based on the audit results to upgrade dependencies.

Task Progress:

If updating to "Upgradable" versions:
- Run
```
dart pub upgrade
```
  .
- Run
```
dart pub upgrade --tighten
```
  to automatically update the lower bounds in
```
pubspec.yaml
```
  to match the newly resolved versions.
If updating to "Resolvable" versions (Major updates):
- Manually edit
```
pubspec.yaml
```
  to bump the version constraint to match the "Resolvable" column (e.g., change
```
^0.11.0
```
  to
```
^0.12.1
```
  ).
- Run
```
dart pub upgrade
```
  to resolve the new constraints and update
```
pubspec.lock
```
  .
Feedback Loop:
- Run
```
dart analyze
```
  -> review errors -> fix breaking API changes.
- Run
```
dart test
```
  -> review failures -> fix regressions.

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

任务进度：

如果更新到“可升级”版本：
- 运行
```
dart pub upgrade
```
  。
- 运行
```
dart pub upgrade --tighten
```
  ，自动将
```
pubspec.yaml
```
  中的下限更新为匹配新解析的版本。
如果更新到“可解析”版本（主版本更新）：
- 手动编辑
```
pubspec.yaml
```
  ，将版本约束提升至与“Resolvable”列匹配（例如：将
```
^0.11.0
```
  改为
```
^0.12.1
```
  ）。
- 运行
```
dart pub upgrade
```
  ，解析新约束并更新
```
pubspec.lock
```
  。
反馈循环：
- 运行
```
dart analyze
```
  -> 查看错误 -> 修复API破坏性变更。
- 运行
```
dart test
```
  -> 查看失败用例 -> 修复回归问题。

Workflow: Resolving Version Conflicts

工作流：解决版本冲突

When

pub

cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically.

NEVER delete the entire

pubspec.lock

file and run

dart pub get

. This causes uncontrolled upgrades across the entire dependency graph.

Task Progress:

Open
```
pubspec.lock
```
.
Locate the specific YAML block for the conflicting or retracted package.
Delete ONLY that package's entry from the lockfile.
Run
```
dart pub get
```
to fetch the newest compatible, non-retracted version for that specific package.
Feedback Loop:
- Run
```
dart pub deps
```
  -> verify the dependency graph resolves correctly.
- If resolution fails, identify the transitive dependency causing the lock, update its constraint in
```
pubspec.yaml
```
  , and retry.

当

pub

无法找到满足所有约束的具体版本集，或者处理被撤回的包版本时，需精准操作锁定文件。

切勿删除整个

pubspec.lock

文件并运行

dart pub get

。这会导致整个依赖图不受控制地升级。

任务进度：

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

Examples

示例

Tightening Constraints

收紧约束

When

dart pub outdated

shows a package is resolvable to a higher minor/patch version, use the

--tighten

flag to update the

pubspec.yaml

automatically.

Input (
pubspec.yaml
):

yaml

dependencies:
  http: ^0.13.0

Command:

bash

dart pub upgrade --tighten http

Output (
pubspec.yaml
):

yaml

dependencies:
  http: ^0.13.5

当

dart pub outdated

显示某个包可以解析到更高的小版本/补丁版本时，使用

--tighten

标志自动更新

pubspec.yaml

。

输入（
pubspec.yaml
）：

yaml

dependencies:
  http: ^0.13.0

命令：

bash

dart pub upgrade --tighten http

输出（
pubspec.yaml
）：

yaml

dependencies:
  http: ^0.13.5

Surgical Lockfile Removal

精准删除锁定文件条目

package_a

is retracted or locked in a conflict, remove only its block from

pubspec.lock

Before (
pubspec.lock
):

yaml

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"
    # ...

Action: Delete the

package_a

block entirely. Leave

package_b

untouched. Run

dart pub get

如果

package_a

被撤回或陷入冲突，仅从

pubspec.lock

中删除其块。

修改前（
pubspec.lock
）：

yaml

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

。

dart-resolve-package-conflicts

Original

Translation

Managing Dart Dependencies

Dart依赖管理

Contents

目录

Core Concepts

核心概念

Version Constraints

版本约束

Workflow: Auditing Dependencies

工作流：审计依赖

Workflow: Upgrading Dependencies

工作流：升级依赖

Workflow: Resolving Version Conflicts

工作流：解决版本冲突

Examples

示例

Tightening Constraints

收紧约束

Surgical Lockfile Removal

精准删除锁定文件条目