DevEco CLI 与 IDE 构建环境差异排查与 CI 化打包

前言

在鸿蒙应用开发中，「DevEco Studio 里能编、命令行 hvigorw 一跑就报 Module not found / 类型不匹配 / 重复符号」是一类高频问题。本质不是命令写错，而是 IDE 与 CLI 两条构建链路解析出的依赖图、工具链版本、构建模式不一致。本文把这类问题的排查方法系统化，并给出一套可在 CI / 流水线稳定复用的打包脚本。

问题描述

典型现象：

• hvigorw assembleHap --mode release --product default 报 Module not found，提示找不到本地 HAR；
• 或报类型不匹配、重复符号定义，但 IDE 的 Debug/Preview 一切正常；
• 报错只在命令行触发，图形化 IDE 无问题。

核心困惑在于：同一份工程、同一台机器，为什么两种入口结果不同？

细节解析

1. IDE 替你做了三件 CLI 不会做的事

• 自动执行 ohpm install 把依赖装进 oh_modules；
• 自动执行 hvigorw --sync 重建模块间依赖关系；
• 自动注入内置 JDK / Node / OHPM / Hvigor 的工具链路径。

命令行环境是「零上下文」的，这些都要你自己做。

2. 命令参数格式
--mode 的合法值是 module / project（构建范围），不是 release；Release 模式用 -p buildMode=release 指定，产品用 -p product=default：

hvigorw assembleHap --mode module -p product=default -p buildMode=release --no-daemon

3. Release 比 Debug 多了硬性检查
Release 会启用 ArkTS 更严格校验与 AOT，并默认开启 useNormalizedOHMUrl（字节码 HAR）。本地 HAR 只声明在工程级 oh-package.json5 却没在引用它的模块级声明时，Debug 可能宽松通过、Release 直接 Failed to get a resolved OhmUrl。

4. 大小写敏感
Linux 构建机文件系统大小写敏感，Mac/Win 不敏感，所以 IDE 过、CLI 挂。开 caseSensitiveCheck 让 IDE 阶段就暴露。

示例代码

可落地的 CI 打包脚本（与 IDE 同一套工具链）：

#!/bin/bash
set -e
# 1. 对齐工具链：用 IDE 自带的 node/ohpm/sdk
export PATH="$DEVECO_STUDIO/contents/tools/node/bin:$DEVECO_STUDIO/contents/tools/ohpm/bin:$PATH"
export DEVECO_SDK_HOME="$DEVECO_STUDIO/sdk"
export JAVA_HOME="$DEVECO_STUDIO/jbr"

cd "$PROJECT_ROOT"
# 2. 清缓存 + 同步依赖（CLI 必须显式做）
./hvigorw clean --no-daemon
./hvigorw --sync
# 3. 真正构建（模块级 + 指定 target + release）
./hvigorw assembleHap --mode module -p product=default -p module=entry@default \
  -p buildMode=release --no-daemon --stacktrace --info

build-profile.json5 中开启大小写检查：

{
  "products": [{
    "name": "default",
    "buildOption": { "strictMode": { "caseSensitiveCheck": true } }
  }]
}

模块级补全本地 HAR 声明：

// entry/oh-package.json5
{ "dependencies": { "@ohos/lib": "file:../library" } }

拿到首个真实错误：Release 报「类型不匹配」往往是前置依赖解析失败的连锁反应，用 --stacktrace --info 看第一条失败点。

总结

「IDE 正常、CLI 报错」的排查铁三角：先 --sync 再构建、CLI 与 IDE 工具链对齐、本地 HAR 在模块级 oh-package.json5 声明、开 caseSensitiveCheck。把这四点固化进 CI 脚本，就能让命令行打包和 IDE 行为完全一致，也方便接入流水线做自动化出包。