欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

Dart 原生提供了 dart:io 库，包含了 File, Socket, Process, HTTP 等基础功能。但在编写复杂的命令行工具（CLI）或者需要跨平台处理文件路径、进程信号时，原生 API 往往显得过于底层且繁琐。

io (pkg:io) 是 Dart 官方维护的一个辅助库。它并不是 dart:io 的替代品，而是它的扩展包。它提供了：

• 更健壮的进程管理器 (ProcessManager)。
• ANSI 转义码支持（让你的终端输出彩色文字）。
• 共享标准输入输出的工具（shared_stdin）。
• 跨文件系统的复制/多级创建操作。

对于 OpenHarmony 开发者，如果你正在为鸿蒙生态编写构建脚本、CI 工具或者本地调试服务器，pkg:io 能让你事半功倍。

一、核心功能概览

1.1 ProcessManager (进程管理)

原生 Process.run 很简单，但 ProcessManager 允许你通过依赖注入的方式来管理进程创建。这意味着你可以方便地 Mock ProcessManager 来编写单元测试，而不需要真的去执行系统命令。

1.2 ANSI Code (终端彩色输出)

在日志中打印红色错误、绿色成功信息，或者移动光标、清除屏幕。

1.3 File System Utilities

提供了 copyPath (递归复制文件夹) 等原生 File 类没有的高级快捷方法。

二、集成与用法详解

2.1 添加依赖

dependencies:
  io: ^1.0.5

2.2 ANSI 彩色输出

让你的鸿蒙构建脚本输出更酷炫的日志。

import 'dart:io';
import 'package:io/ansi.dart';

void main() {
  // 1. 使用 helper 打印
  print(green.wrap('构建成功！')); 
  print(red.wrap('错误：文件未找到。'));
  print(styleBold.wrap('重要警告'));

  // 2. 混合样式
  print(red.wrap(styleBold.wrap('严重错误')));
  
  // 3. 覆盖标准输出 (仅在本次 block 中生效)
  overrideAnsiOutput(true, () {
    print(blue.wrap('强制蓝色文本'));
  });
}

2.3 进程管理 (ProcessManager)

⚠️ OpenHarmony 适配注意：在 OpenHarmony 的移动端及模拟器沙盒环境中，应用默认禁止派生系统进程（即禁止调用 /bin/sh 或执行 ls 等指令），此时调用 run 或 spawn 会抛出 Permission denied 异常。

建议场景：主要用于编写鸿蒙生态下的 Dart CLI 构建脚本，或在纯单元测试环境下使用。

import 'package:io/io.dart';

void main() async {
  var manager = ProcessManager();

  // 像 Process.run 一样使用，但更方便 mock
  var result = await manager.run(['ls', '-l']);
  print(result.stdout);
  
  // 派生进程
  var process = await manager.spawn('tail', ['-f', 'log.txt']);
  // ...
}

2.4 标准退出码 (Exit Codes)

不要再手写 exit(1) 了。Unix 系统定义了一套标准的退出码。

import 'dart:io';
import 'package:io/io.dart';

void main() {
  try {
    // ... logic
  } catch (e) {
    print(e);
    // 使用标准语义的退出码
    exit(ExitCode.software.code); // 70 (Internal software error)
    // 或者
    // exit(ExitCode.usage.code); // 64 (Command line usage error)
  }
}

三、OpenHarmony 适配与实战：递归复制资源

在 OpenHarmony 应用打包流程中，我们经常需要将 assets 目录下的所有文件递归复制到鸿蒙工程的 resources/rawfile 目录下。

原生 File.copy 只能复制文件，不能复制文件夹。pkg:io 补全了这个能力。

3.1 编写从 Flutter 到 OHOS 的资源同步脚本

import 'dart:io';
import 'package:io/io.dart'; // 引入 copyPath

Future<void> syncResources() async {
  final source = 'assets';
  final target = 'ohos/entry/src/main/resources/rawfile';

  print('同步资源: $source -> $target');

  try {
    // 递归复制整个目录
    await copyPath(source, target);
    print(green.wrap('同步完成！'));
  } catch (e) {
    print(red.wrap('同步失败: $e'));
    exit(ExitCode.ioError.code);
  }
}

3.2 处理权限与环境

在鸿蒙开发板或模拟器上运行 Dart 脚本时，如果使用了 ANSI color，需要确认终端是否支持（大多数现代终端如 iTerm2, VS Code Terminal 都支持，但在一些嵌入式 shell 中可能通过 ansiOutputEnabled 自动降级为纯文本）。

package:io 会自动检测 stdout.supportsAnsiEscapes，所以通常不需要额外适配。

四、高级进阶：SharedStdin

在编写交互式 CLI 时，如果多个组件（如 prompts 库和你的主逻辑）都试图读取 stdin，可能会产生冲突（流一旦被监听就成单播了）。

sharedStdIn 是一个广播流 (Broadcast Stream) 包装器，允许代码的不同部分共享对标准输入的访问。

import 'package:io/io.dart';

void listenInput() {
  // 可以在任意地方监听，不会独占
  sharedStdIn.transform(utf8.decoder).listen((line) {
    print('Input: $line');
  });
}

五、总结

package:io 是 Dart 工具链开发者的基础库。它虽然不直接参与 Flutter UI 渲染，但在 工程化、脚本化 方面扮演着重要角色。

对于 OpenHarmony 开发者：

• 构建自动化：利用其强大的 Process 和 FS 如果编写跨平台构建脚本（替代复杂的 Shell/Python 脚本）。
• 开发体验：用 ANSI color 提升日志可读性，快速定位鸿蒙构建中的错误。

它是 Dart 官方维护的质量保证，体积小巧，功能专注，是每个 Dart CLI 项目的 pubspec.yaml 中都应该存在的一行。

最佳实践：

1. Mock 测试：使用 ProcessManager 的主要动力就是为了能 Mock。在写测试时，注入一个假的 ProcessManager，返回预设的 ProcessResult，从而无需真实执行外部命令。
2. 规范退出码：养成使用 ExitCode 枚举的好习惯，这让你的 CLI 工具能更好地被其他脚本（如 CI 系统）集成和理解。

六、完整实战示例

import 'dart:io';
import 'package:io/io.dart';
import 'package:io/ansi.dart';

// 模拟一个构建脚本 scripts/build.dart
void main(List<String> args) async {
  // 1. 检查参数
  if (args.isEmpty) {
    print(red.wrap('❌ Error: Please provide a build target (e.g., debug/release).'));
    exit(ExitCode.usage.code);
  }

  final target = args.first;
  print(styleBold.wrap('🚀 Starting build for $target...'));

  // 2. 执行外部命令 (模拟鸿蒙构建命令)
  // 使用 ProcessManager 方便后续测试 Mock
  final manager = ProcessManager();
  
  try {
    // 模拟执行 hvigorw assembleHap
    print('Running build command...');
    final result = await manager.run(
      ['echo', 'Building $target environment...'], 
      runInShell: true
    );
    
    if (result.exitCode != 0) {
      print(red.wrap('Build failed with exits code ${result.exitCode}'));
      print(result.deferOutput()); // 打印积累的 stderr
      exit(ExitCode.software.code);
    }

    // 3. 文件操作与清理
    print('Cleaning up temp files...');
    // 使用 io 库提供的 copyPath, isLink 等工具方法 (如果需要)
    
    print(green.wrap('✅ Build Success!'));
    exit(ExitCode.success.code);

  } catch (e) {
    print(red.wrap('Unexpected error: $e'));
    exit(ExitCode.osFile.code);
  }
}