用Tauri跨平台框架在鸿蒙PC上开发系统能力港口:NexaPort的沙箱文件舱、外设遥测与能力矩阵实践

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

关键词:鸿蒙PC,Tauri,跨平台框架,Rust,开源鸿蒙,HAP,ArkTS,IPC,沙箱文件系统,外设遥测

前言

开源鸿蒙PC正在成为桌面生态里一个值得关注的新阵地,而如何在鸿蒙PC上高效开发原生体验的桌面应用,是摆在很多开发者面前的现实问题。我这一系列实践选择了 Tauri 这套跨平台框架:它以 Rust 为后端、以 Web 技术为前端,通过 IPC 把两侧粘合起来,天然适合"系统能力调用"这类需要贴近底层的应用形态。
系统能力舱:编译期能力矩阵与运行时指标
本篇的主角是 NexaPort 系统能力港口——一个围绕"文件、外设与系统能力"三大主题构建的鸿蒙PC桌面应用。它把应用窗口设计成三座"泊位":文件舱负责沙箱内文件的真实浏览、编辑与删除;系统能力舱展示编译期能力矩阵与运行时指标;外设舱把鼠标、键盘事件实时上报给 Rust 内核形成环形日志。全部功能基于 Tauri 的 invoke IPC 通道实现,Rust 单元测试与工程测试全部通过,并在鸿蒙PC真机上完成了完整验证。

这篇文章会按"能力设计 → 命令端实现 → 前端泊位 → 真机验证"的顺序展开,所有代码都来自真实可运行的工程,希望能给想在鸿蒙PC上用跨平台框架做系统类工具的开发者一条可复现的路径。

一、为什么在鸿蒙PC上选 Tauri 这条跨平台路线

在鸿蒙PC上做应用,官方路线是 ArkTS + ArkUI。但如果你的应用本质上是"系统工具箱"——需要频繁读写沙箱文件、聚合设备与进程信息、处理外设事件流——用 Rust 写核心逻辑会有明显优势:内存安全、无 GC 停顿、标准库对文件与时间的抽象干净利落。

Tauri 恰好把"Rust 后端 + Web 前端"这套组合工程化了。在鸿蒙PC上,它的落地形态是一个三方协作:

  • Rust 侧编译为 cdylib 动态库(libnexaport_lib.so),里面包含全部业务命令;
  • ArkTS 侧由 NativeAbility 承载,负责加载这个动态库并把 WebView 窗口拉起来;
  • 前端侧是一份零依赖的 HTML/CSS/JS,通过 window.__TAURI__.core.invoke 发起 IPC 调用。

关键的一点是:Tauri 的 #[tauri::command] 宏会把普通 Rust 函数自动注册成前端可调用的 IPC 端点,参数与返回值用 serde 在 JSON 之间转换。这意味着"调用系统能力"这件事,在前端看起来就像调用一个本地函数。这正是跨平台框架的价值——把平台差异收敛到一侧,让前端保持纯粹的 UI 职责。

二、三泊位的能力设计

NexaPort 的功能规划围绕一个原则:每个泊位对应一类真实的系统能力,不做假数据。

泊位系统能力Rust 命令
文件舱沙箱文件系统的浏览/读写/删除list_dir / read_text_file / write_text_file / delete_entry
系统能力舱编译期能力矩阵 + 运行时指标system_report
外设舱指针/点击/键盘事件上报与环形日志log_peripheral / load_peripherals / clear_peripherals

此外保留两个基础命令:app_info 用于启动时自检 IPC 通道,greet 作为"呼叫内核"的活性探测。

NexaPort 在鸿蒙PC真机上的三泊位完整界面

上图是应用在鸿蒙PC真机上的完整桌面截图:深色"夜航港口"主题下,三座泊位一字排开,右上角的内核状态徽标与运行时长一目了然。得益于窗口尺寸 1320×880 的设计,正文文字从 15px 起步、标题 22px 以上,在桌面大屏上完全不需要眯眼看。

三、文件舱:带防穿越保护的沙箱命令端

3.1 存储泊位的探测与回退

在鸿蒙PC上,应用可写目录并不总是 app_data_dir 就能拿到。NexaPort 沿用了本系列验证过的"候选目录 + 探针写入"回退链:

fn candidate_roots(app: &tauri::AppHandle) -> Vec<PathBuf> {
    let mut roots = Vec::new();
    if let Ok(dir) = app.path().app_data_dir() {
        roots.push(dir.join(ROOT_DIR_NAME));
    }
    roots.push(PathBuf::from("el2/base/haps/entry/files").join(ROOT_DIR_NAME));
    roots.push(PathBuf::from("el2/base/files").join(ROOT_DIR_NAME));
    roots.push(PathBuf::from("/data/local/tmp").join(ROOT_DIR_NAME));
    roots.push(std::env::temp_dir().join(ROOT_DIR_NAME));
    roots
}

fn sandbox_root(app: &tauri::AppHandle) -> PathBuf {
    for candidate in candidate_roots(app) {
        let _ = fs::create_dir_all(&candidate);
        if probe_writable(&candidate) {
            return candidate;
        }
    }
    std::env::temp_dir().join(ROOT_DIR_NAME)
}

probe_writable 会在候选目录里真的写一个探针文件再删掉——只有写入成功的目录才算数。这套机制来自真机上踩过的坑:某些环境下 app_data_dir 返回的 XDG 风格路径并不可写,如果直接信任它,文件舱会在第一次保存时报 os error 1。

3.2 路径安全:把 .. 挡在门外

文件舱暴露给前端的 path 参数是相对路径,Rust 侧必须防止路径穿越攻击。safe_join 逐段解析并显式拒绝 ..:

fn safe_join(root: &Path, relative: &str) -> Result<PathBuf, String> {
    let cleaned = relative.trim().replace('\\', "/");
    if cleaned.is_empty() {
        return Ok(root.to_path_buf());
    }
    let mut target = root.to_path_buf();
    for part in cleaned.split('/') {
        if part == "." || part.is_empty() {
            continue;
        }
        if part == ".." {
            return Err("路径不允许包含 ..".into());
        }
        target = target.join(part);
    }
    if !target.starts_with(root) {
        return Err("路径越界".into());
    }
    Ok(target)
}

双保险设计:解析阶段拒绝 ..,拼装后再用 starts_with 校验最终路径仍落在沙箱根之内。这段逻辑配了专门的单元测试,docs/a.txt 通过、.. 与 a/../../etc 被拒。

文件舱:沙箱目录的真实浏览与编辑

真机上的文件舱如上图:面包屑显示当前沙箱路径,文件列表区分目录与文件并展示真实大小,选中文件后下方展开编辑器,保存与删除都直接作用于沙箱内的真实文件——没有任何一层是模拟数据。

3.3 读写删三件套

命令端本身很薄,核心是"safe_join 之后交给标准库":

#[tauri::command]
fn write_text_file(app: tauri::AppHandle, path: String, content: String) -> Result<u64, String> {
    let root = sandbox_root(&app);
    let target = safe_join(&root, &path)?;
    if let Some(parent) = target.parent() {
        fs::create_dir_all(parent).map_err(|e| format!("创建目录失败: {e}"))?;
    }
    fs::write(&target, content.as_bytes()).map_err(|e| format!("写入文件失败: {e}"))?;
    Ok(content.len() as u64)
}

值得注意的错误处理风格:所有 io::Error 都被转成带语义的中文错误串再经 IPC 抛给前端,前端可以直接把 errorMessage(err) 渲染到泊位底部的状态栏。Tauri 命令的 Result<T, String> 约定让这条错误链路零成本贯通。

四、系统能力舱:编译期与运行时的双重画像

系统能力舱的 system_report 命令最有意思的地方在于它混合了两个时间维度的信息:

#[tauri::command]
fn system_report(app: tauri::AppHandle) -> SystemReport {
    SystemReport {
        product: env!("CARGO_PKG_NAME"),
        ohos: cfg!(target_env = "ohos"),
        debug_assertions: cfg!(debug_assertions),
        env_vars: std::env::vars().count(),
        uptime_secs: STARTED.elapsed().as_secs(),
        pid: std::process::id(),
        capabilities: vec![
            Capability { name: "沙箱文件系统", level: "可用", detail: "浏览 / 读写 / 删除 全链路" },
            Capability {
                name: "目标环境 ohos",
                level: if cfg!(target_env = "ohos") { "已编译" } else { "未编译" },
                detail: "target_env = ohos 编译期判定",
            },
            // ... 其余能力项
        ],
        // ...
    }
}

env! 与 cfg! 是编译期求值的——它们记录的是"这个 .so 是在什么条件下被编译出来的";而 uptime_secs、pid、环境变量计数是运行时探得的活数据。两者同屏呈现,等于给应用做了一张"出厂铭牌 + 实时仪表"的组合画像。STARTED 用 LazyLock<Instant> 实现,进程启动即计时:

static STARTED: LazyLock<Instant> = LazyLock::new(Instant::now);

前端拿到报告后,把 os/arch/环境变量数/PID 渲染成 2×2 的指标卡片,四条能力项则渲染成带"可用/已编译"徽标的清单,右上角的 uptime 每秒跳动一次。

系统能力舱:编译期能力矩阵与运行时指标

上图可以看到系统能力舱的真机状态:指标卡片、能力徽标与"呼叫内核"输入框同屏。“呼叫内核"是给 IPC 通道做活性检查的小玩具——输入任意泊位名,greet 命令会原样应答一句"泊位 XX 已应答,Rust 内核在线!”。

五、外设舱:从 DOM 事件到 Rust 环形日志

外设舱要回答的问题是:当用户在鸿蒙PC上移动鼠标、敲击键盘时,事件流如何安全地流过跨平台框架的边界?

前端侧监听三类 DOM 事件,并做了节流——pointermove 以 90ms 为窗口限频,避免 IPC 被高频移动事件打爆:

let moveThrottle = 0;
window.addEventListener("pointermove", (e) => {
  const now = performance.now();
  if (now - moveThrottle < 90) return;
  moveThrottle = now;
  reportPeripheral("pointer", { x: Math.round(e.clientX), y: Math.round(e.clientY) });
});

Rust 侧则用 Mutex<Vec<PeripheralEvent>> 维护一条容量 60 的环形日志,超出即从头部丢弃:

const LOG_CAPACITY: usize = 60;

fn push_event(log: &mut Vec<PeripheralEvent>, event: PeripheralEvent) {
    log.push(event);
    if log.len() > LOG_CAPACITY {
        let drain = log.len() - LOG_CAPACITY;
        log.drain(..drain);
    }
}

log_peripheral 命令每次把最新日志整体返回,前端倒序渲染——最近的事件永远在最上面。这是一个刻意为之的设计:不做流式推送,而是让 IPC 的请求-响应语义天然形成"读一次、同步一次"的节拍,既简单又足够稳。

外设舱:指针/点击/键盘的实时遥测

外设舱的真机效果如上图:三个统计卡片分别累计指针移动、鼠标点击与键盘按键次数;底部是环形日志的时间线。更炫的一部分是覆盖全屏的"航迹画布"——每次指针移动都会在 canvas 上绽开一圈青色涟漪,点击则是玫瑰色的大圆环,动效全部由前端 requestAnimationFrame 驱动,不给 Rust 侧增加任何渲染负担。

六、真机验证与工程测试

NexaPort 的质量底线由两层测试保证。Rust 侧五个单测覆盖了命令语义与安全边界:

#[test]
fn safe_join_blocks_traversal() {
    let root = Path::new("/tmp/nexaport-test");
    assert!(safe_join(root, "docs/a.txt").is_ok());
    assert!(safe_join(root, "..").is_err());
    assert!(safe_join(root, "a/../../etc").is_err());
    assert_eq!(safe_join(root, "./docs//b.txt").unwrap(), root.join("docs/b.txt"));
}

工程侧另有八项测试校验配置一致性:包名 com.nexaport.app 在 tauri.conf.json 与 AppScope/app.json5 中保持一致、Rust 库名在四处(Cargo.toml、EntryAbility、oh-package、类型声明)统一、以及前端命令与 Rust 命令成对出现的映射检查——这项测试会逐一断言 list_dir、system_report、log_peripheral 等命令在 web/main.js 和 src-tauri/src/lib.rs 两侧同时存在,从机制上杜绝"前端调用了不存在的命令"这类低级错。

构建链路上有一个本系列反复确认过的关键点:Tauri 在编译期把 web/ 前端嵌入动态库。所以任何前端改动之后,必须重跑 Rust release 构建、再打 HAP,否则真机上跑的还是旧界面且没有任何报错。NexaPort 的构建顺序因此固化为:

sh tools/build-rust.sh   # 产出 libnexaport_lib.so(release)
sh tools/build-hap.sh    # hvigor 打包,产出 build-output/entry-default-unsigned.hap

真机上的完整运行状态:三泊位协同工作

最终在鸿蒙PC真机上,三座泊位可以协同工作:在文件舱里新建并编辑一个日志文件,切到外设舱操作鼠标键盘产生遥测记录,系统能力舱的 uptime 与进程指标全程跳动——整条链路都是 Tauri IPC 在鸿蒙PC上的真实往返。

七、写给准备上手的你

把这套跨平台框架路线走通之后,我对"在鸿蒙PC上做系统工具类应用"有了几点可以复用的结论:

  1. 能力要按泊位切分,命令要成对验证。 前端命令与 Rust 命令的映射检查测试,是防回归成本最低、收益最高的一道闸。
  2. 可写目录必须探测,不能信任返回值。 探针写入回退链让文件舱在多种沙箱环境下都稳如老狗。
  3. 编译期与运行时信息分开呈现。 cfg!/env! 是"出身证明",uptime/pid 是"体检单",混在一起说不清,分开则各自可信。
  4. 事件流要节流、要环形截断。 高频外设事件用 90ms 限频 + 60 条容量上限,内存与 IPC 压力都可控。

NexaPort 的完整工程结构(Rust 命令端、零依赖前端、hvigor 鸿蒙工程)已经在开源鸿蒙PC社区的应用开发流程中验证过一轮。如果你也想在鸿蒙PC上尝试跨平台框架开发,欢迎在 AtomGit 的 OpenHarmonyPCDeveloper 组织下申请新建项目,把你的"港口"也停靠进来。

工程源码与后续演进计划托管于 AtomGit,下一篇计划给文件舱加上目录树与重命名,给外设舱接入滚轮事件遥测——欢迎持续关注这个系列。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐