功能

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.

功能是一组 permissions，通过各自的标签映射到应用窗口和 Web 视图。功能可以影响多个窗口和 Web 视图，并且可以在多个功能中引用这些窗口和 Web 视图。

¥Capabilities are a set of permissions mapped to application windows and webviews by their respective label. Capabilities can affect multiple windows and webviews and these can be referenced in multiple 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.

有关配置方案的完整参考，请参阅 references 部分。

¥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 enables default functionality for core plugins and the window.setTitle API.

{
  "$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.

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

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

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

{
  "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"
      ]
    }
  }
}

目标平台

¥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:

{
  "$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:

{
  "$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 App 附带的打包代码访问。为了允许远程源访问某些 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.

{
  "$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:

尽量减少前端妥协的影响

¥Minimize impact of frontend compromise
防止或减少本地系统接口和数据的（意外）暴露

¥Prevent or reduce (accidential) exposure of local system interfaces and data
防止或减少从前端到后端/系统的可能的权限升级

¥Prevent or reduce possible privilege escalation from frontend to backend/system

它不能防范什么？

¥What does it not protect against?

恶意或不安全的 Rust 代码

¥Malicious or insecure Rust code
范围和配置太宽松

¥Too lax scopes and configuration
命令实现中的范围检查不正确

¥Incorrect scope checks in the command implementation
有意绕过 Rust 代码

¥Intentional bypasses from Rust code
基本上任何在应用的 rust 核心中编写的内容

¥Basically anything which was written in the rust core of an application
系统 WebView 中 0 天或未修补的 1 天

¥0-days or unpatched 1-days in the system WebView
供应链攻击或其他受损的开发者系统

¥Supply chain attacks or otherwise compromised developer systems

架构文件

¥Schema Files

Tauri 使用你的应用可用的所有权限生成 JSON 模式，从而允许在你的 IDE 中自动补齐。要使用架构，请将配置中的 $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, allowing autocompletion in your IDE. To use a schema, set the $schema property in your configuration 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.