用途:在创建新的 Dart CLI 应用、重构现有 bin/ 入口、审查 CLI 代码质量,或为 Linux/Mac 设置可执行脚本时使用。
主要能力与做法:入口文件(如 bin/my_app.dart)应保持精简,仅导入 lib 中的逻辑并调用,避免在入口定义类或复杂逻辑,以提升可测试性。在 pubspec.yaml 中配置 executables 段,将命令名映射到 bin/ 下的 Dart 文件(不含 .dart 扩展名),之后可用 dart run my_app 调用。在 *nix 系统上可考虑在首行加 #!/usr/bin/env dart 并执行 chmod +x bin/my_script.dart 使其可直接运行。
进程终止:使用 exitCode setter 报告失败并让 main 自然结束,避免直接调用 exit(code),因为会立即终止 VM,妨碍调试与 finally 执行。建议使用标准退出码(如 64 表示用法错误、78 表示配置错误),可参考 package:io 的 ExitCode 类。未捕获异常会自动设置非零退出码,但预期错误应显式捕获处理并设置 exitCode。
跨平台:避免硬编码 / 路径分隔符,使用 package:path 的 p.join 或 p.normalize;测试文件权限错误时注意 Windows 无 chmod,可用 icacls 或 mock 库模拟。
推荐包:stack_trace、args、test_process、test_descriptor、http(需设置 User-Agent)、io(ANSI 输出);社区包包括 json_serializable、build_cli、build_version、checked_yaml。约定:缓存文件写入 .dart_tool/[pkg_name]/,HTTP 请求始终设置含版本信息的 User-Agent。
限制:资料未提供具体版本要求、完整示例代码或各包详细用法,需另行查阅对应文档。