Build & Deploy（构建与部署）

构建系统：hvigor（HarmonyOS 官方构建工具），配置见 hvigor/、hvigorfile.ts、build-profile.json5。

构建 / 运行 Build & Run

主路径：DevEco Studio → Build / Run（GUI）。首次打开自动同步依赖。
命令行（hvigorw wrapper 由 DevEco 首次同步生成）：

# 构建 debug HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

# 构建 release HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=release

产物通常在 entry/build/default/outputs/ 下（default 为 product 名）。

多模块构建 Multi-module Build

本工程为「单 HAP + 多 HAR」：entry/（HAP）+ common/（HAR）+ uikit/（HAR）。

HAR（common/uikit）作为 entry 的依赖，构建 entry 时会自动先编译依赖的 HAR，正常开发只需构建 entry。
任务类型：HAP 用 assembleHap，HAR 用 assembleHar。
构建整个工程用 --mode project（按依赖顺序构建全部模块）；构建单个模块用 --mode module。
模块注册：根 build-profile.json5 的 modules；模块间依赖：各自 oh-package.json5 的 dependencies 用 file:../xxx 声明。

HAR 配置要点（易错）：

module.json5 的 type 必须是 har（不是 shared——shared 对应 HSP，会要求 hspTasks）。
oh-package.json5 的 main: "Index.ets" 指向模块根目录的 Index.ets（该文件 export * from './src/main/ets/Index.ets' 转发公共 API）。
权限（如 ohos.permission.INTERNET）只声明在 HAP 的 module.json5 的 requestPermissions；HAR 不声明权限。

签名 Signing

现状与原则

build-profile.json5 里 signingConfigs 在仓库中必须保持为空 []（products[].signingConfig 仍引用 "default"）——签名是机器相关的，禁止入库。
真正的密钥物料（.p12 / .cer / .p7b）由 DevEco 生成在 ~/.ohos/config/ 下，本来就在仓库外；build-profile.json5 里只有「文件路径 + 加密后的密码」，但同样属敏感信息，不得提交。

本地配置签名（不入库）

要跑真机/模拟器需先配置签名：

DevEco Studio → File → Project Structure → Signing Configs → 勾选自动签名（登录华为账号）。
或手动配置 .p12 + .cer / .p7b。

DevEco 自动签名会把凭据写进 build-profile.json5，这属于本地未提交状态，不要 git add 它。

防泄露：pre-commit 钩子

仓库内置了 pre-commit 钩子 scripts/git-hooks/pre-commit：只要暂存区的 build-profile.json5 出现 keyPassword / storePassword / certpath 等签名字段，就拒绝提交。

每个克隆启用一次：

git config core.hooksPath scripts/git-hooks

验证：临时在 build-profile.json5 里塞一个 "keyPassword" 再 git add build-profile.json5 && git commit，应被拦截。

确需临时绕过时用 git commit --no-verify（仅应急，不建议）。

彻底外部化（可选）

若想连本地也不出现凭据，可走「动态配置签名」：用 hvigorfile.ts 从 gitignore 的本地文件或环境变量读取签名注入，让 build-profile.json5 始终保持空。参考华为官方《基于动态配置签名的多人协同开发应用签名解决方案》。

build-profile.json5 的签名部分属于 Agent 禁止修改 范围（见 AGENTS.md）。

产品与构建模式 Products & Build Modes

products：当前只有一个 default（targetSdkVersion 6.0.2(22)，runtimeOS: HarmonyOS）。
buildModeSet：debug / release。

部署 Deploy

配置签名（见上）。
连接真机（开启开发者模式 + USB 调试）或启动模拟器。
DevEco Studio 选择设备 → Run。

环境环境变量 / 本地配置

local.properties：本机 SDK 路径等，已 gitignore，勿提交，勿写密钥。
依赖锁：oh-package-lock.json5，提交以固定依赖版本。

4.0 KiB Raw Blame History Unescape Escape