框架与适配 · Tauri 框架源码镜像 · Tauri 上游鸿蒙适配分支
桌面应用升级会遇到三种存量配置:可以直接迁的、缺少新字段但还能补齐的、根本无法解析的。用户下次打开时应该得到完整设置,排查时又要能读到原文件。这篇把迁移规则与文件写入提交顺序分别验证,并保留失败现场来解释为什么要先留住旧版。
升级程序开始之前,旧文件的结局应该已经写清楚。主题是 blue 的旧配置可以生成新版,缺主题也可以按规则填成 system,损坏的 JSON 则应停下来,原文留给排查。这是鸿蒙 PC 上这份 Tauri 配置迁移的约定。下面从三个样本目录核对它,顺便看看第一次尝试为什么连合法输入也写不出去。
| 源配置 | 第一次处理 | 旧文件 | 新文件 |
|---|---|---|---|
有 theme: "blue" |
生成版本 2 | 保留 blue 和 futureOption | version 2,theme 为 blue |
只有 version: 1 |
按默认值迁移 | 保留原来的单字段内容 | version 2,theme 为 system |
内容为 {broken |
JSON 无法解析 | 保留原字节内容 | 未生成 |
| 已经生成过版本 2 | 再次进入读取现有结果 | 保留 | 直接读取现有版本 2 |
从源码重建这份迁移页
本次工作从 MateBook 14 的 DevEco Studio 开始。工程根目录里 src/main.ts 管理样本按钮与两栏输出,src-tauri/src/migration.rs 负责真正的目录与文件操作。检查 src-tauri/src/lib.rs 注册了 migration::migrate_workspace,再用前端的 invoke 调同一个方法。两个文件能对上,只说明版本的接口一致,实际写文件还要等鸿蒙模块加载新的动态库。
| 环境 | 版本和证据定位 |
|---|---|
| 本机重建 | HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64;DevEco Studio 26.0.0.220,Node.js 24.18.1,esbuild-wasm 0.28.2。 |
| 早期模拟器运行 | MateBook Pro 2in1,HarmonyOS 6.1.0,软件 6.1.0.125(SP12DEVC00E47R1P3),API 24,x86_64。用当时的调试 HAP 验证输入分支。 |
在本机恢复依赖,生成前端的 HTML、JS 和 CSS。在本次复测中,依赖来自同一台 MateBook 14 上已经按相同锁文件恢复的工程。下面的命令从干净目录也能重建这些资源。实际输出中有三份文件,node --check 已读过生成的 JS。这个步骤验证了 Tauri 将要嵌入的前端资源。
npm ci --ignore-scripts
npm install --ignore-scripts --no-save --package-lock=false esbuild-wasm@0.28.2
node build-native-frontend.mjs
node --check dist/app.js
ls -lh dist

MateBook 14 原生 DevEco 终端,本机生成迁移页的 HTML、JS 和 CSS
接下来需要找到可运行的鸿蒙 Rust 工具链。DevEco 的终端搜索路径没有找到 Rust 或 Cargo,已校验的鸿蒙 arm64 工具链仍在版本查询时返回 zsh: permission denied。这次停在 Rust 编译器启动,和下面早期安装包中发生的 create_dir_all 错误是两件事。前者发生在编译前,后者需要已有包运行到业务命令才会出现。

同一台 MateBook 14 上,工具链版本查询被系统拒绝,编译未开始
本机 Rust 可用后,下一轮要把主程序和鸿蒙库都从当前源码重编,复核 2in1 模块与库架构,并在 DevEco 配置对应包名的调试签名。装完要在隔离的三个目录重走含主题、缺主题、损坏样本和重复读回。当前这版还没有生成新的签名 HAP,因此下面的录屏和写盘结果以当时的签名包为准。

MateBook Pro 模拟器的原生关于本机,保留系统栏和完整软件版本
三种输入要分开放。命令遇到已有新版会读回它;若几个按钮都写同一个目标,第一次生成的新版可能挡住后续分支。要重试首次迁移,用一份尚无新版的隔离目录,不必清理真实使用中的配置。图里左栏来自读取的旧文件,右栏才是新版或无产物的状态。
读日志时对照主题和状态,不需要打印真实用户文件。只在自己的调试目录里放损坏样本,别用生产配置作为复测输入。
旧版保留什么,新版拿走什么

鸿蒙 PC 模拟器全屏,旧配置里的主题和额外字段仍可见

鸿蒙 PC 模拟器全屏,旧版缺主题时,新版填入 system

鸿蒙 PC 模拟器全屏,损坏的源文件保留原样,右栏没有新版
主题字段会进入新版。额外的 futureOption 留在旧文件中,新文件只写新版约定的字段。缺主题的对象已经解析出合法版本,才轮到默认值;右半边缺掉的 JSON 连解析也未通过,不能按缺字段处理。初次迁移与重复运行也分开。第二次点同一成功样本,右边读到的是原有新版,没有再次覆盖。
sample=legacy status=created theme=blue
sample=legacy status=existing theme=blue
sample=missing status=created theme=system
sample=invalid status=invalid theme=none
这页把源文件名和新版文件名分放两栏。看出错结果时,可以顺着左栏核对保留的原文,再到右栏看新版是否生成。窗口窄时改为上下排列,两个标题继续跟各自的文件文本。
界面展示的左侧文本来自本次从磁盘读出的源文件,额外字段应仍在其中。若要进一步验证整个文件没有被覆盖,可以在迁移前后分别计算源文件校验值,或直接逐字节比较。这个演示不把未知字段写入 v2,旧文件因此也是排查历史配置的依据。对正式升级程序,还应先规定支持哪些 v1 字段和错误类型,再决定遇到未知字段时保留、忽略还是提示,否则同一个 v1 会随版本得到不同的结果。
写新版失败时,旧文件还能打开
同目录改名为什么会失败? 第一次在这台鸿蒙 PC 模拟器上用临时文件再改名,合法样本提示 Permission denied (os error 13),损坏样本仍能回报解析失败。复测中改为独占创建新版文件、写入后同步,重新安装后两种合法样本均成功。这里记录的是这套适配环境的实际表现,改名受限的具体系统策略尚未验证。
第一次能读旧配置,临时文件改名却被拒绝。这个结果让排查离开了 JSON 解析器,转向最终写入步骤。改用 create_new(true) 创建新版时仍保留不覆盖的要求。完成写入并同步才算成功,遇到普通写入失败尝试删除未完成文件。这个做法留下一个边界:进程若突然终止,清理函数未必执行,已有新版也可能只是半成品。
Tauri 命令使用 app.path().app_config_dir() 定位应用配置区。这里的内置样本只在第一次建立时写入 v1,后面的步骤只读取它。先用 serde_json 解析并核对版本,再按新版所需的字段生成 v2。缺主题用 system,旧文件里其余字段原样留下。新版用 create_new(true) 独占创建,写入并同步后才回报成功。捕捉到写入错误时,代码尝试清理未完成的文件。这一路径不会覆盖既有新版。异常退出发生在写入中间时仍可能留下半成品,所以生产环境需要另外设计启动时的校验和恢复。 Tauri 命令文档
use serde::Serialize;
use std::fs;
use std::io::Write;
use tauri::Manager;
#[derive(Serialize)]
pub(crate) struct Migration {
before: String,
after: String,
status: &'static str,
}
#[tauri::command]
pub(crate) fn migrate_workspace(app: tauri::AppHandle, sample: &str) -> Result<Migration, String> {
let fixture = match sample {
"legacy" => r#"{"version":1,"theme":"blue","futureOption":true}"#,
"missing" => r#"{"version":1}"#,
"invalid" => "{broken",
_ => return Err("未知样本".into()),
};
let root = app.path().app_config_dir().map_err(|e| e.to_string())?.join("migration-demo").join(sample);
fs::create_dir_all(&root).map_err(|e| e.to_string())?;
let old = root.join("preferences-v1.json");
let new = root.join("preferences-v2.json");
if !old.exists() {
fs::write(&old, fixture).map_err(|e| e.to_string())?;
}
let before = fs::read_to_string(&old).map_err(|e| e.to_string())?;
let data: serde_json::Value = match serde_json::from_str(&before) {
Ok(value) => value,
Err(_) => return Ok(Migration { before, after: String::new(), status: "invalid" }),
};
if data.get("version").and_then(|value| value.as_u64()) != Some(1) {
return Err("源配置版本不支持".into());
}
if new.exists() {
let after = fs::read_to_string(&new).map_err(|e| e.to_string())?;
return Ok(Migration { before, after, status: "existing" });
}
let theme = data.get("theme").and_then(|value| value.as_str()).unwrap_or("system");
let after = serde_json::to_string_pretty(&serde_json::json!({"version": 2, "theme": theme}))
.map_err(|e| e.to_string())?;
let mut destination = fs::OpenOptions::new().write(true).create_new(true).open(&new)
.map_err(|e| format!("创建新版配置失败:{e}"))?;
if let Err(error) = destination.write_all(after.as_bytes()).and_then(|_| destination.sync_all()) {
drop(destination);
fs::remove_file(&new).map_err(|cleanup| format!("写入失败:{error},清理失败:{cleanup}"))?;
return Err(format!("写入失败:{error}"));
}
Ok(Migration { before, after, status: "created" })
}
import { invoke } from '@tauri-apps/api/core';
import './migration.css';
document.querySelector('#app')!.innerHTML = `
<main>
<header><h1>工作区配置迁移</h1><p>检查旧版配置,生成新版配置并保留原文件。</p></header>
<div class="samples" aria-label="配置样本">
<button data-sample="legacy">旧版含主题</button>
<button data-sample="missing">旧版缺主题</button>
<button data-sample="invalid">损坏的配置</button>
</div>
<p id="status" role="status">请选择配置样本</p>
<div class="files">
<section><h2>源配置 <code>preferences-v1.json</code></h2><pre id="before">---</pre></section>
<section><h2>新版配置 <code>preferences-v2.json</code></h2><pre id="after">---</pre></section>
</div>
</main>`;
type Migration = {before: string; after: string; status: 'created' | 'existing' | 'invalid'};
const status = document.querySelector<HTMLParagraphElement>('#status')!;
const before = document.querySelector<HTMLPreElement>('#before')!;
const after = document.querySelector<HTMLPreElement>('#after')!;
const buttons = Array.from(document.querySelectorAll<HTMLButtonElement>('[data-sample]'));
const labels = {created: '已写入新版,旧文件保留', existing: '已读取现有新版,旧文件保留', invalid: '源配置无法解析,未写入新版'};
for (const button of buttons) {
button.addEventListener('click', async () => {
for (const item of buttons) {
item.disabled = true;
item.setAttribute('aria-pressed', String(item === button));
}
status.textContent = '读取中';
try {
const result = await invoke<Migration>('migrate_workspace', {sample: button.dataset.sample});
before.textContent = result.before;
after.textContent = result.after || '没有生成新版配置';
status.textContent = labels[result.status];
status.dataset.kind = result.status;
console.info('UGC_TAURI_MIGRATION sample=' + button.dataset.sample
+ ' status=' + result.status + ' theme=' + (result.after ? JSON.parse(result.after).theme : 'none'));
} catch (error) {
status.textContent = '迁移失败:' + String(error);
status.dataset.kind = 'invalid';
before.textContent = '---';
after.textContent = '---';
} finally {
for (const item of buttons) item.disabled = false;
}
});
}

鸿蒙 PC 模拟器窄窗全屏,源文件和新版结果上下排列
真机跑到写文件时,三份样本都停住了
定位到创建目录后,再用应用私有目录复测
给目录创建加上操作名,MateBook 14 回传 create_dir_all: Operation not permitted (os error 1)。这套 Tauri 分支在鸿蒙上沿用桌面 app_config_dir() 的解析。试着从鸿蒙 Ability 取 base_path() 时,本次入口也没提供可用值。调试版改为优先用宿主给出的非空目录,取不到时才用该机应用沙箱内的 /data/storage/el2/base/files。示例的文件名、旧版字段和写入约定保持原样。正式工程应从自己的 Ability 上下文传入目录。
// 鸿蒙分支中选取本次调试使用的私有目录
let base = OHOS_CONFIG_ROOT
.get()
.cloned()
.filter(|path| !path.as_os_str().is_empty())
.unwrap_or_else(|| std::path::PathBuf::from("/data/storage/el2/base/files"));
let root = base.join("migration-demo").join(sample);
std::fs::create_dir_all(&root)
.map_err(|e| format!("create_dir_all: {e}"))?;
换上签名调试包,再在原真机复测。第一次含主题样本生成 blue,第二次直接读到同一份新版,缺主题样本生成 system。坏 JSON 此时能到达解析分支,左侧显示原文,右侧保持无产物。下面三条状态把之前的系统错误和修复后的结果区分开。

MateBook 14 真机全屏,使用应用私有目录后生成主题为 blue 的新版

MateBook 14 真机全屏,损坏样本保留原文并显示无新版
MateBook 14 用独立的演示目录复现首次迁移。第一次写入新版并保留旧文件;重复操作读取已有新版。缺主题时新版填入 system,损坏的配置则显示「未写入新版」。原始全屏 MP4 为 2880 × 1920,整段约 59.9 fps。

UGC_TAURI_MIGRATION sample=legacy status=created theme=blue
UGC_TAURI_MIGRATION sample=legacy status=existing theme=blue
UGC_TAURI_MIGRATION sample=missing status=created theme=system
UGC_TAURI_MIGRATION sample=invalid status=invalid theme=none
对照下面这一组旧包截图,能看见第一次真机为什么还没读到 JSON。错先出在创建目录,之后才按实际 API 的私有文件区重新选路径并复测。新版工具链能运行后,也要用相同的三类内容和实际目录再核对一次。
| 设备 | 系统与 ABI | 当前实际结果 |
|---|---|---|
| HUAWEI MateBook 14(MNTXM-24B) | HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64 | 签名安装和打开界面通过;三份样本均返回系统错误 1 |
| MateBook Pro 2in1 模拟器 | HarmonyOS 6.1.0,软件版本 6.1.0.125(SP12DEVC00E47R1P3),API 6.1.1(24),x86_64 | 合法样本写出新版,重复读取已有配置,坏 JSON 留在原文区 |

HUAWEI MateBook 14 真机关于本机全屏,完整软件版本及 API
真机上,点「旧版含主题」时,界面立即显示 Operation not permitted (os error 1)。再次点同一个样本、换到缺主题、换到损坏样本,都得到同样的提示。两个文本区没有显示原文或新版,因此这轮只证明请求回到了界面上的错误分支。模拟器那次改名失败是另一条已定位的记录,不能从那条错误推断这次具体是哪一个文件调用受限。

MateBook 14 真机全屏,选择含主题样本后界面返回系统错误 1

MateBook 14 真机全屏,坏样本同样停在系统错误,尚未观察到 JSON 解析分支
hvigor Finished :entry:default@SignHap
install bundle successfully.
start ability successfully.
versionName: 1.0.0
迁移失败:Operation not permitted (os error 1)
初次真机错误只有一条系统描述,因此排查时给目录创建加上操作名,再重新构建。这样可以在修改迁移逻辑之前,先证实是文件目录的问题。前面保留的失败图与修复后的全屏图对应两次不同的签名安装。

模拟器实录,生成新版、重复读取并检查缺字段和损坏样本
早期模拟器实录共 12.05 秒,保留 76 个不同画面。对照三组文件内容与重复读取,当前本机重建停在哪一步见前文终端截图。两者按各自批次判断。
FAQ
看到 existing,是否可以跳过内容检查? 当前演示会优先读已有新版,重复点击正好用来观察它有没有被覆盖。面向真实配置时,存在只是路径状态,仍需验证结构和版本。后续如果加入启动修复,不能看到文件名就删,也不能用可能损坏的文件覆盖旧版。可以先区分完整新版、可恢复半成品和解析失败三类状态,各自决定下一步。
改名的权限原因查到了吗? 当前记录只支持这台鸿蒙 PC 模拟器上原路径报拒绝,换写法后两种合法样本都成功。具体受限策略仍未确认,不能用这条日志推断其他设备的文件系统也必然如此。
结语
早期真机包在私有目录里生成了两份合法样本的新版,坏文件保留原内容,重复操作读出已有主题。此次在 MateBook 14 复建设备端前端产物已成功,Rust 启动失败之后的编译、签名和安装仍待补证。正式迁移还应验证突然中断后留下的新版能否通过结构检查。