dart-package-management

管理 Dart 包

目录

• 包布局约定
• Pubspec 配置
• Monorepo 工作区
• 工作流
• 示例

包布局约定

使用标准化目录组织 Dart 包，以确保工具兼容性并明确 API 边界。

• lib/：在此处放置公共库和资源。仅导出公共 API。
• lib/src/：在此处放置内部实现文件。切勿从其他包的 lib/src/ 导入内容。在自己的包中从 lib/src/ 导入到 lib/ 时，请使用相对导入。
• bin/：在此处放置公共命令行可执行文件。
• tool/：在此处放置内部脚本和工具（例如代码生成、文档脚本）。
• test/：在此处放置单元测试，文件名以 _test.dart 结尾。
• integration_test/：在此处放置耗时较长的集成级测试。
• example/：在此处放置展示包用法的独立示例程序。使用 package: 导入引用父包。
• web/：在此处放置 Web 专用入口点（main.dart）和资源（index.html、CSS）。
• hook/：在此处放置 SDK 构建钩子（例如 build.dart）。

Pubspec 配置

确保每个包的根目录都有有效的 pubspec.yaml。

• 版本约束：使用插入符号语法（^）指定依赖项版本约束（例如 ^3.2.0），以允许不含破坏性变更的更新。
• SDK 约束：始终定义 environment，并设置 SDK 的最低版本约束。
• 公共资源：明确列出包所需的所有公共资源（图片、字体）。
• 可执行文件：在 executables 字段下，将 bin/ 中的脚本映射到命令名称。
• 元数据：已发布的包应包含 name、version、description、repository 和 issue_tracker。
• 主题：使用 topics 字段为已发布的包分类（最多 5 个主题，仅限小写字母数字字符和连字符）。
• 误报密钥：使用 false_secrets 字段和 gitignore 模式，避免 pub 在发布前检测泄漏时产生误报。

Monorepo 工作区

在 monorepo 中实现工作区，以便本地包共享依赖项，减少内存用量并确保版本一致。

• 根 Pubspec：在仓库根目录定义工作区。设置 publish_to: none，要求 SDK 版本为 ^3.6.0 或更高，并使用 workspace 字段和 glob 模式（例如 packages/*）。
• 子 Pubspec：在每个工作区包中，要求 SDK 版本为 ^3.6.0 或更高，并设置 resolution: workspace。
• 相互依赖：像依赖普通包一样依赖其他工作区包。Pub 会自动解析到本地工作区版本。
• 覆盖项：将 dependency_overrides 放在根目录的 pubspec.yaml 中，以便在整个工作区全局应用覆盖项。

工作流

设置 Monorepo 工作区

使用此检查清单，将标准仓库转换为 Dart 工作区。

• 创建根目录的 pubspec.yaml。
• 在根 pubspec 中设置 publish_to: none 和 environment: sdk: ^3.6.0。
• 在根 pubspec 中使用 glob 模式添加 workspace: 字段（例如 - packages/*）。
• 更新所有子目录中的 pubspec.yaml 文件，添加 environment: sdk: ^3.6.0（或更高版本）。
• 在所有子目录的 pubspec.yaml 文件中添加 resolution: workspace。
• 在仓库根目录运行 dart pub get。
• 反馈循环：运行验证器 -> 检查错误 -> 修复。确保子目录中没有多余的 pubspec.lock 或 .dart_tool/package_config.json 文件。如果解析失败，请统一各子包中冲突的依赖项版本。

管理依赖项

• 运行 dart pub get 获取依赖项并生成 package_config.json。
• 运行 dart pub upgrade，将依赖项更新到最新兼容版本。
• 仅为应用程序包提交 pubspec.lock。库包不应提交此文件。

示例

Standard Library Pubspec

name: enchilada
description: A comprehensive toolkit for newt transmogrification.
version: 1.2.3
repository: https://github.com/example/enchilada
issue_tracker: https://github.com/example/enchilada/issues

environment:
  sdk: ^3.6.0

dependencies:
  path: ^1.8.0
  transmogrify: ^0.4.0

dev_dependencies:
  test: ^2.0.0
  lints: ^3.0.0

executables:
  enchilada: main

topics:
  - transmogrification
  - utilities

Workspace Root Pubspec

name: my_monorepo
publish_to: none

environment:
  sdk: ^3.6.0

workspace:
  - packages/*

# Apply overrides globally across all workspace packages
dependency_overrides:
  transmogrify: ^0.5.0-dev

Workspace Child Pubspec

name: client_package
description: The client application for the monorepo.
version: 1.0.0
publish_to: none

environment:
  sdk: ^3.6.0

resolution: workspace

dependencies:
  shared_package: ^1.0.0 # Resolves locally within the workspace
  http: ^1.1.0