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

---

引言

devecocli build 是 HarmonyOS 项目从源码到安装包的核心环节。它不是简单调用一个编译命令，而是三步流水线：依赖安装 → 配置同步 → 编译打包。每一步都有其不可跳过的作用，理解这个流水线是排查构建问题的基础。

本文将带你掌握：

• ✅ 三步流水线每一步的作用与输出
• ✅ HSP 依赖解析与 @target 传播机制
• ✅ 多模块构建与产物类型
• ✅ 构建清理与构建锁

核心实现

Step 1: 三步流水线

目标: 理解 devecocli build 的三个阶段

devecocli build --help

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────────────┐
│  Step 1:             │    │  Step 2:             │    │  Step 3:                 │
│  ohpm install --all  │ →  │  hvigor --sync      │ →  │  hvigor assemble*       │
│  安装所有依赖包       │    │  同步构建配置        │    │  编译 ArkTS/C/C++ 并打包 │
└─────────────────────┘    └─────────────────────┘    └──────────────────────────┘

Step 1: ohpm install --all

• 作用: 安装 oh-package.json5 中声明的所有依赖（包括 dependencies 和 devDependencies）
• 执行: node ohpm-cli.js install --all
• 输出: 依赖包下载到 oh_modules/ 目录
• 何时可跳过: 如果 oh_modules/ 已存在且依赖未变更，此步会快速完成（ohpm 内部缓存）

Step 2: hvigor --sync

• 作用: 同步构建配置，根据 build-profile.json5 生成模块级的 hvigor-config.json5
• 执行: node hvigorw.js --sync
• 输出: 更新各模块的构建配置文件
• 为何需要: HarmonyOS 项目支持多 product、多 target，--sync 确保构建配置与项目配置一致

Step 3: hvigor assemble*

• 作用: 编译 ArkTS / C / C++ 源码，打包为安装包
• 执行: 根据目标产物类型选择不同的 assemble 命令
• 输出: 产物位于 entry/build/default/outputs/default/

目标	hvigor 命令	产物
单模块 HAP	assembleHap	entry-default-signed.hap
单模块 HSP	assembleHsp	feature-default-signed.hsp
整个 product	assembleApp	entry-default-signed.app

Step 2: HSP 依赖解析与 @target 传播

目标: 理解多模块项目中 HSP 依赖的构建顺序

HarmonyOS 的 shared 模块（HSP）是动态共享库，其他模块可能在运行时依赖它。devecocli build 会自动解析 HSP 依赖关系：

entry (HAP) ──依赖──→ feature (HSP) ──依赖──→ common (HSP)

构建顺序：common → feature → entry（先构建被依赖的模块）。

@target 传播：当使用 --modules entry@default 指定 target 时，devecocli build 会自动将 @default 传播到 entry 的 HSP 依赖上，确保所有模块使用相同的 target 构建。

# 构建 entry 模块及其 HSP 依赖，全部使用 default target
devecocli build --modules entry@default

Step 3: 多模块构建选项

目标: 掌握不同构建场景的命令用法

# 默认构建（debug 模式，default product，自动检测模块）
devecocli build

# 构建指定模块
devecocli build --modules entry feature

# 构建模块的特定 target
devecocli build --modules entry@default feature@default

# 构建整个 product bundle（生成 .app 文件）
devecocli build --product default

# Release 模式构建
devecocli build --build-mode release

# 指定 product + release
devecocli build --product oversea --build-mode release

产物类型与模块类型的关系：

模块类型 (module.json5 中的 type)	产物格式	可独立运行
entry	.hap	✅ 是
feature	.hap	❌ 需入口模块加载
shared	.hsp	❌ 运行时动态链接
har	.har	❌ 编译时静态链接
整个 product	.app	✅ 全量安装包

注意: 当项目有多个 entry 模块时，必须通过 --modules 指定构建目标，否则报错。

Step 4: 构建清理

目标: 清理构建产物与守护进程

devecocli build clean

该命令执行两步：

1. hvigor clean —— 删除所有模块的 build/ 目录
2. hvigor --stop-daemon —— 停止 hvigor 守护进程

使用场景：

• 构建缓存导致奇怪的错误 → build clean 后重新构建
• 切换构建模式后产物未更新 → build clean
• CI/CD 流水线中确保干净构建 → build clean && build

Step 5: 构建锁机制

目标: 理解并发构建的安全保障

devecocli 使用 proper-lockfile 实现项目级文件锁：

// src/utils/build-lock.ts (简化)
import lockfile from 'proper-lockfile';

export class BuildLock {
  static async acquire(projectPath: string): Promise<() => void> {
    const release = await lockfile.lock(projectPath, {
      stale: 30000,     // 30s 无更新认为锁过期
      retries: { retries: 5, minTimeout: 1000 },
    });
    return release;     // 调用 release() 释放锁
  }
}

配置	值	说明
stale	30000ms	锁 30 秒无更新自动过期（防死锁）
retries	5 次	获取锁失败时最多重试 5 次
minTimeout	1000ms	重试最小间隔

保护场景：

• CI/CD 多 Job 并发构建同一项目
• 多个终端窗口同时 devecocli build
• AI Agent 并发调用构建命令

效果展示

• 三步流水线：ohpm install → hvigor --sync → hvigor assembleHap

• HSP 依赖自动解析，构建顺序正确

• build clean 清理缓存，--build-mode release 生产构建
  

• 构建锁保证并发安全

关键代码解读

OhpmAdapter

// src/utils/ohpm-adapter.ts (简化)
export class OhpmAdapter {
  static async install(cwd: string): Promise<void> {
    await execa(toolProvider.nodePath, [toolProvider.ohpmJsPath, 'install', '--all'], {
      cwd,
      env: { PATH: jbrBinPath, DEVECO_SDK_HOME: sdkPath },
    });
  }
}

HvigorAdapter

// src/utils/hvigor-adapter.ts (简化)
export class HvigorAdapter {
  static async sync(cwd: string): Promise<void>;
  static async assembleHap(cwd: string, options: BuildOptions): Promise<void>;
  static async assembleApp(cwd: string, options: BuildOptions): Promise<void>;
  static async clean(cwd: string): Promise<void>;
  static async stopDaemon(cwd: string): Promise<void>;
}

Project.collectNonHarDependentModuleList()

// src/utils/project.ts (简化)
// 收集非 HAR 依赖的模块列表（HSP 依赖解析）
static collectNonHarDependentModuleList(
  moduleName: string,
  profile: BuildProfile
): string[];

常见问题排查

问题	原因	解决方案
Product <x> not found	build-profile.json5 中无此 product	检查 products 配置
Multiple entry modules	项目有多个入口模块	使用 --modules 指定
构建卡住不输出	hvigor daemon 锁死	devecocli build clean
HSP 安装顺序错误	依赖解析遗漏	检查 oh-package.json5 依赖声明
ohpm install 失败	依赖包不存在或版本不兼容	检查 oh-package.json5 依赖版本

总结

1. 三步流水线：ohpm install --all → hvigor --sync → hvigor assemble*，每步不可跳过
2. HSP 依赖解析：自动分析依赖图，按正确顺序构建，@target 自动传播
3. 产物类型由模块类型决定：entry/feature → HAP，shared → HSP，har → HAR，product → APP
4. build clean = hvigor clean + hvigor --stop-daemon，清理构建缓存与守护进程
5. 构建锁：proper-lockfile 项目级互斥，30s 自动过期，5 次重试

下篇预告

第 4 篇: 全链路部署 run —— 深入 devecocli run 的构建 → 安装 → 启动全流程，掌握自动模块选择、HSP 安装顺序、–skip-build / --uninstall 场景。