Tauri + 鸿蒙PC：在鸿蒙系统上运行跨平台桌面应用

作者： 本文记录了一次完整的 Tauri 应用在 鸿蒙PC 上的构建实践。

时间： 2025年 5月

---

一、什么是 Tauri？

Tauri 是一个轻量级的跨平台桌面应用框架。它允许开发者使用前端技术（HTML / CSS / JavaScript）构建 UI 界面，同时用 Rust 语言编写底层业务逻辑，打包为原生的桌面应用。

Tauri vs Electron

对比维度	Tauri	Electron
运行时	OS 原生 WebView	捆绑 Chromium
安装包大小	几 MB	几十 ~ 几百 MB
内存占用	低	高
后端语言	Rust	Node.js
安全性	强（默认 CSP）	中等
启动速度	快	慢

核心优势：Tauri 不捆绑浏览器内核，而是利用操作系统自带的 WebView（macOS 上的 WKWebView、Windows 上的 WebView2、Linux 上的 WebKitGTK），因此安装包极小、资源占用极低。

二、Tauri 2.0 架构

Tauri 2.0（当前版本 2.x）引入了更灵活的架构：

┌──────────────────────────────────┐
│        前端 (Vue / React / Svelte)   │  ← Vite 构建
├──────────────────────────────────┤
│    Tauri IPC (invoke / event)      │  ← Rust ↔ JS 通信
├──────────────────────────────────┤
│         Tauri Core (Rust)          │  ← 应用逻辑
├──────────────────────────────────┤
│         Tauri Runtime / WRY        │  ← 窗口管理 & WebView
├──────────────────────────────────┤
│       OS 原生 WebView              │  ← 系统提供
└──────────────────────────────────┘

• 前端层：任意前端框架（Vue、React、Svelte、Solid 等），通过 Vite 构建
• IPC 层：通过 @tauri-apps/api 的 invoke 调用 Rust 端命令
• Rust Core：管理窗口、菜单、系统托盘、文件系统、Shell 等能力
• Tauri Runtime / WRY：窗口与 WebView 的抽象层

三、OpenHarmony 支持：从不可能到可能

OpenHarmony（开源鸿蒙）是华为贡献的开源操作系统，支持手机、平板、IoT 设备等多种形态。HarmonyOS NEXT（鸿蒙星河版）则基于 OpenHarmony，不再兼容 Android 应用。

要让 Tauri 跑在鸿蒙上，需要解决几个核心问题：

1. WebView 适配：鸿蒙自带的 WebView 能力需要被 Tauri 的 WRY（WebView Runtime）层封装
2. 窗口管理：鸿蒙的窗口生命周期与桌面系统不同
3. Rust FFI 绑定：鸿蒙侧用 ArkTS (TypeScript) 开发，需要通过 NAPI 与 Rust 层通信
4. 构建工具链：鸿蒙使用自家的 DevEco Studio 和 hvigor 构建系统

社区贡献

感谢 richerfu 和 harmony-contrib 的开源贡献！

关键上游 fork：

仓库	作用
richerfu/tauri (feat/open-harmony 分支)	Tauri Core 的鸿蒙适配
richerfu/wry	WebView Runtime 的鸿蒙适配
richerfu/tao	窗口创建的鸿蒙适配
harmony-contrib/openharmony-ability	Rust ↔ ArkTS 生命周期绑定
ohrs	鸿蒙构建辅助工具

四、项目结构

本 demo 项目的完整目录结构：

tauri-demo/
├── package.json            # 前端依赖 (Vue + Vite + Tauri CLI)
├── pnpm-lock.yaml
├── src/
│   ├── main.ts             # Vue 入口
│   ├── App.vue             # 主界面
│   ├── assets/
│   └── vite-env.d.ts
├── index.html
├── vite.config.ts
├── tsconfig.json
└── src-tauri/
    ├── Cargo.toml          # Rust 依赖
    ├── tauri.conf.json     # Tauri 配置
    ├── src/
    │   ├── main.rs         # Rust 入口
    │   └── lib.rs          # Tauri 命令定义
    └── gen/
        └── ohos/           # ★ 鸿蒙工程目录 ★
            ├── build-profile.json5
            ├── hvigorfile.ts
            ├── AppScope/
            ├── entry/
            │   ├── build-profile.json5
            │   ├── hvigorfile.ts
            │   ├── oh-package.json5
            │   ├── src/main/ets/   # ArkTS 源码
            │   │   ├── entryability/
            │   │   └── pages/
            │   ├── libs/arm64-v8a/
            │   │   └── libtauri_demo_lib.so  # ★ Rust 编译产物 ★
            └── oh_modules/         # OHPM 依赖

Rust 端命令

在 src-tauri/src/lib.rs 中定义了一个简单的 Tauri 命令：

#[tauri::command]
fn greet(name: &str) -> String {
    format!("Hello, {}! You've been greeted from Rust!", name)
}

前端通过 @tauri-apps/api 调用：

import { invoke } from "@tauri-apps/api/core";
const msg = await invoke("greet", { name: "World" });

五、完整构建过程

环境准备

工具	版本	用途
Rust	≥ 1.77	编译 Tauri Core 和业务代码
Node.js	≥ 22	运行前端构建工具链
pnpm	11.2.2	前端包管理
DevEco Studio (可选)	5.0+	鸿蒙工程构建 & 签名
ohos-sdk	API 12+	鸿蒙 SDK，包含 hvigor 和 native 工具链

步骤一：安装工具链

# 1. 安装 tauri-cli（鸿蒙分支）
cargo install tauri-cli --git https://github.com/tauri-apps/tauri --branch feat/open-harmony

# 2. 安装 ohrs（鸿蒙构建辅助）
cargo install ohrs

步骤二：安装依赖

# 前端依赖
pnpm install

# Rust 依赖（会下载 tauri、wry、tao 等鸿蒙分支的 crate）
cd src-tauri && cargo fetch

步骤三：构建鸿蒙 HAP

cd src-tauri && cargo tauri ohos build

构建过程分三个阶段：

阶段 1：前端构建

$ pnpm build
vue-tsc --noEmit && vite build
✓ 18 modules transformed.
dist/assets/index-yfKK-ms3.css   1.40 kB
dist/assets/index-DV24ggAs.js   63.47 kB
✓ built in 227ms

Vite 将 Vue 源码打包为静态资源，输出到 src-tauri/dist/。

阶段 2：Rust 交叉编译

Compiling tauri-demo v0.1.0
Compiling napi-ohos v1.1.0
...
Finished compiling Rust code

Rust 代码通过 target.*.json 目标描述文件，交叉编译为 ARM64 架构 的动态链接库 (libtauri_demo_lib.so)，输出到鸿蒙工程的 libs/arm64-v8a/ 目录。

阶段 3：鸿蒙 HAP 打包

> hvigor BuildNativeWithCmake...
> hvigor BuildNativeWithNinja...
> hvigor CompileArkTS...
> hvigor PackageHap...
> hvigor BUILD SUCCESSFUL in 5s 313ms

hvigor（鸿蒙的 Gradle 等效工具）执行完整的构建流程：

1. BuildNativeWithCmake — 编译 C/C++ 原生代码
2. BuildNativeWithNinja — 用 Ninja 编译 Rust 产物相关的 native 依赖
3. CompileArkTS — 编译 ArkTS 源码到字节码
4. PackageHap — 打包为 HAP (Harmony Ability Package)

最终产物：

src-tauri/gen/ohos/entry/build/default/outputs/default/
└── entry-default-unsigned.hap   ← 未签名的安装包

常见问题排查

问题	原因	解决办法
hvigor 命令未找到	DevEco Studio / ohos-sdk 未安装或 PATH 未配置	确保 ohos-sdk 已安装，export OHOS_SDK_HOME=/path/to/sdk，并将 hvigor 所在目录加入 PATH
ohpm install 超时	国内网络访问 ohpm registry 不稳定	配置华为云镜像：ohpm config set registry https://repo.huaweicloud.com/repository/ohpm/
Java 相关错误	hvigor 依赖 JDK 17+	安装 JDK 17 并设置 JAVA_HOME
error: failed to run custom build command for napi-ohos	Rust 交叉编译工具链未安装	安装 aarch64-linux-android target：rustup target add aarch64-linux-android
BUILD FAILED 且日志含 sign	签名配置缺失或证书过期	参考上方签名配置章节，重新生成证书

六、技术实现详解

6.1 Rust → ArkTS NAPI 桥接

鸿蒙原生应用使用 ArkTS（基于 TypeScript）编写，而 Tauri 的业务逻辑在 Rust 中。两者通过 NAPI (Native API) 通信：

┌────────────────────┐          ┌─────────────────────┐
│    Rust (lib.rs)   │  NAPI    │   ArkTS (鸿蒙侧)     │
│                    ├─────────►│                      │
│  #[tauri::command] │  ◄──────│  RustAbility.ets     │
│  fn greet()        │  invoke  │                      │
└────────────────────┘          └─────────────────────┘

techpack: @ohos-rs/ability 提供了 RustAbility 基类，自动管理 Rust 生命周期的转发：

// 鸿蒙侧 EntryAbility.ets
import { RustAbility } from '@ohos-rs/ability'

export default class EntryAbility extends RustAbility {
  // RustAbility 自动转发：
  // onCreate → Rust 初始化
  // onWindowStageCreate → 创建 WebView 窗口
  // onForeground / onBackground → 生命周期同步
  // onDestroy → Rust 资源清理
}

6.2 WebView 封装

鸿蒙的 WebView 通过 ohos.web.webview 模块提供，WRY (WebView Runtime) 适配层将其封装为 Tauri 兼容的接口：

功能	鸿蒙 API	Tauri/WRY 抽象
创建窗口	WindowStage.loadContent()	WindowBuilder
加载 URL	WebviewController.loadUrl()	WebView::navigate()
JS 注入	WebviewController.runJavaScript()	WebView::eval()
通信桥	javaScriptProxy()	IPC

6.3 Patch 机制

Cargo.toml 通过 [patch.crates-io] 将上游 crate 替换为鸿蒙适配版本：

[patch.crates-io]
wry = { git = "https://github.com/richerfu/wry", rev = "..." }
tao = { git = "https://github.com/richerfu/tao", branch = "feat-ohos-webview" }
openharmony-ability = { git = "https://github.com/harmony-contrib/openharmony-ability.git" }

这意味着无需修改 Tauri 的上游代码，即可在鸿蒙上构建——这是 Rust 生态中 Patch 依赖机制的经典用法。

七、构建结果验证

构建产物确认

构建成功后，可以看到完整的 HAP 包结构和 Rust 动态库：

# 确认 Rust 动态库被正确打包
$ ls -la src-tauri/gen/ohos/entry/libs/arm64-v8a/
libtauri_demo_lib.so    # ≈ 几 MB

# 确认 HAP 产物
$ ls -la src-tauri/gen/ohos/entry/build/default/outputs/default/
entry-default-unsigned.hap

⚠️ 签名配置

构建过程中如果出现以下警告，说明签名尚未配置：

WARN: Will skip sign 'hos_hap'.
No signingConfigs profile is configured in current project.
If needed, configure the signingConfigs in
  src-tauri/gen/ohos/build-profile.json5

添加签名配置后，cargo tauri ohos build 会自动完成签名，不再需要手动干预。在 src-tauri/gen/ohos/build-profile.json5 中配置：

{
  app: {
    signingConfigs: [
      {
        name: "default",
        type: "HarmonyOS",
        material: {
          certpath: "your.cer",
          keyAlias: "debugKey",
          keyPassword: "...",
          profile: "your.p7b",
          signAlg: "SHA256withECDSA",
          storeFile: "your.p12",
          storePassword: "...",
        },
      },
    ],
  },
}

证书可以通过以下方式获取：

方式一：DevEco Studio 自动生成

1. 用 DevEco Studio 打开 src-tauri/gen/ohos 目录
2. 登录华为开发者账号 → File → Project Structure → Signing Configs
3. 点击 “Automatically generate signature” → 配置会自动写入

方式二：命令行签名（备用）

# 使用鸿蒙 SDK 的 hap-sign-tool
java -jar hap-sign-tool.jar sign-app \
  -keyAlias <alias> \
  -signAlg SHA256withECDSA \
  -keystore <keystore.p12> \
  -inFile entry-default-unsigned.hap \
  -outFile entry-default-signed.hap

手机端运行效果：

鸿蒙PC 运行效果

Tauri 应用在鸿蒙PC（模拟器/真机）上同样可以正常运行，展示完整的 Web 界面和应用交互能力：

从截图可以看出：前端 Vue 页面完整渲染、Rust 后端通过 invoke("greet") 返回数据、IPC 通信链路完全打通。无论是手机形态还是桌面形态，同一套代码无需修改即可运行。

八、总结与展望

已有成果 ✅

• ✅ Tauri 2.0 适配鸿蒙 — 核心 IPC + WebView + 窗口管理已跑通
• ✅ Rust ↔ ArkTS 双向通信 — 通过 NAPI + ohos-rs/ability
• ✅ 交叉编译工具链 — macOS 上可交叉编译 ARM64 的 Rust 动态库
• ✅ 完整的 HAP 打包流程 — cargo tauri ohos build 一键构建

未来方向 🔭

1. Tauri 插件生态 — Tauri 2.0 的插件系统（tauri-plugin-*）需要逐个适配鸿蒙 API
2. 原生能力封装 — 文件系统、剪贴板、通知等系统 API 的鸿蒙实现
3. 上层框架集成 — 用 Tauri 封装鸿蒙的分布式能力（Distributed Data Management、Distributed File System）
4. 官方支持 — 期待 Tauri 官方将鸿蒙纳入正式支持的 target 列表

最后

Tauri + OpenHarmony 的组合，意味着一套 Rust + Vue/React 代码，可以编译到 macOS、Windows、Linux、Android、iOS，以及 OpenHarmony。对于追求代码复用和包体积控制的应用场景（如 IoT 管理工具、轻量级跨平台应用），这是一个极具吸引力的技术路径。

---

本文所述项目代码：https://github.com/richerfu/tauri-demo

Tauri 官方文档：https://tauri.app

OpenHarmony 项目：https://www.openharmony.cn/