系列: DevEco CLI 工具链实战 · 第 1 篇

---

引言

DevEco Studio 是 HarmonyOS 官方 IDE，但 CI/CD 流水线、远程构建、AI 辅助编程、快速原型验证等场景并不需要完整的 GUI。devecocli 将 DevEco Studio 底层的 ohpm、hvigor、hdc、emulator、hilog 等工具链统一封装为单一命令行入口，同时新增项目脚手架、Skills 市场、本地文档搜索和 MCP 语法检查等能力。

本文将带你完成：

• ✅ 安装 devecocli 并验证版本
• ✅ 了解全部 11 个子命令的功能定位
• ✅ 理解 ToolProvider 自动发现机制
• ✅ 掌握三个关键环境变量

环境准备

项目	版本
DevEco Studio	≥ 6.1.0（推荐 6.1.1 Release）
Node.js	≥ 18（推荐 ≥ 22）
操作系统	macOS / Windows

说明: devecocli 依赖 DevEco Studio 自带的工具链，必须先安装 DevEco Studio。devecocli 会自动发现本机安装路径，无需手动配置 PATH / DEVECO_SDK_HOME / JAVA_HOME。

核心实现

Step 1: 安装与验证

目标: 全局安装 devecocli 并确认可用

# 全局安装
npm install -g @deveco-test/deveco-cli@latest

# 验证版本
devecocli --version
# 输出: 0.4.0

安装成功后，devecocli 命令即可在任意终端使用。

Step 2: 11 个子命令总览

目标: 了解每个命令的功能定位与后续详解篇

devecocli --help

命令	一句话功能	详解篇
create	从模板脚手架新建 HarmonyOS 项目	第 2 篇
build	三步流水线：依赖安装 → 配置同步 → 编译打包	第 3 篇
run	构建 + 安装 + 启动，一键部署到设备	第 4 篇
device	查看连接的真机与运行中的模拟器	第 5 篇
emulator	模拟器实例、系统镜像、虚拟设备、许可证全生命周期	第 6 篇
log	获取 hilog / 崩溃日志，支持 7 种过滤维度	第 7 篇
docs	ripgrep 驱动的本地 HarmonyOS 文档全文搜索	第 8 篇
init	安装 Skill 或配置 MCP 到 AI Agent	第 9 篇
skills	管理 HarmonyOS Skills 市场	第 9 篇
serve	启动 MCP 语法检查服务器	第 10 篇
update	自更新到最新版本	本文

Step 3: ToolProvider 自动发现

目标: 理解 devecocli 如何零配置找到 DevEco Studio

devecocli 启动时，ToolProvider 会自动定位 DevEco Studio 安装路径：

平台	发现策略
macOS	扫描 ~/Applications 和 /Applications，匹配 *DevEco*.app
Windows	读注册表 HKLM\...\DevEco Studio，回退 C:\Program Files\Huawei\DevEco Studio
Linux	暂不支持

找到 DevEco Studio 后，ToolProvider.resolve() 一次性解析全部工具链路径：

ToolProvider.resolve() → {
  nodePath,       // DevEco 自带 Node.js
  ohpmJsPath,     // ohpm 包管理器
  hvigorJsPath,   // hvigor 构建系统
  javaPath,       // JBR (JetBrains Runtime)
  hdcPath,        // hdc 设备连接器
  emulatorPath,   // 模拟器
  sdkPath,        // HarmonyOS SDK
}

说明: 所有工具调用都使用 DevEco 自带的 Node.js 和 JBR，不污染系统环境。

Step 4: 版本检查与环境变量

目标: 掌握三个关键环境变量

devecocli 启动时会检查 DevEco Studio 版本是否 ≥ 6.1.0，不满足则报错退出。

环境变量	作用	示例
DEVECO_CLI_SKIP_VERSION_CHECK=1	跳过 DevEco Studio 版本检查	CI 环境中版本检测异常时使用
DEVECO_CLI_DEBUG=1	打印所有底层命令行（node/ohpm/hvigor/hdc/emulator）	调试构建、运行等问题
HTTP_PROXY / HTTPS_PROXY	HTTP 代理（通过 global-agent 自动生效）	企业内网代理环境

global-agent 在 cli.ts 入口处 bootstrap，所有 HTTP 请求（Skills API、npm 更新等）自动走代理，无需额外配置。

Step 5: 自更新

目标: 使用 devecocli update 保持最新

devecocli update

内部执行 npm install -g @deveco-test/deveco-cli@latest，需要网络和全局安装权限。

效果展示

• devecocli --version 确认安装成功
• devecocli --help 展示 11 个子命令
• ToolProvider 自动发现 DevEco Studio，零配置
• 三个环境变量覆盖代理、调试、版本检查场景

关键代码解读

cli.ts —— 入口与命令注册

// src/cli.ts (简化)
process.env.GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE = '';
import { bootstrap } from 'global-agent';
bootstrap();  // 代理支持

import { program } from 'commander';
// ... 导入 11 个命令

program
  .name('devecocli')
  .description('HarmonyOS application development command line tool')
  .version(process.env.npm_package_version || '0.1.0');

program.addCommand(buildCommand);
program.addCommand(runCommand);
// ... 注册其余 9 个命令

// 版本检查（可跳过）
if (!process.env.DEVECO_CLI_SKIP_VERSION_CHECK) {
  ToolProvider.checkVersion();
}

program.parse();

ToolProvider.checkVersion()

// src/utils/tool-provider.ts (简化)
static checkVersion(): void {
  const devEcoPath = this.getDevEcoPath();
  // macOS: 读 Contents/Info.plist → Contents/product-info.json
  // Windows: 读 product-info.json
  const version = this.readVersion(devEcoPath);
  if (semver.lt(version, '6.1.0')) {
    throw new Error(`DevEco Studio ${version} is below minimum 6.1.0`);
  }
}

总结

1. 一条命令安装：npm install -g @deveco-test/deveco-cli@latest，全局可用
2. 11 个子命令覆盖 HarmonyOS 开发全流程：create → build → run → debug → docs → AI 集成
3. ToolProvider 零配置发现：macOS 扫描 Applications，Windows 读注册表，自动解析全部工具链路径
4. 三个环境变量：SKIP_VERSION_CHECK（CI 用）、DEBUG（调试用）、HTTP_PROXY（代理用）
5. devecocli update 自更新，保持 CLI 始终最新

下篇预告

第 2 篇: 项目脚手架 create —— 深入 devecocli create 的模板渲染机制、占位符替换规则、API Level 自动适配与完整性校验。