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 跑在鸿蒙上，需要解决几个核心问题：

WebView 适配：鸿蒙自带的 WebView 能力需要被 Tauri 的 WRY（WebView Runtime）层封装
窗口管理：鸿蒙的窗口生命周期与桌面系统不同
Rust FFI 绑定：鸿蒙侧用 ArkTS (TypeScript) 开发，需要通过 NAPI 与 Rust 层通信
构建工具链 ：鸿蒙使用自家的 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 命令：

rust 复制代码

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

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

typescript 复制代码

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` 工具链

步骤一：安装工具链

bash 复制代码

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

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

步骤二：安装依赖

bash 复制代码

# 前端依赖
pnpm install

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

步骤三：构建鸿蒙 HAP

bash 复制代码

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 等效工具）执行完整的构建流程：

BuildNativeWithCmake --- 编译 C/C++ 原生代码
BuildNativeWithNinja --- 用 Ninja 编译 Rust 产物相关的 native 依赖
CompileArkTS --- 编译 ArkTS 源码到字节码
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 生命周期的转发：

typescript 复制代码

// 鸿蒙侧 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 替换为鸿蒙适配版本：

toml 复制代码

[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 动态库：

bash 复制代码

# 确认 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 中配置：

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 自动生成

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

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

bash 复制代码

# 使用鸿蒙 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 一键构建

未来方向 🔭

Tauri 插件生态 --- Tauri 2.0 的插件系统（tauri-plugin-*）需要逐个适配鸿蒙 API
原生能力封装 --- 文件系统、剪贴板、通知等系统 API 的鸿蒙实现
上层框架集成 --- 用 Tauri 封装鸿蒙的分布式能力（Distributed Data Management、Distributed File System）
官方支持 --- 期待 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/