Tauri v2的Rust应用 → HarmonyOS（鸿蒙 PC）移植30分钟速成指南

面向新手的实操版，全程照抄命令即可完成移植。

本指南配套已修复的 tauri OHOS 分支 （atomgit.com/qq8864/tauri, feat/open-harmony），

原版分支的已知坑（cargo-mobile2 版本、Windows HAP 装配报错）已在此仓修复。

详细原理与踩坑记录见详细版移植指南。

耗时估算 ：环境 30 分钟 + 改代码 30 分钟 + 编译 20 分钟 + 打包部署 20 分钟。

用一键脚本可压到 30 分钟以内（见第 0 步）。

更多交流学习，欢迎加入开源鸿蒙PC社区 ：https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目 ：https://atomgit.com/OpenHarmonyPCDeveloper

猫哥的博客 ：https://blog.csdn.net/qq8864

第 0 步：一键脚本移植（推荐）

port-to-ohos.ps1 自动完成本指南第 2~6 步的全部机械操作：

环境检查（Rust 目标 / OHOS NDK / DevEco / ohpm / tauri-cli / ohrs）
-InstallToolchain：自动装 gnullvm 工具链、克隆已修复的 tauri OHOS fork、
安装 tauri-cli + ohrs（一次性，约 10 分钟）
项目改造：Cargo.toml（fork 依赖 / napi 桥接 / webpki 证书 / rfd 移到桌面段）、
rust-toolchain.toml、.cargo/config.toml、ohos-clang.cmd、RGBA 图标
cargo tauri ohos init + 交叉编译 .so + 前端同步 rawfile + ohpm + hvigor 打包 HAP

用法：

powershell 复制代码

# 从 m3u8dl-tauri 仓库根目录取脚本（首次运行加 -InstallToolchain）
.\port-to-ohos.ps1 -ProjectPath D:\你的项目 -InstallToolchain

# 以后重新打包（工具链已装好）
.\port-to-ohos.ps1 -ProjectPath D:\你的项目

跑完后只剩三件事手动做（都在 DevEco Studio 里，见第 7 步）：

SDK 位置、compatibleSdkVersion、签名；然后按第 8 步部署真机。

想理解脚本每一步在做什么，继续读下面的手动步骤。

第 1 步：准备环境

bash 复制代码

# Rust 交叉编译目标（标准库已预编译，直接下载）
rustup target add aarch64-unknown-linux-ohos

需要安装的软件（按官网装好即可）：

软件	说明
DevEco Studio	完整安装（自带 hvigor / ohpm / node / hdc）
ohpm	鸿蒙包管理器（可单独装到 D:\ohpm）
鸿蒙真机	开发者模式 + USB 调试

DevEco 的 SDK 位置必须指向完整 SDK （含 ets 组件）。

只指向 NDK 目录会报 SDK component missing，见第 7 步。

第 2 步：安装 OHOS 工具链（用修复后的仓）

2.1 Windows 先切 gnullvm 工具链（Linux/macOS 跳过）

Windows + llvm-mingw 环境下，默认 GNU 工具链链接会报

unable to find library -lgcc_eh。先装 gnullvm 工具链，后面所有 cargo 命令都带上它：

bash 复制代码

rustup toolchain install stable-x86_64-pc-windows-gnullvm
rustup target add --toolchain stable-x86_64-pc-windows-gnullvm aarch64-unknown-linux-ohos

2.2 克隆并安装 tauri-cli

bash 复制代码

# 1. 克隆已修复的 tauri OHOS 分支（cargo-mobile2 版本问题已修复）
git clone --branch feat/open-harmony https://atomgit.com/qq8864/tauri.git tauri-ohos

# 2. 安装 tauri-cli（OHOS 版）
cd tauri-ohos
cargo +stable-x86_64-pc-windows-gnullvm install --path crates/tauri-cli   # Windows
# cargo install --path crates/tauri-cli                                    # Linux/macOS

# 3. 安装 ohrs（编译 OHOS 后端的助手，必须装）
cargo install ohrs    # 若报 -lgcc_eh，同样加 +stable-x86_64-pc-windows-gnullvm

# 4. 验证
cargo tauri --version        # 应输出 tauri-cli 2.8.4
cargo tauri ohos --help      # 应出现 init / build 子命令

Linux/macOS 用户跳过 2.1，直接执行 2.2 的普通命令即可。

第 3 步：固定项目工具链（Windows）

在你的项目 src-tauri/ 下新建 rust-toolchain.toml，让项目里所有 cargo

命令（包括 cargo tauri ohos build 内部调用的 cargo）都用 gnullvm：

toml 复制代码

[toolchain]
channel = "stable-x86_64-pc-windows-gnullvm"
targets = ["aarch64-unknown-linux-ohos"]

第 4 步：改造项目代码（30 分钟）

假设已有标准 Tauri v2 项目（src-tauri/ 目录）。

4.1 入口：lib.rs + main.rs

src-tauri/src/lib.rs：

rust 复制代码

pub mod commands;

/// Tauri 应用入口（OHOS 正常运行的關鍵）
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            /* 你的命令 */
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

src-tauri/src/main.rs：

rust 复制代码

#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

fn main() {
    your_app_lib::run()
}

4.2 Cargo.toml（完整替换依赖部分）

toml 复制代码

[lib]
name = "your_app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]   # 必须

[build-dependencies]
tauri-build = { path = "../../tauri-ohos/crates/tauri-build", default-features = false, features = ["codegen"] }

[dependencies]
tauri = { path = "../../tauri-ohos/crates/tauri", features = [] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
# ...你的其他业务依赖不变

# 桌面平台：原生证书 + 原生对话框
[target.'cfg(not(target_env = "ohos"))'.dependencies]
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls-native-roots", "stream"] }
rfd = "0.15"        # 如果用了 rfd

# OHOS：内置根证书 + napi 桥接（缺了编译报 cannot find crate napi_ohos）
[target.'cfg(target_env = "ohos")'.dependencies]
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls-webpki-roots", "stream"] }
napi-derive-ohos = "1.1"
napi-ohos = { version = "1.1", features = ["napi8"] }

tauri-ohos 是第 2 步克隆的仓库路径，按你的实际位置改。

4.3 平台差异命令（只需处理对话框/资源管理器）

src-tauri/src/commands.rs 里，凡是调 rfd 或 explorer 的命令，加平台分支：

rust 复制代码

#[cfg(not(target_env = "ohos"))]
#[tauri::command]
pub async fn pick_folder() -> Option<String> {
    /* 原实现（rfd::FileDialog...） */
}

#[cfg(target_env = "ohos")]
#[tauri::command]
pub async fn pick_folder() -> Option<String> {
    None   // OHOS 无原生对话框，返回空即可
}

命令名保持不变 → 前端零改动。

4.4 链接器包装（Windows）

src-tauri/ohos-clang.cmd（把 NDK 路径换成你的）：

bat 复制代码

@echo off
"D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony\native\llvm\bin\clang.exe" ^
  -target aarch64-linux-ohos ^
  --sysroot="D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony\native\sysroot" ^
  -D__MUSL__ -fuse-ld=lld %*

src-tauri/.cargo/config.toml：

toml 复制代码

[target.aarch64-unknown-linux-ohos]
linker = "..\\ohos-clang.cmd"
ar = "D:\\oh\\DevEcoStudio\\sdk\\HarmonyOS-NEXT-DB6\\openharmony\\native\\llvm\\bin\\llvm-ar.exe"
rustflags = [
    "-C", "link-arg=-fuse-ld=lld",
    "-C", "link-arg=--rtlib=compiler-rt",
]

4.5 图标

generate_context!() 要求 RGBA PNG。在 src-tauri/icons/ 放一个 1024×1024 的

RGBA 图片，命名 icon.png（Pillow 生成时确保 mode="RGBA"，RGB 三通道会报

icon is not RGBA）。

第 5 步：初始化 + 交叉编译

powershell 复制代码

# OHOS_HOME 指到 SDK 根目录（不是 native/！）
$env:OHOS_HOME = "D:\oh\DevEcoStudio\sdk\HarmonyOS-NEXT-DB6\openharmony"

cd src-tauri
cargo tauri ohos init --skip-targets-install     # 生成 gen/ohos/ DevEco 工程
cargo tauri ohos build -t aarch64                # 编译 .so（自动复制到 libs/）

成功标志：gen/ohos/entry/libs/arm64-v8a/lib你的应用_lib.so 存在。

（Windows 下 build 最后会提示"手工完成 HAP 打包"------这是修复后的正常提示，见第 6 步。）

第 6 步：打包 HAP

把前端复制进 rawfile（必做，build 不会自动同步）：

powershell 复制代码

Copy-Item -Force ..\frontend\* `
  "src-tauri\gen\ohos\entry\src\main\resources\rawfile\" -Recurse

打包（Windows 用 cmd /c，因为 .bat 需要 cmd 执行）：

powershell 复制代码

$env:PATH = "D:\Program Files\Huawei\DevEco Studio\tools\node;" +
            "D:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin;" +
            "D:\ohpm\ohpm-1.2.5\bin;" + $env:PATH
$env:DEVECO_SDK_HOME = "D:\Program Files\Huawei\DevEco Studio\sdk"

cd src-tauri\gen\ohos
cmd /c "ohpm install"
cd entry && cmd /c "ohpm install" && cd ..
cmd /c "hvigorw assembleHap --mode module -p product=default --no-daemon"

产物：entry/build/default/outputs/default/entry-default-signed.hap

第 7 步：DevEco Studio 配置（一次性）

打开 src-tauri/gen/ohos/ 工程后，做三件事：

SDK 位置 ：File → Settings → SDK（HarmonyOS SDK）→ 指向完整 SDK
（含 ets 组件），例如 D:\Program Files\Huawei\DevEco Studio\sdk。
compatibleSdkVersion ：打开 build-profile.json5，改成**≤ 真机 API 版本** 的值。
查真机：hdc shell "param get const.ohos.apiversion"。
例：真机 API 24 → "compatibleSdkVersion": "6.1.1(24)"。
（保持 26.0.0 会在旧设备上安装失败：install failed due to older sdk version。）
签名：File → Project Structure → Signing Configs → Automatically generate
signature（需华为账号）。

然后命令行重打一次包（第 6 步命令），得到已签名 HAP。

第 8 步：部署到真机

bash 复制代码

hdc list targets                          # 确认设备在线
cd src-tauri\gen\ohos\entry\build\default\outputs\default
hdc install -r entry-default-signed.hap   # 注意用相对路径，hdc 绝对路径有坑
hdc shell "aa start -a EntryAbility -b com.your.bundle_name"

bundle 名以 gen/ohos/AppScope/app.json5 里的 bundleName 为准

（原 identifier 的连字符会自动转下划线）。

验证：

bash 复制代码

hdc shell "ps -ef" | grep 你的包名     # 有主进程 + render 进程 = 在跑
hdc shell "hilog -x" | grep -iE "panic|fatal"   # 无 panic 即正常
hdc shell "snapshot_display -f /data/local/tmp/s.jpeg"   # 截图看 UI
hdc file recv /data/local/tmp/s.jpeg s.jpeg

常见错误速查

报错	原因	解决
`cannot find open_harmony in cargo_mobile2`	tauri-cli 依赖旧版 cargo-mobile2	用修复后的仓（本指南第 2 步）
`Failed to run ohrs build: program not found`	没装 ohrs	`cargo install ohrs`
`unable to find library -lgcc_eh`	GNU 工具链 + llvm-mingw	用 gnullvm 工具链（第 3 步）
`cannot find crate napi_ohos`	缺 napi 依赖	Cargo.toml 加 `napi-ohos`/`napi-derive-ohos`（4.2）
`icon ... is not RGBA`	图标不是 RGBA	重新生成 RGBA PNG（4.5）
`toolchain file not found`	OHOS_HOME 指错	指 SDK 根目录，别指 `native/`（第 5 步）
`Failed to assemble HAP: os error 2`	Windows 无法执行 .bat	修复后分支会提示手工命令；照第 6 步做
`SDK component missing`	DevEco SDK 位置不对 / 版本不匹配	指向完整 SDK；改 compatibleSdkVersion（第 7 步）
`install failed due to older sdk version`	compatibleSdkVersion > 真机 API	改成真机 API 版本（第 7 步）
WebView 白屏	前端没同步 / JS 报错	`Copy-Item` 前端到 rawfile（第 6 步）；`node --check` 查 JS

移植核心要点

前端零改动是 Tauri 移植的最大红利------HTML/JS/CSS 直接进 rawfile。
两条关键链 ：Rust .so（交叉编译） + DevEco 工程壳（hvigor 打包）。
平台能力降级 ：OHOS 没有原生对话框/资源管理器/系统证书库，代码里做好
回退（返回 None / 报错提示 / webpki 根证书），UI 就不会崩。
版本对齐 ：cargo-mobile2 用 0.22 分支、compatibleSdkVersion 对齐真机 API、
tauri/tauri-build 用同一分支------三处对齐基本就顺了。
先跑通再优化 ：先出未签名 HAP 验证功能，再配签名上真机；
体积优化（opt-level = "z" 等）放最后。