项目：Vue 3 + uni-app 3.0 App，编译目标 HarmonyOS App环境：HBuilderX 5.x + DevEco Studio 5.0 + 鸿蒙真机自动化脚本：dev-harmony.bat（Windows）
一、环境准备
最低版本要求
关键依赖（package.json）
{ ”@dcloudio/uni-app-harmony”: ”3.0.0-5010520260709002”, ”@dcloudio/uni-mp-harmony”: ”3.0.0-5010520260709002”, ”@dcloudio/uni-uts-v1”: ”^3.0.0-4080420251103001”}
所有 dcloudio 包需统一版本号，避免编译冲突。
二、首次初始化：生成原生壳工程
首次运行前，需用 HBuilderX 生成鸿蒙原生壳工程：壳工程位于 dist/dev/app-harmony/，包含鸿蒙原生代码（AppScope、entry 模块等）。
三、一键构建流程（dev-harmony.bat）
项目提供了 dev-harmony.bat 脚本，自动完成从源码编译到 DevEco Studio 打开的全流程。用法
开发模式（debug 签名）dev-harmony.bat# 发布模式（release 签名，用于 AppGallery 上架）dev-harmony.bat --release
完整流程（3 大步 + 子步骤）
Step 1: uni build -p app-harmony ← 编译 uni-app 注入壳工程Step 1.4: 注入鸿蒙权限声明 ← 震动等权限 uni build 不会自动写入Step 1.5: 注入 App 图标 ← 从 app-icons/{repo}/ 复制 foreground/background/startIconStep 1.6: 设置 bundleName + 版本号 ← 根据 repo.config.json 重写 AppScope/app.json5Step 1.7: 重置调试签名配置 ← 删除旧证书，DevEco 打开后自动弹出签名修复Step 2: 注入 local.properties / release 签名 ← SDK 路径 + AppGallery 发布签名Step 3: 启动 DevEco Studio ← 打开壳工程，点击 Run 即可安装到真机
脚本关键逻辑
自动识别仓库：dev-harmony.bat 从 src/baseUrl.js 读取 REPO_CODE（jwdev 或 jwsgt），自动对应不同的：bundleName：cn.juanwang.dev / cn.juanwang.sgtApp 图标目录：app-icons/jwdev/ / app-icons/jwsgt/签名配置目录：harmony-configs/jwdev/signing/ / harmony-configs/jwsgt/signing/版本号自动计算：从 package.json 读取 version，自动计算 versionCode：versionCode = major × 10000 + minor × 100 + patch
例如：版本 1.2.3 → versionCode 10203
四、关键配置详解
4.1 manifest.json — 鸿蒙平台配置
”app-harmony”: { ”distribute”: { ”icons”: { ”foreground”: ”../app-icons/jwdev/foreground.png”, ”background”: ”../app-icons/jwdev/background.png” } }}
注意：app-harmony.distribute 支持的字段非常有限（基本只有 icons），权限声明不能通过 manifest.json 配置，需构建后注入。
4.2 vite.config.js — IIFE 编译适配
鸿蒙不支持代码分割（动态 chunk），需在 vite.config.js 中添加 harmony-fix-iife 插件：{ name: 'harmony-fix-iife', enforce: 'post', configResolved(config) { const isHarmony = process.env.UNI_PLATFORM === 'app-harmony' || process.env.UNI_PLATFORM === 'mp-harmony' if (isHarmony) { config.build.rollupOptions.output.inlineDynamicImports = true delete config.build.rollupOptions.output.manualChunks } }}
作用：检测到鸿蒙平台时，强制将所有动态 import 内联为单一 IIFE 文件。4.3 repo.config.json — 多仓库配置
{ ”jwdev”: { ”harmonyBundleName”: ”cn.juanwang.dev”, ”agcProjectId”: ”...”, ”agcClientId”: ”...” }, ”jwsgt”: { ”harmonyBundleName”: ”cn.juanwang.sgt”, ”agcProjectId”: ”...”, ”agcClientId”: ”...” }}
4.4 权限注入 — 构建后脚本
uni build 生成 module.json5 后，运行 scripts/inject-harmony-permissions.js 注入需要的权限：// 核心逻辑：读取 module.json5 → push 权限 → 写回const REQUIRED_PERMISSIONS = [ { name: 'ohos.permission.VIBRATE' }]// 去重后 push 到 json.module.requestPermissions
五、Vue 代码适配要点
5.1 getSystemInfoSync — 鸿蒙端需条件编译
鸿蒙运行时的桥接层对 uni.getSystemInfoSync() 存在兼容性问题，需用条件编译替代：// #ifndef APP-HARMONYconst systemInfo = uni.getSystemInfoSync()statusBarHeight.value = systemInfo.statusBarHeight || 0// #endif// #ifdef APP-HARMONYstatusBarHeight.value = 44 // 鸿蒙默认状态栏高度tabBarHeight.value = 65 // 鸿蒙默认 tabBar 高度// #endif
鸿蒙设备状态栏高度基本统一为 44px，硬编码默认值即可。
5.2 条件编译 — 平台差异隔离
// #ifdef APP-HARMONY// 鸿蒙专属逻辑（如 deviceAutoLogin）// #endif// #ifndef APP-HARMONY// 其他平台逻辑// #endif
5.3 大体积依赖 — 按平台按需加载
markdown-it、katex、highlight.js 等重型库会导致鸿蒙 bundle 过大（1MB+），用条件编译隔离：<!-- #ifndef APP-HARMONY -->import MarkdownIt from 'markdown-it'import katex from 'katex'<!-- #endif -->
鸿蒙端改为简化纯文本渲染，避免触发桥接层数据量上限。
六、签名与安装
6.1 调试签名（Debug）
脚本会自动重置调试签名配置，DevEco Studio 打开后会弹出签名修复向导，按提示操作即可：6.2 发布签名（Release）
harmony-configs/└── jwdev/ └── signing/ ├── xxx.p12 ← 发布证书 ├── xxx.cer ← 证书文件 └── xxx.p7b ← Profile 文件
并在 harmony-configs/ 下创建 build-profile.release.jwdev.json5，引用签名文件路径。签名敏感文件（.p12/.cer/.p7b）已在 .gitignore 中排除，不会提交到 Git。
七、完整构建链路总结
源码 (src/) │ ├─ prebuild-manifest.js ──→ 模板替换（{{repo.xxx}} → 实际值） │ ├─ uni build -p app-harmony │ ├─ vite-plugin-manifest.js ──→ manifest.json 注入 │ ├─ harmony-fix-iife ──→ inlineDynamicImports + 删除 manualChunks │ └─ 输出 ──→ dist/dev/app-harmony/ （原生壳工程） │ ├─ inject-harmony-permissions.js ──→ module.json5 权限注入 ├─ 图标复制 (app-icons/ → AppScope/resources/) ├─ app.json5 重写 (bundleName + version) ├─ build-profile.json5 重置 (签名清理) │ ├─ local.properties 注入 (SDK 路径) │ └─ DevEco Studio 打开 → Build → Run → 真机
八、要点总结
- 首次用 HBuilderX 生成壳工程，后续全部用 `dev-harmony.bat` 自动化构建
- 鸿蒙**不支持**代码分割，vite.config.js 必须设置 `inlineDynamicImports: true`
- `manifest.json` 中 `app-harmony.distribute` 有效字段极少，权限需构建后脚本注入
- `uni.getSystemInfoSync()` 在鸿蒙存在桥接兼容问题，用条件编译 + 硬编码默认值替代
- 重型第三方库（markdown-it 等）在鸿蒙端按需加载或降级为轻量替代
- 多仓库（jwdev/jwsgt）通过 `repo.config.json` 切换 bundleName、图标、签名配置
- 调试签名用 DevEco 自动生成，发布签名需从 AppGallery Connect 手动下载配置
10个月宝宝每天需要喝多少奶粉？