构建 Dart 命令行应用时如何组织入口、退出码…

在用 Dart 开发 CLI 工具、控制台程序或脚本时，提供架构、退出码、输出流、参数解析、子进程与打包的完整实践。

适用场景

解决思路

1. 避免直接调用 `exit(N)`：它会立即终止 OS 进程而不展开 Dart 栈，导致调试器断开、覆盖率丢失、缓冲区截断和资源泄漏；应设置 `exitCode = code` 或从 `CommandRunner<int>` 返回整数退出码，让异步 `main()` 自然返回；未处理错误时抛出异常而非调用 `exit()`。
2. 使用标准 POSIX 退出码：`0` 成功（`ExitCode.success.code`）、`64` 用法错误（`ExitCode.usage.code`）、`65` 数据格式错误（`ExitCode.data.code`）、`70` 内部崩溃（`ExitCode.software.code`）、`78` 配置错误（`ExitCode.config.code`）；优先从 `package:io/io.dart` 导入 `ExitCode` 常量而非魔法数字。
3. 采用薄入口点模式：`bin/*.dart` 仅作为最小入口跳板（实例化 runner、传入 `args`、await 退出码），所有命令定义、参数解析器、格式化器和业务逻辑放在 `lib/src/`，以便通过 `package:` URI 导入并在内存中快速单元测试。
4. 区分数据与诊断输出：程序结果和机器可读数据只写 `stdout`；警告、错误和调试日志只写 `stderr`。
5. 参数解析或必填选项错误时（`FormatException`、`UsageException` 或访问 `mandatory: true` 选项抛出的 `ArgumentError`），错误消息和用法文本都必须写入 `stderr`，并返回退出码 `64`；仅当用户显式请求 `--help` 或 `-h` 时用法帮助才写 `stdout`。
6. 错误处理中不要用 `print()`（它路由到 `stdout`），失败通知用 `stderr.writeln()`；标准输出优先用 `stdout.writeln()` 以符合 `avoid_print` lint 规则。
7. 输出 ANSI 颜色或光标转义码前检测终端能力：检查 `stdout.hasTerminal`、`stdout.supportsAnsiEscapes` 且 `!Platform.environment.containsKey('NO_COLOR')`。
8. 传入 `--json` 或 `--machine` 标志时，将数据以 JSON 格式写入 `stdout`，日志路由到 `stderr`。
9. 用 `dart create -t console <package_name>` 脚手架新项目，并在 `pubspec.yaml` 的 `executables:` 下声明可执行文件，将命令名映射到 `bin/` 中的脚本，以支持 `dart run <command>` 和 `dart install` 的全局符号链接。
10. 避免硬编码 `--version` 字符串或手动同步常量文件，使用 `package:build_version` 在构建时从 `pubspec.yaml` 生成 `lib/src/version.dart` 中的 `const packageVersion = 'x.y.z';`。
11. 将临时缓存文件存放在 `.dart_tool/<package_name>/`，不要直接写入项目根目录。
12. 使用 `package:args` 管理参数：简单脚本直接用 `ArgParser` 配合 `addFlag()` 和 `addOption()`；多命令工具实现 `CommandRunner<int>` 并为每个子命令扩展 `Command<int>`，直接返回 POSIX 退出码。
13. 使用类型安全访问器 `results.flag('name')`、`results.option('name')`、`results.multiOption('name')`（`package:args` 2.5+）替代 map 索引 `operator []`，消除手动类型转换。
14. 对于标志繁多的应用，使用 `package:build_cli` 生成强类型选项类，并利用命名默认值覆盖（如 `{String? hostDefaultOverride}`）合并配置文件与 CLI 标志。
15. 避免 `Chain.capture()`：Dart VM 原生保留跨 `await` 挂起点的异步栈帧，`Chain.capture` 会包装事件循环带来大量分配开销并跨 Zone 边界捕获错误。
16. 在未捕获错误上使用 `package:stack_trace` 的 `Trace.from(st).terse` 进行清理，而无需捕获 Zone。
17. 生成 Dart SDK 子进程或执行其他 Dart 工具时，不要假设 `Platform.resolvedExecutable` 或 `Platform.executable` 指向 `dart` 命令行可执行文件：在独立 AOT 编译二进制中它指向编译后的应用本身，会导致递归自调用或标志拒绝崩溃。
18. 使用 `package:cli_util` 的 `cli_util.dartExecutable` 或 `cli_util.sdkPath` 解析 Dart SDK 可执行文件，而非自定义 PATH 或目录扫描。
19. 若 CLI 修改终端模式、显示 spinner 或打开监听套接字：在 Windows 上用 `if (!Platform.isWindows)` 保护 `ProcessSignal.sigterm.watch()`，因为它会抛出 `UnsupportedError`。
20. 若设置 `stdin.echoMode = false` 或 `stdin.lineMode = false`，先检查 `if (!stdin.hasTerminal) return;`，并安装 `SIGINT` 监听器和 `finally` 块以恢复它们，确保退出后用户按键仍可见。
21. 若发出 ANSI 隐藏光标（`\x1B[?25l`），务必在退出或取消时恢复光标可见性（`\x1B[?25h`）。
22. 在终止信号上显式关闭监听的 `HttpServer` 或 `ServerSocket` 实例（`server.close(force: true)`），立即释放 OS 端口。
23. 分两层测试 CLI：单元测试（内存中，`< 5ms`）在 `test/` 中直接导入 `package:<pkg>/src/...` 测试命令类、选项解析和业务逻辑；集成测试用 `package:test_process` 和 `package:test_descriptor` 验证端到端二进制执行、进程 I/O 流和 OS 退出码。
24. Dart 3.12+ 使用 `dart run` 和 `dart install` 分发 CLI：`dart run <package>@<version> [args]` 按需下载运行（JIT）；`dart install <package>` 编译为原生 AOT 独立二进制到 `~/.dart/install/bin/`；本地开发用 `dart run <command>` 或 `dart run bin/cli.dart`；用 `dart build cli` 打包动态库和代码资产到 `build/cli/_/bundle/`；用 `dart compile exe bin/cli.dart -o <output_path>` 编译独立可执行文件。
25. 实现工作流检查清单：在 `pubspec.yaml` 的 `executables:` 声明入口点；保持 `bin/*.dart` 为薄入口，命令逻辑放 `lib/src/`；返回整数退出码或设置 `exitCode = N`，避免裸 `exit(N)`；解析失败时将错误、警告和用法写入 `stderr`；使用 `results.flag()`、`results.option()`、`results.multiOption()` 保证类型安全；发出 ANSI 码前验证 `useAnsi`；用 `cli_util.dartExecutable` 生成子工具，绝不用 `Platform.resolvedExecutable`；在内存中单元测试命令 runner，用 `test_process` 测试端到端二进制执行。

适用边界 · 注意事项

• 不适用于 Flutter UI 组件、Web 应用或独立 HTTP 后端服务器。
• 若项目不需要命令行交互、参数解析或子进程管理，则无需采用这些模式。