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

前言

随着 Flutter 和 Dart 生态的繁荣，我们写了越来越多的 CLI (命令行) 工具：代码生成脚本、CI/CD 辅助工具、鸿蒙 HAP 包签名工具等。

当这些工具分发给团队成员使用时，最大的痛点是 更新问题。

• “你的脚本报错了？哦，你用的还是上个月的版本，快 pub global activate 一下。”
• “新功能即使发布了，也没人知道要去更新。”

pub_updater 是一个专门用于检查和更新 Dart CLI 工具的库。它可以集成在你的命令行工具内部，自动检查 Pub 上是否有新版本，并提示（甚至自动）更新。

一、核心功能

pub_updater 的功能非常纯粹：

1. Check: 检查当前安装版本是否是最新的。
2. Update: 执行更新命令（实际是调用 dart pub global activate）。

它使得你的 CLI 工具具备了“自我进化”的能力。

二、集成与用法详解

2.1 添加依赖

dependencies:
  pub_updater: ^0.5.0

2.2 实战：为 CLI 添加更新检查

假设你写了一个工具叫 ohos_helper。在它的入口函数中：

import 'package:pub_updater/pub_updater.dart';

void main(List<String> args) async {
  final updater = PubUpdater();
  const packageName = 'ohos_helper';
  const currentVersion = '1.0.0'; // 通常从 pubspec.yaml 读取

  // 1. 检查更新
  final isUpToDate = await updater.isUpToDate(
    packageName: packageName,
    currentVersion: currentVersion,
  );

  if (!isUpToDate) {
    final latestVersion = await updater.getLatestVersion(packageName);
    print('⚠️ 发现新版本: $latestVersion (当前: $currentVersion)');
    
    // 2. 询问更新
    // (这里可以使用 dcli 或 prompts 库获取用户输入)
    print('正在自动更新...');
    
    // 3. 执行更新
    await updater.update(packageName: packageName);
    print('✅ 更新完成！请重新运行命令。');
    return; // 退出当前进程
  }

  // 执行正常逻辑
  print('运行 ohos_helper 逻辑...');
}

三、OpenHarmony 适配与实战：处理私有源与鸿蒙镜像

国内开发者（尤其是鸿蒙生态）通常会使用国内的 Pub 镜像（如 TUNA, 腾讯云）或者公司内部的私有 Pub 服务器。

pub_updater 默认查询 pub.dev。要适配国内环境或私有源，我们需要一点小技巧。

3.1 机制分析

pub_updater 内部也是通过 HTTP 请求去查询包信息的。不过好消息是，update() 方法本质上是调用本地的 dart pub global activate 命令，这个命令会自动遵循用户环境变量中的 PUB_HOSTED_URL。

但是 getLatestVersion 默认是写死查询 pub.dev 的。如果你的包只发在私有服，需要自行处理。

3.2 适配私有源

如果你的工具发布在私有服务器，或者需要通过国内镜像检查更新，目前 pub_updater 可能需要 fork 修改或者你在调用时传入 baseUrl（如果库支持）。截至目前版本，直接支持自定义 upstream url 的 API 比较有限，建议的 Workaround：

如果你是在企业内网，可以将 检查更新 的逻辑替换为查询自己的 Version API，而只利用 pub_updater 的 update 方法（因为它就是一层 shell 封装）。

// 使用 update 方法，它会 respecting 用户的 PUB_HOSTED_URL
await updater.update(packageName: 'my_private_pkg');

四、场景延伸：鸿蒙构建工具链管理

OpenHarmony 的构建涉及很多步骤（hvigor, ohpm 等）。如果我们用 Dart 编写了一套 ohos_ci_toolkit 来封装这些流程。

确保团队所有成员的 ohos_ci_toolkit 都是最新版至关重要，因为构建脚本的 Bug 可能会导致产生的 HAP 包不可用。

建议：

1. 强制更新策略：在 CI/CD 环境中，运行工具前先自动执行 update。
2. 版本锁定：在 pubspec.yaml 中严格锁定依赖，或者使用 pub_updater 检查到大版本更新时强制报错并退出，逼迫开发者更新。

五、总结

pub_updater 是 Dart CLI 开发者的良伴。它让你的工具不再是一座孤岛，而是一个可以持续交付的产品。

对于 OpenHarmony 社区，随着越来越多的鸿蒙辅助开发工具（Flutter 写的）出现，使用标准化的更新机制，有助于维护整个社区生态的健康和活跃度。

最佳实践：

1. 异步检查：将检查更新放在后台运行（不 await），避免阻塞 CLI 的启动速度（CLI 响应速度很重要）。等用户跑完命令后，再打印一行“发现新版本”的日志。
2. 错误处理：网络请求可能会失败（比如没网的时候），记得 try-catch 检查更新的代码，别让更新检查的失败导致主功能无法使用。
3. 区分环境：在 CI 环境下（检测 CI 环境变量），通常不需要交互式更新，而是应该直接失败或自动静默更新。

六、完整实战示例

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

// 模拟 CLI 工具入口
void main() async {
  final updater = PubUpdater();
  const packageName = 'my_ohos_cli';
  const currentVersion = '1.0.2';

  print('🔧 My OHOS CLI v$currentVersion');
  
  // 1. 异步后台检查更新 (不阻塞主业务)
  final updateCheckFuture = _checkUpdate(updater, packageName, currentVersion);

  // 2. 执行核心业务逻辑
  await _runBusinessLogic();

  // 3. 业务结束前，展示更新提示
  // 这里 await 只是为了保证 main 退出前打印日志，实际 CLI 可能直接退出
  await updateCheckFuture;
}

Future<void> _checkUpdate(PubUpdater updater, String name, String current) async {
  try {
    final isUpToDate = await updater.isUpToDate(
      packageName: name,
      currentVersion: current,
    );
    
    if (!isUpToDate) {
      final latest = await updater.getLatestVersion(name);
      print('\n📢 ==================================');
      print('📢 发现新版本: $latest (当前: $current)');
      print('📢 运行下面的命令进行更新:');
      print('📢 dart pub global activate $name');
      print('📢 ==================================\n');
      
      // 注意：如果策略允许，这里甚至可以直接调用：
      // await updater.update(packageName: name);
    }
  } catch (e) {
    // 检查更新失败是次要错误，静默处理，不要打扰用户
    // print('Debug: Update check failed: $e');
  }
}

Future<void> _runBusinessLogic() async {
  print('正在构建 HAP 包...');
  // 模拟耗时操作
  await Future.delayed(Duration(seconds: 1));
  print('✅ 构建完成!');
}