Tauri 2.x 版本线与变化详解：1.x 到 2.x 关键差异速查

本节目标：读完你能看懂 Tauri 的版本号含义，说清 2.x 相比 1.x 改了什么，并在遇到旧教程时快速对照差异。

Tauri 目前有两条大版本线：1.x 和 2.x。本教程全程以 2.x 为准（基线版本 2.11.5，发布于 2026-07-01），但网络上大量旧文章、旧视频还是 1.x 写法。这一章帮你建立版本感，免得被过时的配置带偏。

两条版本线：1.x 与 2.x

Tauri 1.0 发布于 2022 年 6 月，是第一个稳定大版本，陪社区走过了两年多。Tauri 2.0 稳定版在 2024 年 10 月发布，最大的标签是移动端成为一等公民——从 2.0 起，Android 和 iOS 不再是实验特性，而是官方稳定支持的目标平台。

2.x 此后持续小版本迭代，到本教程基线已是 2.11.x。两个版本线配置和插件写法不兼容，所以你搜到的教程如果还是 tauri > allowlist、@tauri-apps/api/tauri 这种写法，基本就是 1.x 时代的，不能直接照抄到 2.x。

版本号怎么看

Tauri 的版本号遵循语义化版本（SemVer），形式是 主版本.次版本.修订号，比如 2.11.5：

主版本（2）：大改动的标志。数字变了通常意味着不兼容的旧写法要调整。1 → 2 就是这种级别。
次版本（11）：在保持兼容的前提下加新功能。2.11 相对 2.0 加了不少能力，但老代码一般还能跑。
修订号（5）：修 bug、做小修正，不影响接口。

配套的前端包也走独立版本线：@tauri-apps/cli 当前是 2.11.4，@tauri-apps/api 是 2.11.1。它们和 Rust 侧的 tauri crate 主版本对齐即可，小版本不必逐一对齐。

Tip

想知道自己用的是哪版？Rust 侧看 src-tauri/Cargo.toml 里 tauri 的版本号；前端看 package.json 里 @tauri-apps/* 的版本。遇到报错先确认两边大版本一致。

2.x 相对 1.x 的关键变化

下面三处变化影响最大，写代码时几乎一定会碰到。

配置结构重组

2.x 把 tauri.conf.json 重新分区，逻辑更清楚。最关键的是原来顶层的 tauri 键改成了 app，打包相关的 bundle 和构建相关的 build 提升为顶层对象；package 里的 productName、version 也提到了最外层。

一个 2.x 配置骨架长这样：

{
  "productName": "my-app",
  "version": "0.1.0",
  "identifier": "com.example.myapp",
  "build": {
    "frontendDist": "../dist",
    "devUrl": "http://localhost:5173"
  },
  "app": {
    "windows": [
      { "title": "我的应用", "width": 800, "height": 600 }
    ],
    "trayIcon": {
      "id": "main-tray",
      "iconPath": "icons/icon.png"
    }
  },
  "bundle": {
    "active": true,
    "targets": "all"
  }
}

注意两个老字段改名：build > distDir → frontendDist，build > devPath → devUrl；系统托盘从 tauri > systemTray 挪到 app > trayIcon。

插件权限模型：allowlist → capabilities

这是 2.x 安全模型的核心升级。1.x 用 tauri > allowlist 开关各个能力；2.x 改成了能力（capabilities） 系统：你在 src-tauri/capabilities/ 目录下写 JSON 文件，声明「哪个窗口、能用哪些插件的哪些命令、作用域到哪」。没声明的，默认拒绝。

一个能力文件示例：

{
  "identifier": "default",
  "description": "默认能力",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "dialog:default",
    "fs:default",
    {
      "identifier": "fs:scope",
      "allow": [{ "path": "$DOCUMENT/**/*.md" }]
    }
  ]
}

这套机制更像访问控制列表（ACL），可以按窗口、按域名精细分配，对多窗口和加载远程页面的场景更安全。

移动端成为一等公民

2.x 起，Android 和 iOS 是稳定支持的目标。代价是项目结构要能产出「共享库」：1.x 只有桌面可执行文件，2.x 需要把入口从 main.rs 改成 lib.rs，并加上移动端入口宏：

// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用时出错");
}

然后用 npx tauri android init / npx tauri ios init 初始化移动端工程。桌面与移动端差异（屏幕、权限、目录）仍需单独处理，但「同一套代码跨端」在 2.x 是官方支持的事。

Note

事件 API 也有调整：2.x 里 emit 默认发给所有监听者，新增 emit_to / emitTo 发往特定目标；旧的 listen_global 改名 listen_any；过滤改用 EventTarget。另外 Rust 的 Window 类型改名 WebviewWindow，前端 window 模块改名 webviewWindow。

兼容说明：1.x 与 2.x 主要差异速查

兼容说明（1.x → 2.x 主要差异）
遇到旧教程时，按这张表对照即可，切勿混用两套写法：

配置：顶层 tauri 键 → app；package > productName/version 提到最外层；build > distDir → frontendDist，devPath → devUrl；tauri > systemTray → app > trayIcon；tauri > bundle → 顶层 bundle。

权限：tauri > allowlist（白名单开关）→ src-tauri/capabilities/ 能力文件，默认拒绝、按需授权。

JS API 包名：@tauri-apps/api/tauri → @tauri-apps/api/core；@tauri-apps/api/window → @tauri-apps/api/webviewWindow。

内置模块外置为插件：fs、dialog、http、shell、notification、os、clipboard、process、updater 等，从核心 API 移到独立插件（@tauri-apps/plugin-* 搭配 Rust 端 tauri-plugin-*），需在 Cargo.toml 和 capabilities 里显式引入。

Rust 类型改名：SystemTray → TrayIcon（tauri::tray）；Menu 相关 → tauri::menu；Window → WebviewWindow。

移动端：2.x 起 Android / iOS 稳定支持，需 lib.rs + tauri::mobile_entry_point。

环境变量：如 TAURI_PRIVATE_KEY → TAURI_SIGNING_PRIVATE_KEY 等大批重命名。

Warning

官方提供了 tauri migrate 命令自动把 1.x 项目迁到 2.x，它会解析旧 allowlist 并生成对应的能力文件。但自动迁移不能替代人工核查——迁完务必跑一遍、读一遍配置，确认没有遗漏的旧写法。

小结

Tauri 2.x 相对 1.x，主线是「更清晰、更安全、更跨端」：配置分区更合理，权限从白名单升级为默认拒绝的能力系统，移动端成为稳定一等公民。版本号 主.次.修 帮你判断改动大小——主版本跳变意味着要注意兼容。

记住一句话：看到 tauri > allowlist 或 @tauri-apps/api/tauri，那是 1.x 的痕迹；2.x 对应的是 app + capabilities + @tauri-apps/api/core。带着这个版本感，后面读任何 Tauri 资料都不会迷路。