configuring-tauri-capabilities

Tauri 权限配置

Capabilities 是 Tauri 的权限管理系统，可精细控制前端能访问哪些 API 和命令。它通过指定哪些权限适用于哪些窗口或 WebView 来定义安全边界。

什么是 Capabilities？

Capabilities 是连接权限与窗口/WebView 的桥梁。它们可以：

• 定义为特定窗口授予或拒绝哪些权限
• 帮助开发者将前端遭到入侵时的影响降至最低
• 根据窗口标签（而非标题）创建安全边界
• 支持按平台进行定向配置（桌面端与移动端）

Capability 文件位置

Capability 文件位于 src-tauri/capabilities/，使用 JSON 或 TOML 格式。

Capability 文件结构

Capability 文件包含：

字段	必填	说明
identifier	是	唯一的 capability 名称
description	否	用途说明
windows	是	目标窗口标签（支持通配符）
permissions	是	允许或拒绝的操作数组
platforms	否	目标平台（linux、macOS、windows、iOS、android）
remote	否	远程 URL 访问配置
$schema	否	对生成的 schema 的引用，用于 IDE 支持

基本 Capability 示例

创建 src-tauri/capabilities/main.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"
  ]
}

默认 Capabilities

src-tauri/capabilities/ 中的所有 capabilities 默认都会自动启用，无需额外配置。

如需明确控制启用哪些 capabilities，请在 tauri.conf.json 中配置：

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

显式配置后，仅应用列出的 capabilities。

配置方式

方式 1：使用独立文件（推荐）

将各个 capability 文件存放在 capabilities 目录中：

src-tauri/
  capabilities/
    main.json
    editor.json
    settings.json

在 tauri.conf.json 中通过 identifier 引用：

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

方式 2：内联定义

直接在 tauri.conf.json 中嵌入 capabilities：

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "Capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "core:window:default"]
        }
      ]
    }
  }
}

方式 3：混合方式

组合使用基于文件的 capabilities 和内联 capabilities：

{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "file-based-capability"
      ]
    }
  }
}

按窗口配置 Capabilities

使用窗口标签为不同窗口分配不同的权限：

单个窗口

{
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": ["core:window:default", "fs:default"]
}

多个指定窗口

{
  "identifier": "editor-capability",
  "windows": ["editor", "preview"],
  "permissions": ["fs:read-files", "core:event:default"]
}

通配符（所有窗口）

{
  "identifier": "global-capability",
  "windows": ["*"],
  "permissions": ["core:event:default"]
}

模式匹配

{
  "identifier": "dialog-capability",
  "windows": ["dialog-*"],
  "permissions": ["core:window:allow-close"]
}

权限语法

权限遵循以下命名约定：

模式	说明
<plugin>:default	插件的默认权限集
<plugin>:allow-<command>	允许特定命令
<plugin>:deny-<command>	拒绝特定命令

核心权限

{
  "permissions": [
    "core:path:default",
    "core:event:default",
    "core:window:default",
    "core:window:allow-set-title",
    "core:window:allow-close",
    "core:app:default",
    "core:resources:default",
    "core:menu:default",
    "core:tray:default"
  ]
}

插件权限

{
  "permissions": [
    "fs:default",
    "fs:allow-read-file",
    "fs:allow-write-file",
    "shell:allow-open",
    "dialog:allow-open",
    "dialog:allow-save",
    "http:default",
    "clipboard-manager:allow-read",
    "clipboard-manager:allow-write"
  ]
}

平台专属 Capabilities

使用 platforms 数组针对特定平台。

仅桌面端的 Capability

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

仅移动端的 Capability

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

为不同平台版本创建独立文件

创建平台专属的 capability 文件：

src-tauri/capabilities/desktop.json：

{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}

src-tauri/capabilities/mobile.json：

{
  "identifier": "mobile-features",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": ["haptics:default", "biometric:default"]
}

远程 API 访问

允许远程 URL 访问 Tauri 命令（请谨慎使用）：

{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "permissions": ["http:default"]
}

自定义 Capabilities 示例

一个具有不同权限级别的多窗口应用：

src-tauri/capabilities/main.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-window",
  "description": "Full access for main application window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "shell:allow-open",
    "dialog:default",
    "http:default",
    "clipboard-manager:default"
  ]
}

src-tauri/capabilities/settings.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "settings-window",
  "description": "Limited access for settings window",
  "windows": ["settings"],
  "permissions": [
    "core:window:allow-close",
    "core:event:default",
    "fs:allow-read-file",
    "fs:allow-write-file"
  ]
}

src-tauri/capabilities/preview.json：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "preview-window",
  "description": "Read-only access for preview window",
  "windows": ["preview"],
  "permissions": [
    "core:window:default",
    "core:event:default",
    "fs:allow-read-file"
  ]
}

安全边界

Capabilities 可防范：

• 前端遭到入侵时的影响
• 意外暴露系统接口
• 前端到后端的权限提升

Capabilities 无法防范：

• 恶意 Rust 代码
• 权限范围过于宽泛
• WebView 漏洞

最佳实践

1. 最小权限原则：仅授予每个窗口所需的权限
2. 按窗口划分能力：为不同窗口创建独立的能力文件
3. 使用描述性标识符：清晰地命名能力（例如，main-window、editor-readonly）
4. 记录能力：添加说明，阐明其用途
5. 检查远程访问：仔细审核任何远程 URL 访问配置
6. 测试权限边界：确认窗口无法访问未授权的 API

架构支持

生成的架构可提供 IDE 自动补全。在能力文件中引用它们：

{
  "$schema": "../gen/schemas/desktop-schema.json"
}

构建后可用的架构：

• desktop-schema.json - 桌面平台
• mobile-schema.json - 移动平台
• remote-schema.json - 远程访问能力

故障排除

权限被拒绝错误

检查能力是否包含所需权限，并且是否面向正确的窗口标签。

能力未生效

确认能力文件位于 src-tauri/capabilities/ 中，或已在 tauri.conf.json 中明确列出。

窗口标签不匹配

能力中的窗口标签必须与 Rust 代码创建窗口时定义的标签一致。标签区分大小写。