移动端 App 总览

探字星球基于同一套 web/ 源码，通过原生 WebView 套壳方式打包为安卓与鸿蒙两个移动端 App。 本文档介绍「单源同步」架构、两款 App 的技术选型对比，以及从源码到安装包的一键构建流程。

---

一、单源同步架构

移动端 App 不复制源码，而是复用 web/ 作为唯一源码与数据源。构建产物经脚本同步到两个原生壳工程：

web/  ←── 唯一源码 + 数据（Vue3 + TS + 500 汉字 JSON/音频/SVG）
 │
 ├── pnpm build (vite.config.ts)         →  web/dist        →  Android (Capacitor)
 └── pnpm build:harmony (vite.harmony.config.ts)  →  web/dist-harmony  →  HarmonyOS (ArkWeb)

双构建路径说明：

构建配置	产出目录	格式	用途
vite.config.ts	web/dist/	ES module + 动态分包	浏览器、安卓（Capacitor）
vite.harmony.config.ts	web/dist-harmony/	IIFE 单文件（inlineDynamicImports）	鸿蒙（ArkWeb 无法执行 import() 动态导入）

为什么鸿蒙需要单独构建？ Vite 默认构建产出的 JS 包含大量 import() 动态分包调用（如 25 个路由分包），安卓 Capacitor 的 WebView 能正常执行 ES module，但鸿蒙 ArkWeb 在 onInterceptRequest 拦截模式下无法解析动态导入 → 白屏。因此使用 format: 'iife' + inlineDynamicImports 产出单文件包，所有代码内联到 assets/app.js（0 个 import() 调用）。

核心原则：

• 源码永不复制：android/、harmony/ 只含原生壳（Kotlin / ArkTS / Gradle / Manifest / 配置）。
• 数据只改一处：web/ 更新 JSON/音频/SVG 后，一键重新构建 + 同步即可。
• 产物不提交：web/dist、web/dist-harmony、assets/public/、rawfile/ 均由各 .gitignore 排除。

---

二、两款 App 技术选型对比

维度	安卓（Android）	鸿蒙（HarmonyOS）
套壳技术	Capacitor（跨平台框架）	原生 ArkWeb（Web 组件 + onInterceptRequest）
原生语言	Java（BridgeActivity）	ArkTS（Stage 模型）
工程目录	android/	harmony/
资源加载	WebViewAssetLoader 虚拟域名（Capacitor 内置）	onInterceptRequest 拦截 rawfile 请求 + MIME 映射
加载入口	assets/public/index.html	rawfile/index.html
构建命令（根目录）	pnpm apk:debug	pnpm hap:sync + DevEco Studio 构建
安装包产物	.apk	.hap

两者共享同一套 web/dist，业务逻辑、数据、UI 完全一致；差异仅在于原生壳与资源加载方式。

---

三、根目录一键命令

源码：根 package.json scripts

命令	作用	说明
pnpm build:web	构建 web 产物（默认）	等价 cd web && pnpm build，产出 web/dist（ES module）
pnpm build:harmony	构建 web 产物（鸿蒙专用）	cd web && npx vite build --config vite.harmony.config.ts，产出 web/dist-harmony（IIFE 单文件）
pnpm sync:android	同步安卓	等价 cap sync android，将 web/dist 拷入 assets/public/
pnpm sync:harmony	同步鸿蒙	运行 scripts/sync-harmony.mjs，将 web/dist-harmony 拷入 rawfile/
pnpm apk:debug	一键生成 APK	build:web → sync:android → Gradle assembleDebug
pnpm hap:sync	同步鸿蒙产物	build:harmony → sync:harmony（供 DevEco Studio 构建 .hap）

---

四、阅读路径

阶段	文档	阅读目标
① 安卓	安卓 App 创建指南	掌握 Capacitor 壳的配置、构建流程与排错
② 鸿蒙	鸿蒙 App 创建指南	掌握 ArkWeb 套壳的资源拦截、构建配置与签名

---

五、快速导航

• 只想生成安卓 APK：直接看 安卓 App 创建指南。
• 直接下载现成 APK：官方百度网盘分享（提取码 ssvh）：https://pan.baidu.com/s/1kJLYUOro8-AZVwvohMQUTw?pwd=ssvh
• 想生成鸿蒙 .hap：直接看 鸿蒙 App 创建指南。
• 了解整体链路：先阅读本文档「单源同步架构」一节。