8.1 前端 SDK @tauri-apps/api 核心用法

1. 问题本质

Tauri 应用启动时，会尝试在系统中查找 WebView2 运行时。如果没有找到：

默认情况下，窗口无法创建，应用会直接崩溃或弹出错误提示。
这对非技术用户来说体验极差，甚至可能投诉“应用打不开”。

目标：让应用在低版本或未安装 WebView2 的系统上，能够自动、静默地处理好依赖，或者至少给出清晰的引导。

2. 三种兼容方案

方案一：引导用户安装 WebView2 运行时（推荐用于外网用户）

这是最轻量的方式：应用检测到缺少 WebView2 时，弹出一个友好的对话框，指引用户前往微软官网下载“Evergreen Bootstrapper”（常青引导程序）。优点是不增加安装包体积，且后续 WebView2 会自动保持更新。缺点是用户必须有网络连接，且需要一定的操作能力。

Tauri 内置支持：在 tauri.conf.json 中配置：

{
  "tauri": {
    "bundle": {
      "windows": {
        "webviewInstallMode": {
          "type": "downloadBootstrapper"
        }
      }
    }
  }
}

这样 Tauri 会在应用启动失败时主动下载并运行 WebView2 引导程序。你也可以自定义提示文案，让用户更容易接受。

方案二：嵌入固定版本 WebView2（适用于离线/内网环境）

如果你的用户环境完全离线，或者你希望严格控制 WebView2 的版本（避免自动更新引入兼容性问题），可以在打包时直接携带一个“Fixed Version”（固定版本）的 WebView2 运行时。这会将 WebView2 的二进制文件放入应用的安装目录，应用启动时直接加载该版本，完全不依赖系统安装状态。

配置方式：

从 WebView2 Runtime 下载页获取固定版本包（选择与你的应用架构匹配的 x86/x64/arm64 版本）。
将解压后的文件夹（如 Microsoft.WebView2.FixedVersionRuntime.x64）放到项目的 src-tauri 目录中。
在 tauri.conf.json 中指定路径和环境变量：

{
  "tauri": {
    "bundle": {
      "windows": {
        "webviewInstallMode": {
          "type": "embedLoader",
          "fixedVersion": {
            "path": "./Microsoft.WebView2.FixedVersionRuntime.x64"
          }
        }
      }
    }
  }
}

代价：安装包体积会增加约 120~180 MB（根据架构），但换来的是完全离线可用，以及行为的一致性。适合企业内部系统或工控机等场景。

方案三：WebView2 已安装但仍需兼容低版本系统 API

有些老系统即使安装了 WebView2，也可能缺少一些较新的 Windows API（比如某些通知、任务栏缩略图功能）。Tauri 在这些情况下会自动降级或跳过，但如果你想更细致地控制，可以在 Rust 端通过条件判断 Windows 版本并关闭特定功能：

#[cfg(target_os = "windows")]
if tauri::utils::platform::is_windows_7() {
    // 禁用需要 Win10+ 的特性
}

同时，在 tauri.conf.json 中可以关闭依赖新 API 的权限（如 shell.open 在旧系统上可能行为不同），提前自测一遍。

3. 安装包层面的兼容策略

MSI/NSIS 安装器：你可以让安装程序在安装前检查 WebView2 是否存在。NSIS 脚本可以调用 WebView2 引导程序静默安装；WiX 之类的 MSI 工具也可以通过自定义动作实现。
便携版（exe）：便携版不写注册表，最好采用方案二（嵌入固定版本），否则每次启动都会提示下载运行时，用户体验极差。

4. 真实场景建议

面向普通用户的桌面工具：用方案一，让 Tauri 自动处理，因为现在大部分 Windows 10/11 都有 WebView2，只有极少数用户会触发下载引导，安装包保持轻量。
企业内部 OA 客户端：用方案二，并配置组策略阻止 WebView2 自动更新，确保所有员工使用同一版本，减少 IT 支持压力。
仍然需要支持 Windows 7：请注意微软已于 2023 年 1 月停止 Windows 7 的扩展安全更新，WebView2 对 Win7 的支持也停留在较老版本。你需要使用对应的固定版本 WebView2（版本号 ≤ 109），并在安装包中捆绑。同时要在 tauri.conf.json 中设置 "windows" 的 "minWebView2Version" 为 "109.0.1518.78" 左右。

5. 验证方法

在虚拟机中安装一个纯净的 Windows 7 SP1（不含任何更新），测试你的应用安装和启动流程。如果启动成功且界面正常，说明兼容方案生效。此外，可以用 Windows 10/11 的“添加/删除程序”卸载掉 WebView2 运行时，模拟首次遇到的低版本环境。

一句话总结：低版本兼容的核心是处理好 WebView2 的缺失或版本过旧问题。根据用户网络的连通性，选择引导下载或内嵌运行时，并提前在目标系统上真实验证，就能让 Tauri 应用平稳覆盖绝大多数 Windows 设备。