怎么读这一卷

主线位置：三条主线的总览。本页把启动主线、调用主线和事件主线各画一遍，标出每一步落在哪个函数上、哪一页讲它；再讲这三条线为什么在开发和发布两种构建里走不同的代码：custom-protocol 这个 feature 经过两个构建脚本变成应用里的 cfg(dev)，debug_assertions 又让 debug 和 release 有别。「一次启动」和「一次 invoke」用带时间戳的实验把前两条线各走一遍。

flowchart TB
  start[从这里开始] --> q{读这一卷为了什么}
  q -->|会用| use1[01 全景]
  use1 --> use2["06 的分发与参数"]
  use2 --> use3["07 的能力与运行时检查"]
  q -->|读懂实现| all[00 到 11 按顺序]
  q -->|自己写一个| hands["03 运行时 再到 11 动手"]

锁定版本

wry 和 tao 的 tag 比 tauri 的 tag 晚两天，它们是独立发版的仓库。本卷的版本组合不是挑出来的：一个新 crate 写 tauri = "=2.12.5"、tauri-build = "=2.7.4"，cargo 解析出来就是这一组，实验项目的 Cargo.lock 里一共 414 个包。源码链接一律指向 tag：https://github.com/tauri-apps/tauri/blob/tauri-v2.12.5/crates/...、https://github.com/tauri-apps/wry/blob/wry-v0.57.1/src/...、https://github.com/tauri-apps/tao/blob/tao-v0.37.2/src/...。仓库里已经有 tauri-v3.0.0-alpha.* 的 tag，本卷不讲 3.x。

三条主线

全卷沿三条线展开，每页开头都会标出本页在哪条主线上。

启动主线：一个窗口加载出页面

fn main() {
  tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![greet])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

flowchart TB
  ctx["generate_context! 编译期"] --> bnew["Builder::new 生成 invoke key"]
  bnew --> bbuild["Builder::build"]
  bbuild --> wnew["Wry::new 建事件循环"]
  wnew --> run["App::run 进事件循环"]
  run --> ready["StartCause Init 变成 Ready"]
  ready --> setupfn["setup 按配置建窗口"]
  setupfn --> prep["prepare_pending_webview"]
  prep --> cw["create_webview 交给 wry"]
  cw --> wk["WKWebView 和 scheme handler"]
  wk --> load["请求 tauri://localhost"]
  load --> asset["get_asset 取内嵌资源"]

第 3 步和第 5 步的分界值得记住：build 返回时一个窗口也没有，窗口是在事件循环跑起来之后、在 Ready 的处理里建的，用户的 setup 钩子拿到的是已经建好的窗口。逐步的实验见一次启动。

调用主线：一次 invoke

#[tauri::command]
fn greet(name: &str) -> String {
  format!("hello, {name}")
}

const v = await window.__TAURI_INTERNALS__.invoke('greet', { name: 'rie' })

flowchart TB
  inv["invoke 登记两个回调 id"] --> pm["postMessage 发 fetch"]
  pm --> st["wry start_task"]
  st --> ipcget["ipc 协议 get"]
  ipcget --> parse["parse_invoke_request"]
  parse --> onmsg["Webview::on_message"]
  onmsg --> acl["invoke key 和 ACL"]
  acl --> handler["generate_handler 的分发"]
  handler --> wrap["command 包装函数"]
  wrap --> resolver["InvokeResolver"]
  resolver --> resp["HTTP 响应"]
  resp --> cbrun["runCallback 兑现 Promise"]

一次 invoke 在 Rust 侧走了哪些线程、JS 侧看到的请求和响应头各是什么，见一次 invoke。

事件主线：一次 emit

flowchart TB
  lis["JS listen"] --> lisinv["invoke plugin:event 的 listen"]
  lisinv --> ljs["Webview::listen_js"]
  ljs --> store["eval 记下 handlerId"]
  emitn["Rust app.emit"] --> amemit["AppManager::emit"]
  amemit --> tojs["emit_js 每个有监听的 webview"]
  tojs --> evaljs["eval 调分发函数"]
  evaljs --> runcb["runCallback handlerId"]
  amemit --> torust["再分发给 Rust 监听器"]

两点和直觉不同：没有监听器的 webview 收不到任何 eval；JS 侧的监听器比 Rust 侧的先被通知（指送出 eval 的先后，JS 什么时候执行由 webview 决定）。大块数据不要走事件，改用 Channel：它沿用 invoke 的回调 id，Rust 侧按 id 推送。

feature 与 cfg

tauri 的 feature

crates/tauri/Cargo.toml 的 [features] 里，和本卷有关的：

custom-protocol 怎么变成 cfg(dev)

custom-protocol 在 tauri 的 Cargo.toml 里只有一行：custom-protocol = ["tauri-macros/custom-protocol"]。它的效果是分三处落下去的：

1. tauri 自己的构建脚本。crates/tauri/build.rs 检查这个 feature，用 alias 给 tauri crate 自己发 cfg(custom_protocol) 或 cfg(dev)，另外打印一行 cargo:dev=<bool>。tauri 的 Cargo.toml 写着 links = "Tauri"，所以这一行会以环境变量 DEP_TAURI_DEV 的形式传给直接依赖 tauri 的 crate 的构建脚本。
2. 应用的构建脚本。tauri_build::build() 里的 try_build 读 DEP_TAURI_DEV（is_dev），给应用 crate 发 cfg(dev)，desktop / mobile 也是在这里发的。
3. 过程宏。tauri-macros 的 generate_context 用 cfg!(not(feature = "custom-protocol")) 决定生成开发还是发布的 Context：开发模式配了 devUrl 就不内嵌资源，CSP 优先用 devCsp。

实验 crate 分别带和不带 --features tauri/custom-protocol 编一次，两个构建脚本的输出（target/debug/build/*/output，只留 cfg 相关的行）：

# 带 custom-protocol
tauri 的构建脚本     cargo:rustc-cfg=custom_protocol
                     cargo:dev=false
                     cargo:rustc-cfg=desktop
应用的构建脚本       cargo:rustc-cfg=desktop

# 不带
tauri 的构建脚本     cargo:rustc-cfg=dev
                     cargo:dev=true
                     cargo:rustc-cfg=desktop
应用的构建脚本       cargo:rustc-cfg=desktop
                     cargo:rustc-cfg=dev

运行时的分叉看 cfg(dev)：get_app_url 在开发模式下返回 devUrl，发布模式下 frontendDist 是 URL 就用它，否则是 tauri://localhost；csp() 在开发模式下优先取 devCsp；mobile 的开发模式下 tauri 协议还会把请求代理到开发服务器。应用代码里也可以写 #[cfg(dev)]，tauri_build::is_dev 的文档就是这么推荐的。

本卷的模板没有配 devUrl。本卷的实验都带 custom-protocol 编译。写作时不带它的开发模式构建曾在 setup 之后无声退出（退出码 138），原因是实验机器的 DYLD_LIBRARY_PATH 让系统的 ImageIO 加载了另一份 libpng，和 tauri 无关，见常见坑 1。

debug 构建多出来的东西

debug_assertions 在 debug profile 下打开、release 下关闭。tauri 里和本卷有关的：

本卷展示输出时都会说明是 debug 还是 release；两者行为不同时两种都跑。

阅读路线

• 只想会用：读 01 全景；06 里的分发和参数与 InvokeResolver；07 里的权限、能力、作用域和运行时检查；遇到报错再查 09 常见坑。
• 想读懂实现：按顺序读。02 讲清楚编译期生成了什么之后，04、05 的运行时代码才好读；06 是全卷的重点。
• 只关心 webview 那一层：03 运行时，配合 dioxus 卷：dioxus-desktop 用的是同一套 wry 和 tao。
• 想自己写一个：读完 03 和 06，直接去 11 动手。

前置知识

• Rust 的 trait、泛型和关联类型：整个 tauri crate 对运行时泛型（R: Runtime），见 Runtime trait。
• async/await 和 tokio：async 命令和 tauri 协议的处理都跑在一个全局的 tokio 多线程运行时上，见 tokio 卷。
• http crate 的 Request / Response：自定义协议的请求和响应就是它们，见 hyper 卷。
• serde：命令参数从 JSON 反序列化、返回值序列化回 JSON，见 serde 卷。
• 前端：fetch、Promise、CORS 和 CSP 的基本概念。

小结

• 全卷对着 tauri 2.12.5、wry 0.57.1、tao 0.37.2 写，这是新项目写 tauri = "=2.12.5" 时解析出来的组合。
• 启动主线：generate_context! → Builder::new（invoke key）→ Builder::build（AppManager、Wry::new、核心插件，不建窗口）→ App::run → Ready → setup 建窗口 → prepare_pending_webview → create_webview → WKWebView → tauri://localhost → get_asset。
• 调用主线：invoke 登记回调 id → fetch POST ipc://localhost/<cmd> → start_task → parse_invoke_request → on_message（invoke key、ACL）→ 分发 → 包装函数 → InvokeResolver → HTTP 响应 → runCallback。
• 事件主线：listen 是一次 plugin:event|listen 调用；emit 先给有监听器的 webview eval，再通知 Rust 监听器。
• custom-protocol 经过 tauri 的构建脚本（cargo:dev）、应用的构建脚本（cfg(dev)）和过程宏三处生效，切换的是开发 / 发布模式，不是「注不注册 tauri://」。
• debug 构建多了 ACL 的详细拒绝信息、devtools、动态分发和低压缩级别；本卷两种行为不同时都跑。