Dart packages pub

管理 Dart 包生态

Contents

• 使用 Package
• 创建 Package
• 发布 Package
• 依赖管理与版本策略
• 工作空间 (Workspace)
• Hooks 机制
• Workflow: 创建并发布一个 Dart Package
• Examples

使用 Package

添加依赖

dart pub add http        # 添加常规依赖
dart pub add dev:test    # 添加开发依赖
dart pub add http:^1.0.0 # 指定版本约束

pubspec.yaml 中的依赖声明

name: my_app
environment:
  sdk: ^3.6.0

dependencies:
  http: ^1.2.0
  path: ^1.9.0

dev_dependencies:
  test: ^1.25.0
  lints: ^5.0.0

依赖类型

类型	声明位置	用途
常规依赖	dependencies	运行时需要的包
开发依赖	dev_dependencies	开发工具、测试框架
依赖覆盖	dependency_overrides	临时覆盖传递依赖版本

创建 Package

使用 dart create 命令

dart create -t package my_package

生成的文件结构：

my_package/
├── lib/
│   └── my_package.dart          # 公开 API
├── lib/src/                      # 内部实现
│   └── my_package_base.dart
├── test/
│   └── my_package_test.dart
├── pubspec.yaml
├── README.md
├── CHANGELOG.md
├── LICENSE
└── analysis_options.yaml

pubspec.yaml 完整示例

name: my_package
description: A sample Dart package
version: 1.0.0
repository: https://github.com/user/my_package

environment:
  sdk: ^3.6.0

dependencies:
  meta: ^1.15.0

dev_dependencies:
  test: ^1.25.0
  lints: ^5.0.0

包的文件结构规范

• lib/ — 公开 API，所有 import 'package:xxx/yyy.dart' 的入口
• lib/src/ — 内部实现，不应对用户暴露
• test/ — 测试文件，命名以 _test.dart 结尾
• example/ — 用法示例
• bin/ — 可执行入口（若为命令行工具）
• benchmark/ — 性能测试

发布 Package

发布前检查

dart pub publish --dry-run   # 模拟发布，检查问题
dart analyze                  # 确保零错误
dart test                     # 确保测试通过
dart doc                      # 生成文档

发布到 pub.dev

dart pub publish

发布前必须确保：

1. pubspec.yaml 包含 description、version、repository 和 environment
2. CHANGELOG.md 已更新
3. LICENSE 文件存在
4. 分析器零错误零警告

版本管理

Dart 使用语义化版本 (semver)：MAJOR.MINOR.PATCH

版本号变更	含义
1.2.3 → 1.2.4	修复 bug（PATCH）
1.2.3 → 1.3.0	新增功能，兼容旧版（MINOR）
1.2.3 → 2.0.0	破坏性变更（MAJOR）

dart pub version major   # 1.0.0 → 2.0.0
dart pub version minor   # 1.0.0 → 1.1.0 (加 prerelease: --preid=alpha)
dart pub version patch   # 1.0.0 → 1.0.1

依赖管理与版本策略

版本约束写法

dependencies:
  package_a: ^1.2.3       # >=1.2.3 <2.0.0（caret 约束）
  package_b: '>=2.0.0 <3.0.0'  # 显式范围
  package_c: any          # 任意版本（不推荐）

依赖覆盖

用于临时替换传递依赖的版本：

dependency_overrides:
  some_package: ^2.0.0     # 强制使用指定版本

注意：dependency_overrides 仅在开发时使用，不应在发布包中使用。

传递依赖

dart pub deps              # 查看依赖树
dart pub deps --json       # JSON 格式输出
dart pub outdated          # 检查可更新的依赖
dart pub upgrade           # 更新到最新兼容版本

工作空间 (Workspace)

Pub 工作空间支持在单个开发环境中管理多个相互依赖的包（monorepo）。

配置工作空间

根目录 pubspec.yaml：

name: my_workspace
publish_to: none

environment:
  sdk: ^3.6.0

workspace:
  - packages/package_a
  - packages/package_b
  - packages/shared

子包 packages/package_a/pubspec.yaml：

name: package_a
environment:
  sdk: ^3.6.0

dependencies:
  shared: any    # 工作空间内的包自动解析

工作空间命令

# 在工作空间任意位置运行
dart pub get       # 为所有成员解析依赖
dart test          # 运行当前包的测试
dart run build_runner build  # 在所有成员中运行

使用场景

• 大型项目拆分为多个子包
• 共享代码库（models、utils、api client）
• Flutter 应用的模块化开发

Hooks 机制

Dart Hooks 允许在开发工作流的特定节点自动执行脚本。

配置文件 .agents/hooks.json

{
  "dart-format": {
    "Stop": [
      {
        "type": "command",
        "command": "dart format .",
        "timeout": 30
      }
    ]
  },
  "dart-analyze": {
    "Stop": [
      {
        "type": "command",
        "command": "dart analyze",
        "timeout": 90
      }
    ]
  }
}

事件类型：

• Stop — Agent 停止编辑后触发
• Start — Agent 开始编辑前触发

Workflow: 创建并发布一个 Dart Package

Task Progress

• Step 1: 创建包骨架。 运行 dart create -t package <name> 生成项目结构。
• Step 2: 配置 pubspec.yaml。 填写 name、description、version、repository、SDK 约束和依赖。
• Step 3: 实现功能。 在 lib/ 下编写公开 API，在 lib/src/ 下编写内部实现。使用 library 或 barrel file 导出。
• Step 4: 编写测试。 在 test/ 目录创建 *_test.dart 文件，确保核心功能有测试覆盖。
• Step 5: 编写文档。 使用 /// 文档注释，编写 README.md 和 CHANGELOG.md。
• Step 6: 运行质量检查。 依次执行 dart analyze、dart test、dart doc。
• Step 7: 模拟发布检查。 运行 dart pub publish --dry-run 确认所有必需文件就位。
• Step 8: 正式发布。 运行 dart pub publish 发布到 pub.dev。
• Step 9: 版本迭代。 使用 dart pub version <major|minor|patch> 更新版本号后重复发布流程。
• Step 10: Feedback Loop。 审查发布输出 → 修复警告 → 更新 CHANGELOG → 重新发布。

条件逻辑

• 如果创建 NEW Package： 使用 dart create -t package 命令生成标准骨架。
• 如果创建命令行工具： 使用 dart create -t console-full 并在 executables 字段声明入口。
• 如果配置工作空间 (monorepo)： 在根目录 pubspec.yaml 中添加 workspace 字段列出所有成员包路径。
• 如果依赖工作空间内的子包： 使用 any 作为版本约束，pub 自动解析到本地版本。
• 如果发布到 pub.dev： 确保 dependency_overrides 已移除，version 字段不为空。
• 如果遇到版本冲突： 运行 dart pub outdated 查看可更新依赖，使用 dependency_overrides 临时解决。

Examples

创建和发布一个完整的 Package

dart create -t package dart_math_utils
cd dart_math_utils

// lib/dart_math_utils.dart
export 'src/math_utils_base.dart';

// lib/src/math_utils_base.dart
extension MathUtils on num {
  double percentOf(num total) => this / total * 100;
  
  bool isBetween(num min, num max) => this >= min && this <= max;
}

int factorial(int n) {
  if (n < 0) throw ArgumentError('n must be non-negative');
  if (n == 0) return 1;
  return n * factorial(n - 1);
}

// test/dart_math_utils_test.dart
import 'package:dart_math_utils/dart_math_utils.dart';
import 'package:test/test.dart';

void main() {
  group('factorial', () {
    test('factorial(0) returns 1', () {
      expect(factorial(0), equals(1));
    });
    
    test('factorial(5) returns 120', () {
      expect(factorial(5), equals(120));
    });
  });
  
  group('percentOf', () {
    test('25.percentOf(100) returns 25', () {
      expect(25.percentOf(100), equals(25.0));
    });
  });
}

# pubspec.yaml
name: dart_math_utils
description: Useful math utility functions and extensions for Dart.
version: 1.0.0
repository: https://github.com/user/dart_math_utils

environment:
  sdk: ^3.6.0

dev_dependencies:
  test: ^1.25.0
  lints: ^5.0.0

工作空间配置示例

# 根目录 pubspec.yaml
name: my_monorepo
publish_to: none

environment:
  sdk: ^3.6.0

workspace:
  - packages/shared
  - packages/api
  - packages/app

# packages/api/pubspec.yaml
name: my_api
environment:
  sdk: ^3.6.0

dependencies:
  shared: any
  http: ^1.2.0