diff --git a/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-0.svg b/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-0.svg new file mode 100644 index 000000000..03c0d9441 --- /dev/null +++ b/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-0.svg @@ -0,0 +1,191 @@ + + + + + + + + +WebviewFrontendCoreBackend Event Event + + + + + + diff --git a/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-1.svg b/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-1.svg new file mode 100644 index 000000000..5f002bab0 --- /dev/null +++ b/public/d2/docs/zh-cn/concept/Inter-Process Communication/index-1.svg @@ -0,0 +1,194 @@ + + + + + + + + +WebviewFrontendCoreBackendInvokeHandler IPC Request Invoke command Serialize return Response + + + + + + + + + diff --git a/public/d2/docs/zh-cn/concept/architecture-0.svg b/public/d2/docs/zh-cn/concept/architecture-0.svg new file mode 100644 index 000000000..d93a3e68c --- /dev/null +++ b/public/d2/docs/zh-cn/concept/architecture-0.svg @@ -0,0 +1,198 @@ + + + + + + + + +CoreUpstreamtauritauri-buildtauri-codegentauri-runtime-wryWRYTAOtauri-runtimetauri-macrostauri-utils + + + + + + + + + + + + + diff --git a/public/d2/docs/zh-cn/concept/process-model-0.svg b/public/d2/docs/zh-cn/concept/process-model-0.svg new file mode 100644 index 000000000..20963bf72 --- /dev/null +++ b/public/d2/docs/zh-cn/concept/process-model-0.svg @@ -0,0 +1,197 @@ + + + + + + + + +CoreEvents & Commands 1Events & Commands 2Events & Commands 3WebView1WebView2WebView3WebViewWebViewWebView + + + + + + + + + + + + diff --git a/src/content/docs/zh-cn/concept/Inter-Process Communication/index.mdx b/src/content/docs/zh-cn/concept/Inter-Process Communication/index.mdx new file mode 100644 index 000000000..2780c95c3 --- /dev/null +++ b/src/content/docs/zh-cn/concept/Inter-Process Communication/index.mdx @@ -0,0 +1,93 @@ +--- +title: 进程间通信 +sidebar: + label: 概述 + order: 1 + i18nReady: true +--- + +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +进程间通信(IPC)允许隔离的进程安全地进行通信,是构建更复杂应用程序的关键。 + +在以下指南中了解特定的 IPC 模式: + + + + + + +Tauri 使用一种特定风格的进程间通信,称为[异步消息传递],其中进程通过一些简单的数据表示交换*请求*和*响应*。对于任何有 Web 开发经验的人来说,消息传递应该听起来很熟悉,因为这种范式用于互联网的客户端-服务器通信。 + +消息传递是一种比共享内存或直接函数访问更安全的技术,因为接收方可以自由地拒绝或丢弃请求。例如,如果Tauri核心进程确定某个请求是恶意的,它将简单地丢弃该请求,并且不会执行相应的函数。 + +接下来,我们将更详细地解释 Tauri 的两个 IPC 原语——`事件`和`命令`。 + +## 事件 + +事件是一次性、单向的 IPC 消息,最适合用于通信生命周期事件和状态变化。与[命令](#命令)不同,事件可以由前端*和* Tauri 核心发出。 + +
+ +```d2 sketch pad=50 +shape: sequence_diagram + +Frontend: { + shape: rectangle + label: "Webview\nFrontend" +} +Core: { + shape: rectangle + label: "Core\nBackend" +} + +Frontend -> Core: "Event"{style.animated: true} +Core -> Frontend: "Event"{style.animated: true} +``` + +
在核心和 Webview 之间发送的事件。
+
+ +## 命令 + +Tauri 还提供了一种类似于[外部函数接口]的抽象,建立在IPC消息之上[^1]。主要 API `invoke` 类似于浏览器的`fetch` API,允许前端调用 Rust 函数、传递参数并接收数据。 + +由于该机制在底层使用类似 [JSON-RPC] 的协议来序列化请求和响应,因此所有参数和返回数据必须能够序列化为 JSON。 + +
+ +```d2 sketch pad=50 +shape: sequence_diagram + + +Frontend: { + label: "Webview\nFrontend" +} + +Core: { + label: "Core\nBackend" +} +InvokeHandler: { + label: "Invoke\nHandler" +} + +Frontend -> Core: "IPC Request"{style.animated: true} +Core -> InvokeHandler: "Invoke command"{style.animated: true} +InvokeHandler -> Core: "Serialize return"{style.animated: true} +Core -> Frontend: "Response"{style.animated: true} +``` + +
命令调用中涉及的 IPC 消息。
+
+ +[^1]: 由于命令在底层仍然使用消息传递,因此它们没有真实 FFI 接口所面临的安全隐患。 + +[异步消息传递]: https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing +[json-rpc]: https://www.jsonrpc.org +[外部函数接口]: https://en.wikipedia.org/wiki/Foreign_function_interface diff --git a/src/content/docs/zh-cn/concept/architecture.mdx b/src/content/docs/zh-cn/concept/architecture.mdx new file mode 100644 index 000000000..7669147ae --- /dev/null +++ b/src/content/docs/zh-cn/concept/architecture.mdx @@ -0,0 +1,186 @@ +--- +title: Tauri 结构 +sidebar: + order: 0 + i18nReady: true +--- + +## 介绍 + +Tauri 是一个多语言和通用工具包,非常可组合,允许工程师创建各种应用程序。它用于使用 Rust 工具和在Webview 中呈现的 HTML 构建桌面计算机应用程序。使用 Tauri 构建的应用程序可以与任意数量的可选 JS API 和Rust API一起发布,以便 Webview 可以通过消息传递控制系统。开发人员可以轻松扩展默认 API,以实现自己的功能,并在 Webview 和基于 Rust 的后端之间建立桥接。 + +Tauri 应用程序可以具有[托盘类型接口](/learn/system-tray/)。它们可以被[更新](/plugin/updater/),并按预期由用户的操作系统进行管理。由于使用了操作系统的 Webview,它们非常小。它们不附带运行时,因为最终的二进制文件是从 Rust 编译而来的。这使得[反向工程 Tauri 应用程序不是一项简单的任务](/security/)。 + +### Tauri 不是 + +Tauri 不是一个轻量级内核包装器。相反,它直接使用 [WRY](#wry) 和 [TAO](#tao) 来进行系统调用的重负载。 + +Tauri 不是虚拟机或虚拟化环境。相反,它是一个应用程序工具包,允许制作 Webview OS 应用程序。 + +## 核心生态系统 + +
+ +```d2 sketch pad=50 +direction: up + +Core: { + shape: rectangle + "tauri": { + "tauri-runtime" + "tauri-macros" + "tauri-utils" + } + + "tauri-build" + "tauri-codegen" + "tauri-runtime-wry" +} + +Upstream: { + shape: rectangle + direction: right + WRY + TAO +} + +Core."tauri"."tauri-runtime" -> Core."tauri-runtime-wry"{style.animated: true} + +Upstream.WRY -> Upstream.TAO{style.animated: true} +Core."tauri-runtime-wry" -> Upstream.Wry {style.animated: true} +``` + +
简化的 Tauri 架构图
+
+ +### tauri + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri) + +这是一个主要的 crate,将所有内容结合在一起。它将运行时、宏、工具和 API 整合成一个最终产品。它在编译时读取[`tauri.conf.json`](/reference/config/)文件,以引入功能并进行应用程序的实际配置(甚至是项目文件夹中的 `Cargo.toml` 文件)。它在运行时处理脚本注入(用于 polyfills / 原型修订),托管与系统交互的 API,甚至管理更新过程。 + +### tauri-runtime + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-runtime) + +Tauri 本身与底层 Webview 库之间的粘合层。 + +### tauri-macros + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-macros) + +通过利用 [`tauri-codegen`](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-codegen) crate 为上下文、处理程序和命令创建宏。 + +### tauri-utils + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-utils) + +在许多地方重复使用的通用代码,提供有用的工具,如解析配置文件、检测平台三元组、注入 CSP 和管理资产。 + +### tauri-build + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-build) + +在构建时应用宏,以设置 `cargo` 所需的一些特殊功能。 + +### tauri-codegen + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-codegen) + +嵌入、哈希和压缩资产,包括应用程序的图标以及系统托盘。在编译时解析[`tauri.conf.json`](/reference/config/)并生成 Config 结构。 + +### tauri-runtime-wry + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-runtime-wry) + +这个 crate 为 WRY 打开了直接的系统级交互,例如打印、监视器检测和其他与窗口相关的任务。 + +## Tauri 工具 + +### API (JavaScript / TypeScript) + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/packages/api) + +一个 TypeScript 库,为您创建 `cjs` 和 `esm` JavaScript 端点,以便您导入到前端框架中,以便 Webview 可以调用和监听后端活动。还以纯 TypeScript 的形式发布,因为对于某些框架来说,这更为优化。它利用 Webview 的消息传递与其主机进行通信。 + +### Bundler (Rust / Shell) + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-bundler) + +一个库,为其检测或被告知的平台构建 Tauri 应用程序。目前支持 macOS、Windows 和 Linux—但在不久的将来也将支持移动平台。可以在 Tauri 项目之外使用。 + +### cli.rs (Rust) + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/crates/tauri-cli) + +这个 Rust 可执行文件提供了 CLI 所需的所有活动的完整接口。它在 macOS、Windows 和 Linux 上运行。 + +### cli.js (JavaScript) + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri/tree/dev/packages/cli) + +围绕 [`cli.rs`](https://github.com/tauri-apps/tauri/blob/dev/crates/tauri-cli)的包装,使用 [`napi-rs`](https://github.com/napi-rs/napi-rs) 为每个平台生成 npm 包。 + +### create-tauri-app (JavaScript) + +[在 GitHub 上查看](https://github.com/tauri-apps/create-tauri-app) + +一个工具包,使工程团队能够快速搭建新的 `tauri-apps` 项目,使用他们选择的前端框架(只要它已被配置)。 + +## 上游 Crates + +Tauri-Apps 组织维护两个来自 Tauri 的“上游” crate,即 TAO 用于创建和管理应用程序窗口,WRY 用于与窗口内的 Webview 进行接口。 + +### TAO + +[在 GitHub 上查看](https://github.com/tauri-apps/tao) + +一个跨平台的应用程序窗口创建库,支持所有主要平台,如 Windows、macOS、Linux、iOS 和 Android。用 Rust 编写,它是 [winit](https://github.com/rust-windowing/winit) 的一个分支,我们根据自己的需要进行了扩展—例如菜单栏和系统托盘。 + +### WRY + +[在 GitHub 上查看](https://github.com/tauri-apps/wry) + +WRY 是一个跨平台的 WebView 渲染库,用 Rust 编写,支持所有主要桌面平台,如 Windows、macOS 和 Linux。Tauri 使用 WRY 作为抽象层,负责确定使用哪个 Webview(以及如何进行交互)。 + +## 其他工具 + +### tauri-action + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri-action) + +一个 GitHub 工作流,为所有平台构建 Tauri 二进制文件。甚至允许创建一个(非常基本的)Tauri 应用程序,即使没有设置 Tauri。 + +### tauri-vscode + +[在 GitHub 上查看](https://github.com/tauri-apps/tauri-vscode) + +这个项目增强了 Visual Studio Code 界面,提供了一些非常实用的功能。 + +### vue-cli-plugin-tauri + +[在 GitHub 上查看](https://github.com/tauri-apps/vue-cli-plugin-tauri) + +允许您在 vue-cli 项目中非常快速地安装 Tauri。 + +## 插件 + +[Tauri 插件指南](/develop/plugins/) + +一般来说,插件由第三方编写(尽管可能有官方支持的插件)。一个插件通常完成三件事: + +1. 使 Rust 代码能够“做某事”。 +2. 提供接口粘合,使其易于集成到应用程序中。 +3. 提供 JavaScript API,以便与 Rust 代码进行接口。 + +以下是一些 Tauri 插件的示例: + +- [tauri-plugin-fs](https://github.com/tauri-apps/tauri-plugin-fs) +- [tauri-plugin-sql](https://github.com/tauri-apps/tauri-plugin-sql) +- [tauri-plugin-stronghold](https://github.com/tauri-apps/tauri-plugin-stronghold) + +## 许可证 + +Tauri 本身根据 MIT 或 Apache-2.0 许可证授权。如果您重新打包并修改任何源代码,您有责任确保遵守所有上游许可证。Tauri 以“原样”提供,没有明确的适用性声明。 + +在这里,您可以浏览我们的[软件材料清单](https://app.fossa.com/projects/git%2Bgithub.com%2Ftauri-apps%2Ftauri)。 diff --git a/src/content/docs/zh-cn/concept/index.mdx b/src/content/docs/zh-cn/concept/index.mdx new file mode 100644 index 000000000..76ab1654b --- /dev/null +++ b/src/content/docs/zh-cn/concept/index.mdx @@ -0,0 +1,39 @@ +--- +title: 核心概念 +sidebar: + order: 0 + i18nReady: true + label: 概述 +--- + +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +Tauri 有多种主题被认为是核心概念,任何开发者在开发应用程序时都应该了解的事情。如果你想充分利用这个框架,这里有一些你应该更加熟悉的主题。 + + + + + + + + diff --git a/src/content/docs/zh-cn/concept/process-model.md b/src/content/docs/zh-cn/concept/process-model.md new file mode 100644 index 000000000..a6de83527 --- /dev/null +++ b/src/content/docs/zh-cn/concept/process-model.md @@ -0,0 +1,80 @@ +--- +title: 进程模型 +sidebar: + order: 0 + i18nReady: true +--- + +Tauri 采用了类似于 Electron 或许多现代网页浏览器的多进程架构。本指南探讨了这种设计选择背后的原因以及它为何对编写安全应用程序至关重要。 + +## 为什么使用多个进程? + +在图形用户界面(GUI)应用程序的早期阶段,通常使用单个进程来执行计算、绘制界面和响应用户输入。正如你可能猜到的,这意味着长时间运行的昂贵计算会使用户界面无响应,或者更糟糕的是,应用程序的一个组件发生故障会导致整个应用程序崩溃。 + +显然,需要一种更具弹性的架构,应用程序开始在不同的进程中运行不同的组件。这更好地利用了现代多核 CPU,并创造了更安全的应用程序。一个组件的崩溃不会再影响整个系统,因为组件在不同的进程中隔离开来。如果一个进程进入无效状态,我们可以轻松重启它。 + +我们还可以通过仅向每个进程分配最低限度的权限来限制潜在漏洞的影响范围,给予它们完成工作的足够权限。这种模式被称为[最小权限原则],在现实世界中你经常会看到。如果你请来一个园丁修剪你的树篱,你会给他们你的花园的钥匙。你不会给他们你房子的钥匙;他们为什么需要访问那个呢?同样的概念适用于计算机程序。我们给他们的访问权限越少,如果被攻破,他们造成的伤害就越小。 + +## 核心进程 + +每个 Tauri 应用程序都有一个核心进程,作为应用程序的入口点,并且是唯一一个拥有完全操作系统访问权限的组件。 + +核心的主要责任是利用该权限创建和协调应用程序窗口、系统托盘菜单或通知。Tauri 实现了必要的跨平台抽象,使这一过程变得简单。它还通过核心进程路由所有[进程间通信],允许你在一个中心位置拦截、过滤和操作 IPC 消息。 + +核心进程还应负责管理全局状态,例如设置或数据库连接。这使你能够轻松同步窗口之间的状态,并保护你的商业敏感数据免受前端窥探。 + +我们选择 Rust 来实现 Tauri,因为它的[所有权]概念在保证内存安全的同时保持了优异的性能。 + +
+ +```d2 sketch pad=50 +direction: right + +Core: { + shape: diamond +} + +"事件与命令 1": { + WebView1: WebView +} + +"事件与命令 2": { + WebView2: WebView +} + +"事件与命令 3": { + WebView3: WebView +} + +Core -> "事件与命令 1"{style.animated: true} +Core -> "事件与命令 2"{style.animated: true} +Core -> "事件与命令 3"{style.animated: true} + +"事件与命令 1" -> WebView1{style.animated: true} +"事件与命令 2" -> WebView2{style.animated: true} +"事件与命令 3" -> WebView3{style.animated: true} +``` + +
Tauri 进程模型的简化表示。一个核心进程管理一个或多个 WebView 进程。
+
+ +## WebView 进程 + +核心进程并不直接渲染实际的用户界面(UI);它启动 WebView 进程,这些进程利用操作系统提供的 WebView 库。WebView 是一个类似浏览器的环境,可以执行你的 HTML、CSS 和 JavaScript。 + +这意味着你在传统网页开发中使用的大多数技术和工具都可以用来创建 Tauri 应用程序。例如,许多 Tauri 示例是使用 [Svelte] 前端框架和 [Vite] 打包工具编写的。 + +安全最佳实践同样适用;例如,你必须始终清理用户输入,绝不要在前端处理机密信息,并且理想情况下将尽可能多的业务逻辑推迟到核心进程,以保持你的攻击面较小。 + +与其他类似解决方案不同,WebView 库**不**包含在你的最终可执行文件中,而是在运行时动态链接[^1]。这使你的应用程序*显著*更小,但也意味着你需要考虑平台差异,就像传统网页开发一样。 + +[^1]: 目前,Tauri 在 Windows 上使用 [Microsoft Edge WebView2],在 macOS 上使用 [WKWebView],在 Linux 上使用 [webkitgtk]。 + +[最小权限原则]: https://zh.wikipedia.org/wiki/%E6%9C%80%E5%B0%8F%E6%9D%83%E9%99%90%E5%8E%9F%E5%88%99 +[进程间通信]: /zh-cn/concept/inter-process-communication/ +[所有权]: https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html +[Microsoft Edge WebView2]: https://docs.microsoft.com/en-us/microsoft-edge/webview2/ +[WKWebView]: https://developer.apple.com/documentation/webkit/wkwebview +[webkitgtk]: https://webkitgtk.org +[Svelte]: https://svelte.dev/ +[Vite]: https://vitejs.dev/ diff --git a/src/content/docs/zh-cn/concept/size.mdx b/src/content/docs/zh-cn/concept/size.mdx new file mode 100644 index 000000000..ebfb68e9d --- /dev/null +++ b/src/content/docs/zh-cn/concept/size.mdx @@ -0,0 +1,71 @@ +--- +title: 应用程序大小 +sidebar: + order: 0 + i18nReady: true +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +虽然 Tauri 默认提供非常小的二进制文件,但稍微推一下极限也无妨,因此这里有一些技巧和建议,以达到最佳效果。 + +## Cargo 配置 + +您可以对项目进行的最简单的前端无关的大小优化之一是为其添加一个 Cargo 配置文件。 + +根据您使用的是 stable 还是 nightly 的 Rust 工具链,您可以使用的选项会有所不同。除非您是高级用户,建议您坚持使用稳定版工具链。 + + + +```toml +# src-tauri/Cargo.toml +[profile.dev] +incremental = true # 以较小的步骤编译您的二进制文件。 + +[profile.release] +codegen-units = 1 # 允许 LLVM 执行更好的优化。 +lto = true # 启用链接时优化。 +opt-level = "s" # 优先考虑小的二进制文件大小。如果您更喜欢速度,请使用 `3`。 +panic = "abort" # 通过禁用 panic 处理程序来提高性能。 +strip = true # 确保移除调试符号。 + +```` + + + +```toml +# src-tauri/Cargo.toml +[profile.dev] +incremental = true # 以较小的步骤编译您的二进制文件。 +rustflags = ["-Zthreads=8"] # 提高编译性能。 + +[profile.release] +codegen-units = 1 # 允许 LLVM 执行更好的优化。 +lto = true # 启用链接时优化。 +opt-level = "s" # 优先考虑小的二进制文件大小。如果您更喜欢速度,请使用 `3`。 +panic = "abort" # 通过禁用 panic 处理程序来提高性能。 +strip = true # 确保移除调试符号。 +trim-paths = "all" # 从您的二进制文件中移除潜在的特权信息。 +rustflags = ["-Cdebuginfo=0", "-Zthreads=8"] # 提高编译性能。 +```` + + + + +### 参考资料 + +:::note +这并不是所有可用选项的完整参考,只是我们想特别强调的几个选项。 +::: + +- [incremental:](https://doc.rust-lang.org/cargo/reference/profiles.html#incremental) 以较小的步骤编译您的二进制文件。 +- [codegen-units:](https://doc.rust-lang.org/cargo/reference/profiles.html#codegen-units) 以牺牲编译时间优化为代价,加快编译时间。 +- [lto:](https://doc.rust-lang.org/cargo/reference/profiles.html#lto) 启用链接时优化。 +- [opt-level:](https://doc.rust-lang.org/cargo/reference/profiles.html#opt-level) 确定编译器的关注点。使用 `3` 来优化性能,使用 `z` 来优化大小,使用 `s` 以达到两者之间的平衡。 +- [panic:](https://doc.rust-lang.org/cargo/reference/profiles.html#panic) 通过移除 panic unwind 来减少大小。 +- [strip:](https://doc.rust-lang.org/cargo/reference/profiles.html#strip) 从二进制文件中剥离符号或调试信息。 +- [rpath:](https://doc.rust-lang.org/cargo/reference/profiles.html#rpath) 通过将信息硬编码到二进制文件中,帮助找到二进制文件所需的动态库。 +- [trim-paths:](https://rust-lang.github.io/rfcs/3127-trim-paths.html) 从二进制文件中移除潜在的特权信息。 +- [rustflags:](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#profile-rustflags-option) 在每个配置文件的基础上设置 Rust 编译器标志。 + - `-Cdebuginfo=0`: 是否应在构建中包含调试信息符号。 + - `-Zthreads=8`: 增加编译期间使用的线程数。