Flutter for OpenHarmony：pub_updater 命令行工具自动更新专家（DevOps 运维必备） 深度解析与鸿蒙适配指南
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net
前言
随着 Flutter 和 Dart 生态的繁荣，我们写了越来越多的 CLI (命令行) 工具：代码生成脚本、CI/CD 辅助工具、鸿蒙 HAP 包签名工具等。
当这些工具分发给团队成员使用时，最大的痛点是 更新问题。
- “你的脚本报错了？哦，你用的还是上个月的版本，快
pub global activate一下。” - “新功能即使发布了，也没人知道要去更新。”
pub_updater 是一个专门用于检查和更新 Dart CLI 工具的库。它可以集成在你的命令行工具内部，自动检查 Pub 上是否有新版本，并提示（甚至自动）更新。
一、核心功能
pub_updater 的功能非常纯粹：
- Check: 检查当前安装版本是否是最新的。
- Update: 执行更新命令（实际是调用
dart pub global activate）。
它使得你的 CLI 工具具备了“自我进化”的能力。
启动
有更新吗?
查询
返回最新版
对比
新版本!
用户同意
用户运行 CLI
我的工具
PubUpdater
Pub.dev / 私有镜像
提示更新
下载并更新
二、集成与用法详解
2.1 添加依赖
dependencies:pub_updater: ^0.5.0 2.2 实战：为 CLI 添加更新检查
假设你写了一个工具叫 ohos_helper。在它的入口函数中：
import'package:pub_updater/pub_updater.dart';voidmain(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_URLawait updater.update(packageName:'my_private_pkg');四、场景延伸：鸿蒙构建工具链管理
OpenHarmony 的构建涉及很多步骤（hvigor, ohpm 等）。如果我们用 Dart 编写了一套 ohos_ci_toolkit 来封装这些流程。
确保团队所有成员的 ohos_ci_toolkit 都是最新版至关重要，因为构建脚本的 Bug 可能会导致产生的 HAP 包不可用。
建议：
- 强制更新策略：在 CI/CD 环境中，运行工具前先自动执行
update。 - 版本锁定：在
pubspec.yaml中严格锁定依赖，或者使用pub_updater检查到大版本更新时强制报错并退出，逼迫开发者更新。
五、总结
pub_updater 是 Dart CLI 开发者的良伴。它让你的工具不再是一座孤岛，而是一个可以持续交付的产品。
对于 OpenHarmony 社区，随着越来越多的鸿蒙辅助开发工具（Flutter 写的）出现，使用标准化的更新机制，有助于维护整个社区生态的健康和活跃度。
最佳实践：
- 异步检查：将检查更新放在后台运行（不 await），避免阻塞 CLI 的启动速度（CLI 响应速度很重要）。等用户跑完命令后，再打印一行“发现新版本”的日志。
- 错误处理：网络请求可能会失败（比如没网的时候），记得 try-catch 检查更新的代码，别让更新检查的失败导致主功能无法使用。
- 区分环境：在 CI 环境下（检测
CI环境变量），通常不需要交互式更新，而是应该直接失败或自动静默更新。
六、完整实战示例
import'dart:io';import'package:pub_updater/pub_updater.dart';// 模拟 CLI 工具入口voidmain()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 包...');// 模拟耗时操作awaitFuture.delayed(Duration(seconds:1));print('✅ 构建完成!');}
