功能

Tauri 为应用和插件开发者提供了一个能力系统，以便逐步启用和限制在系统 WebView 中运行的应用前端对核心的访问。

🌐 Tauri provides application and plugin developers with a capabilities system, to granually enable and constrain the core exposure to the application frontend running in the system WebView.

功能定义了哪些 权限 被授予或拒绝给哪些窗口或网页视图。

🌐 Capabilities define which permissions are granted or denied for which windows or webviews.

功能可以影响多个窗口和网页视图，并且这些可以在多个功能中被引用。

🌐 Capabilities can affect multiple windows and webviews and these can be referenced in multiple capabilities.

Security Tip

属于多个功能的窗口和 WebViews 实际上会合并所有相关功能的安全边界和权限。

🌐 Windows and WebViews which are part of more than one capability effectively merge the security boundaries and permissions of all involved capabilities.

功能文件可以定义为位于 src-tauri/capabilities 目录中的 JSON 或 TOML 文件。

🌐 Capability files are either defined as a JSON or a TOML file inside the src-tauri/capabilities directory.

将文件单独使用并仅通过标识符在 tauri.conf.json 中引用是良好的做法，但也可以直接在 capabilities 字段中定义它们。

🌐 It is good practice to use individual files and only reference them by identifier in the tauri.conf.json but it is also possible to define them directly in the capabilities field.

capabilities 目录中的所有功能默认都会自动启用。 一旦在 tauri.conf.json 中明确启用功能，应用构建中只会使用这些功能。

🌐 All capabilities inside the capabilities directory are automatically enabled by default. Once capabilities are explicitly enabled in the tauri.conf.json, only these are used in the application build.

有关配置方案的完整参考，请参见参考资料部分。

🌐 For a full reference of the configuration scheme please see the references section.

以下示例 JSON 定义了一个能力，该能力允许主窗口使用核心插件的默认功能和 window.setTitle API。

🌐 The following example JSON defines a capability that allows the main window use the default functionality of core plugins and the window.setTitle API.

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default",
    "core:window:allow-set-title"
  ]
}

这些代码片段是Tauri 配置文件的一部分。

🌐 These snippets are part of the Tauri configuration file.

这可能是最常见的配置方法，其中各个功能是内联的，只有权限是通过标识符引用的。

🌐 This is likely the most common configuration method, where the individual capabilities are inlined and only permissions are referenced by identifier.

这需要在 capabilities 目录中有明确定义的能力文件。

🌐 This requires well defined capability files in the capabilities directory.

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "capabilities": ["my-capability", "main-capability"]
    }
  }
}

内联功能可以与预定义功能混合使用。

🌐 Inline capabilities can be mixed with pre-defined capabilities.

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "My application capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "allow-home-read-extended"]
        },
        "my-second-capability"
      ]
    }
  }
}

默认情况下，在你的应用中注册的所有命令（使用 tauri::Builder::invoke_handler 函数）都允许应用的所有窗口和网页视图使用。要更改此设置，请考虑使用 AppManifest::commands。

🌐 By default, all commands that you registered in your app (using the tauri::Builder::invoke_handler function) are allowed to be used by all the windows and webviews of the app. To change that, consider using AppManifest::commands.

src-tauri/build.rs

fn main() {
    tauri_build::try_build(
        tauri_build::Attributes::new()
            .app_manifest(tauri_build::AppManifest::new().commands(&["your_command"])),
    )
    .unwrap();
}

目标平台

🌐 Target Platform

可以通过定义 platforms 数组使功能具有特定于平台的特性。默认情况下，该功能适用于所有目标，但你可以选择 linux、macOS、windows、iOS 和 android 目标的子集。

🌐 Capabilities can be platform-specific by defining the platforms array. By default the capability is applied to all targets, but you can select a subset of the linux, macOS, windows, iOS and android targets.

例如，桌面操作系统的功能。请注意，它启用了仅在桌面上可用的插件权限：

🌐 For example a capability for desktop operating systems. Note it enables permissions on plugins that are only available on desktop:

src-tauri/capabilities/desktop.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "desktop-capability",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:allow-register"]
}

另一个移动功能的示例。请注意，它会启用仅在移动设备上可用的插件权限：

🌐 And another example of a capability for mobile. Note it enables permissions on plugins that are only available on mobile:

src-tauri/capabilities/mobile.json

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    "nfc:allow-scan",
    "biometric:allow-authenticate",
    "barcode-scanner:allow-scan"
  ]
}

远程 API 访问

🌐 Remote API Access

默认情况下，API 仅对随 Tauri 应用打包的代码可访问。要允许远程来源访问某些 Tauri 命令，可以在能力配置文件中定义此项。

🌐 By default the API is only accessible to bundled code shipped with the Tauri App. To allow remote sources access to certain Tauri Commands it is possible to define this in the capability configuration file.

此示例将允许扫描 NFC 标签并使用来自 tauri.app 所有子域的条形码扫描器。

🌐 This example would allow to scan for NFC tags and to use the barcode scanner from all subdomains of tauri.app.

src-tauri/capabilities/remote-tags.json

{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-tag-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.tauri.app"]
  },
  "platforms": ["iOS", "android"],
  "permissions": ["nfc:allow-scan", "barcode-scanner:allow-scan"]
}

Caution

在 Linux 和 Android 上，Tauri 无法区分来自嵌入的 <iframe> 的请求和窗口本身的请求。

🌐 On Linux and Android, Tauri is unable to distinguish between requests from an embedded <iframe> and the window itself.

请非常仔细地考虑使用此功能，并在本功能的参考部分详细阅读有关你目标操作系统的具体安全影响。

🌐 Please consider usage of this feature very carefully and read more into the specific security implications for your targeted operating system in the reference section of this feature.

安全边界

🌐 Security Boundaries

它可以防护什么？

🌐 What does it protect against?

根据它能够拥有的权限和能力：

🌐 Depending on the permissions and capabilities it is able to:

• 尽量减少前端妥协的影响
• 防止或减少本地系统接口和数据的（意外）暴露
• 防止或减少从前端到后端/系统的可能的权限升级

它不能防护什么？

🌐 What does it not protect against?

• 恶意或不安全的 Rust 代码
• 范围和配置太宽松
• 命令实现中的范围检查不正确
• 有意绕过 Rust 代码
• 基本上任何在应用的 rust 核心中编写的内容
• 系统 WebView 中 0 天或未修补的 1 天
• 供应链攻击或其他受损的开发者系统

Security Tip

安全边界取决于窗口标签（而不是标题）。 我们建议仅将窗口创建功能暴露给高权限窗口。

🌐 The security boundaries are depending on window labels (not titles). We recommend to only expose of the window creation functionality to higher privileged windows.

架构文件

🌐 Schema Files

Tauri 通过 tauri-build 为你的应用生成包含所有可用权限的 JSON 模式，允许在你的 IDE 中进行自动补全。要使用模式，请在配置文件（.json 或 .toml）中将 $schema 属性设置为位于 gen/schemas 目录中的某个特定平台的模式。通常，你会将其设置为 ../gen/schemas/desktop-schema.json 或 ../gen/schemas/mobile-schema.json，尽管你也可以为特定目标平台定义功能。

🌐 Tauri generates JSON schemas with all the permissions available to your application through tauri-build, allowing autocompletion in your IDE. To use a schema, set the $schema property in your configuration file (either .json or .toml) to one of the platform-specific schemas located in the gen/schemas directory. Usually you will set it to ../gen/schemas/desktop-schema.json or ../gen/schemas/mobile-schema.json though you can also define a capability for a specific target platform.

配置文件

🌐 Configuration Files

Tauri 应用目录结构的简化示例：

🌐 Simplified example of an example Tauri application directory structure:

tauri-app
├── index.html
├── package.json
├── src/
├── src-tauri/
│   ├── Cargo.toml
│   ├── capabilities/
│   │  └── <identifier>.json/toml
│   ├── src/
│   ├── tauri.conf.json

所有内容都可以内联到 tauri.conf.json 中，但即使是稍微复杂一点的配置也会让这个文件变得臃肿，而这种方法的目标是尽可能抽象权限，并且易于理解。

🌐 Everything can be inlined into the tauri.conf.json but even a little more advanced configuration would bloat this file and the goal of this approach is that the permissions are abstracted away whenever possible and simple to understand.

核心权限

🌐 Core Permissions

所有核心权限的列表可以在 核心权限 页面上找到。

🌐 A list of all core permissions can be found on the Core Permissions page.