• 桌面应用
• 跨平台
• 移动开发

导读：Isolation Pattern 是 Tauri 框架内置的一种安全通信模式，它将所有前端到 Rust 后端的 IPC 消息强制路由到一个由开发者掌控的沙箱<iframe>中，经过校验、过滤、加密后才放行到核心层，从而在“不可信前端”（例如加载了第三方脚本的应用页面）与后端能力之间竖起一道纵深防线。本文以仓库中 examples/isolation 示例为骨架，结合tauri、tauri-utils、tauri-codegen的源码实现，完整讲解隔离模式的配置方法、目录结构、钩子函数契约、消息加解密调用链与测试验证，帮助你把这套机制真正落地到自己的项目里。

一、隔离模式是什么：一条“绕行”的 IPC 通路

在默认的Brownfield（棕地）模式下，前端通过window.__TAURI_INTERNALS__.postMessage(message)直接把调用消息交给 Rust 核心，两者之间没有中间层。一旦前端页面被注入恶意脚本，攻击者就可以直接调用后端命令。

Isolation（隔离）模式则强制插入一个中间层：所有 IPC 消息先被送往一个由你完全掌控、托管在沙箱 iframe 中的“安全应用”，由其中的window.__TAURI_ISOLATION_HOOK__函数完成校验与清洗，再用 AES-256-GCM 加密后送回主框架，最终才被 Rust 侧解密并执行。Rust 侧持有密钥，即使 iframe 本身被攻破，攻击者拿不到密钥也无法伪造合法消息。

源码中crates/tauri-utils/src/config.rs对该模式的官方描述是：“every IPC message is routed through a secure JavaScript application you own, hosted in a sandboxed<iframe>, so it can validate or reject messages before they reach the Rust core. This protects the core from an untrusted or compromised frontend … at the cost of an extra build step”（config.rs）。这里的“额外构建步骤”指的就是：你必须额外提供一个隔离应用目录，并让配置中的dir指向它。

二、运行官方示例：一条命令启动隔离模式应用

仓库中的examples/isolation是一个极简但完整的隔离模式参考实现，其 README 给出了唯一的启动方式：

cargo run --example isolation --features isolation

命令必须在仓库根目录执行，其中：

• --example isolation指向 Cargo.toml 中注册的示例目标：path = "../../examples/isolation/main.rs"；
• --features isolation开启tauricrate 的isolation特性，该特性会联动开启tauri-utils/isolation、tauri-macros/isolation并引入uuid依赖（Cargo.toml）。

示例应用本身非常简单（main.rs）：

#[tauri::command] fn ping() { println!("ping: {:?}", std::time::Instant::now()); } fn main() { tauri::Builder::default() .invoke_handler(tauri::generate_handler![ping]) .run(tauri::generate_context!( "../../examples/isolation/tauri.conf.json" )) .expect("error while running tauri application"); }

注意generate_context!传入的是仓库根目录相对的配置文件路径，这正是隔离模式“额外构建步骤”的入口：编译期宏（tauri-codegen）会读取该配置，扫描隔离应用目录并把它嵌入二进制。

三、配置详解：tauri.conf.json中的隔离模式开关

隔离模式完全通过app.security.pattern配置项启用，示例配置见 tauri.conf.json：

{ "app": { "withGlobalTauri": true, "windows": [ { "title": "Isolation", "width": 800, "height": 600, "resizable": true, "fullscreen": false } ], "security": { "csp": "default-src blob: data: filesystem: ws: wss: http: https: tauri: 'unsafe-eval' 'unsafe-inline' 'self' img-src: 'self'; connect-src ipc: http://ipc.localhost", "pattern": { "use": "isolation", "options": { "dir": "isolation-dist" } } } } }

关键点逐项说明：

模式配置会直接影响构建产物：

1. PatternKind::Isolation通过AppConfig::features()自动向 Cargo 注入isolation特性（config.rs），因此使用tauri build/CLI 构建时无需手动加--features isolation；手动cargo run跑示例时才需要显式指定；
2. 若未开启isolation特性而配置里却写了 isolation 模式，代码生成阶段会静默降级为 Brownfield（config.rs、context.rs）——这是容易踩坑的细节：一定要确保特性开启；
3. 隔离模式启用后，dir目录不存在会直接 panic："The isolation application path is set to{dir:?}but it does not exist"（context.rs）；
4. 目录内的文件中若没有任何一处出现__TAURI_ISOLATION_HOOK__，构建也会 panic（context.rs），这是钩子函数存在的硬校验。

四、隔离应用目录：你需要自己写什么

示例的隔离应用只有两个文件：

• isolation-dist/index.html：只包含一个加载index.js的<script>标签，标题为Isolation Secure Script；
• isolation-dist/index.js：定义全局钩子函数：

window.__TAURI_ISOLATION_HOOK__ = (payload, options) => { console.log('hook', payload, options) return payload }

钩子函数契约

__TAURI_ISOLATION_HOOK__是隔离模式下唯一需要你实现的接口，其语义为：

• 入参payload：一条待发送的 IPC 消息对象，包含cmd（命令名）、callback、error、options与payload（真正的调用参数）字段；
• 入参options：扩展选项（示例中未使用）；
• 返回值：经校验/清洗后的 payload。返回undefined或抛错即可拒绝该消息，使其永远不会到达 Rust 后端。

隔离 iframe 侧的运行时脚本 isolation.js 中，payloadHandler会先检查event.origin !== origin与消息结构合法性，然后调用钩子：

if (typeof window.__TAURI_ISOLATION_HOOK__ === 'function') { // await even if it's not async so that we can support async ones data = await window.__TAURI_ISOLATION_HOOK__(data) }

因此钩子既可以写同步函数，也可以写 async 函数，返回值都会被await后再加密发送。

构建期自动改写

tauri-codegen在编译期会对隔离目录中的 HTML 做三类改写（context.rs）：

1. 注入一段 codegen 期的隔离脚本（inject_codegen_isolation_script，html2.rs）；
2. 把<script src="...">引用的外部脚本内联进 HTML（inline_isolation，html2.rs）——这是为规避 Windows 平台加载自定义 scheme 资源问题的临时方案，所以示例中index.html虽引用index.js，最终嵌入时会被合并；
3. 注入 CSP nonce 与脚本哈希（inject_script_hashes）。

正是由于构建期会扫描内联后的脚本内容，__TAURI_ISOLATION_HOOK__才能被上述硬校验检测到。

五、底层原理：消息如何被加密、解密与放行

5.1 运行时密钥与随机 scheme

隔离模式的加密体系由tauri-utils的pattern::isolation模块实现（isolation.rs）：

• Keys：包含一个 256 位 AES-GCM 密钥对（AesGcmPair），密钥通过getrandom（CSPRNG）生成 32 字节随机数；
• 加密流程：前端侧用 Web Crypto API 的AES-GCM加密，随机生成 12 字节 IV（nonce），payload 按内容类型分为application/json与application/octet-stream两种；
• 解密流程：Rust 侧收到{ nonce, payload, contentType }结构后，用同一把密钥解密，得到原始消息体。

密钥在编译期生成并嵌入二进制（Keys::new()，context.rs），运行时通过IsolationJavascriptRuntime模板注入到 iframe 脚本中（isolation.rs）。同时，隔离 iframe 使用随机生成的 scheme（形如isolation-<uuid>）而非固定协议名（embedded_assets.rs），配合每窗口随机key，显著提高了攻击者猜解消息通道的难度。

5.2 主框架侧：排队、转发与 ready 信号

主页面侧的核心逻辑位于 ipc.js：

• 所有 IPC 消息先进入window.__TAURI_INTERNALS__.ipc，根据pattern分流：brownfield直接postMessage，isolation则校验消息结构后排队等待；
• iframe 通过发送__TAURI_ISOLATION_READY__信号告知主框架自己已就绪，主框架随即清空队列逐条转发（sendIsolationMessage使用postMessage的 structuredClone 语义，并递归调用__TAURI_TO_IPC_KEY__序列化器处理 Map、Uint8Array 等类型）；
• iframe 侧发回的加密消息同样由主框架监听message事件识别（通过nonce/payload/contentType字段特征），再交给window.__TAURI_INTERNALS__.postMessage发给后端。

5.3 Rust 侧：按模式解密再派发

后端解析 IPC 请求时（protocol.rs），先检查当前Pattern是否为Isolation；若是，则要求请求体必须符合IsolationMessage结构，并用crypto_keys.decrypt(message.payload)解密，再按contentType还原为原始二进制或 JSON：

let is_raw = message.payload.content_type() == &mime::APPLICATION_OCTET_STREAM.to_string(); let payload = crypto_keys.decrypt(message.payload)?; // is_raw => InvokeBody::Raw，否则 serde_json::from_slice 解析为 Json

5.4 iframe 的托管与导航豁免

隔离 iframe 由 Tauri 通过自定义 URI scheme 协议处理器托管（protocol::isolation::get，isolation.rs）：仅处理index.html请求，注入运行时脚本与密钥后返回，并强制附加 CSPdefault-src 'none'; frame-src <isolation-scheme>。在 Windows 与 Android 上 scheme 形如http(s)://isolation-xxx.localhost，其余平台为isolation-xxx:（protocol/isolation.rs）。

同时，导航处理器对隔离 iframe 的 URL（scheme 匹配且域名为localhost，常量 ISOLATION_IFRAME_SRC_DOMAIN）做了无条件放行，并且不会向业务代码派发导航事件（manager/webview.rs）。

六、IPC 内容序列化：加密前的类型归一化

iframe 加密之前，消息体要经过 process-ipc-message-fn.js 归一化：ArrayBuffer、视图、数组按application/octet-stream原样传输；其余对象通过JSON.stringify处理，其中Map转为对象、Uint8Array/ArrayBuffer转为数组、带__TAURI_TO_IPC_KEY__方法的对象调用该方法自定义序列化。该函数同样被注入到隔离运行时模板中（PROCESS_IPC_MESSAGE_FN，manager/webview.rs），保证主页面与 iframe 两侧的序列化规则一致。

七、测试与验证：从源码确认机制可靠

隔离模式的加密链路在源码中有明确的单元测试支撑（ipc/protocol.rs）：

• 测试parse_invoke_request_isolation使用generate_context!加载仓库内 test/fixture/isolation/src-tauri/tauri.conf.json 的隔离配置，从编译产物中取出真实生成的crypto_keys；
• 用生成的密钥对vec![1, 41, 65, 12, 78]与一段 JSON 分别加密，构造{ nonce, payload, contentType }请求体；
• 断言 Rust 侧解析后能正确还原出InvokeBody::Raw与InvokeBody::Json，同时cmd、callback、error、invoke_key、Origin头均被正确提取。

此外 tauri-utils 的 isolation 模块 还有create_keys测试验证密钥生成，html2.rs 的测试验证构建期内联逻辑。若你怀疑自己的隔离应用配置有误，运行cargo test --features isolation -p tauri即可在本地复现这些链路。

八、在你的项目里启用隔离模式的完整步骤

结合以上分析，把隔离模式引入自己的 Tauri 项目只需四步：

1. 创建隔离应用目录（如isolation-dist/），包含index.html与若干 JS 文件，其中必须有文件定义window.__TAURI_ISOLATION_HOOK__；
2. 修改tauri.conf.json：在app.security.pattern下设置use: "isolation"、options.dir: "isolation-dist"，并收紧 CSP 到default-src 'self'等最小化策略（示例 CSP 可作为宽松起点，生产环境建议进一步收紧，勿保留'unsafe-eval'/'unsafe-inline'之类不必要的豁免）；
3. 实现钩子：在钩子里校验每条消息的cmd与payload，白名单之外的一律返回拒绝；
4. 构建：使用tauri dev/tauri build（CLI 会自动启用isolation特性），或手动cargo run --features isolation。

九、注意事项与已知边界

• 特性开关：直接跑cargo run --example isolation时若漏掉--features isolation，应用会静默退化为 Brownfield 模式，行为与预期不符且无报错；
• withGlobalTauri：示例开启了withGlobalTauri: true，隔离模式下window.__TAURI_INTERNALS__与 IPC 均由 Tauri 注入，使用@tauri-apps/api时其内部会感知__TAURI_PATTERN__（由 pattern.js 注入的深冻结对象）自动走隔离通道，业务代码无需区分；
• 性能开销：每条 IPC 消息都会多一次postMessage跳转与 AES-GCM 加解密，隔离模式是为安全敏感场景设计，普通应用保持默认 Brownfield 即可；
• iOS 特殊注意：若在 iOS 上同时开启 App-Bound Domains（limit_navigations_to_app_bound_domains），必须在WKAppBoundDomains中加入localhost，因为 Tauri 用该域名托管应用页面、IPC 协议与隔离 iframe（webview/mod.rs）。

十、延伸阅读

想继续深入，可以按以下路径阅读本仓库源码：

• 配置解析与模式枚举：crates/tauri-utils/src/config.rs
• 密钥生成与加解密实现：crates/tauri-utils/src/pattern/isolation.rs
• 主框架 IPC 分流与排队：crates/tauri/scripts/ipc.js
• iframe 侧运行时（钩子调用与加密）：crates/tauri-utils/src/pattern/isolation.js
• 构建期代码生成与校验：crates/tauri-codegen/src/context.rs
• iframe 协议托管：crates/tauri/src/protocol/isolation.rs
• 端到端加解密测试：crates/tauri/src/ipc/protocol.rs

隔离模式不是一把“万能锁”，而是 Tauri 提供的纵深防御中的一道关键闸门：它假定主页面可能被攻破，把最后的消息校验权牢牢握在开发者自己手中。对照官方示例跑通一次，再结合源码理解其加解密与排队机制，你就能在自己的安全敏感型应用（如涉及账号体系、文件系统、系统命令调用的桌面应用）中，把它作为默认防线落地。

• 桌面应用
• 跨平台
• 移动开发