Back to Details

configuring-tauri-capabilities

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tauri Capabilities Configuration

Tauri Capabilities配置

Capabilities are Tauri's permission management system that granularly controls which APIs and commands the frontend can access. They define security boundaries by specifying which permissions apply to which windows or webviews.
Capabilities是Tauri的权限管理系统，可精细控制前端能够访问的API与命令。它们通过指定哪些权限适用于哪些窗口或Web视图来定义安全边界。

What Are Capabilities?

什么是Capabilities？

Capabilities serve as the bridge between permissions and windows/webviews. They:
  • Define which permissions are granted or denied for specific windows
  • Enable developers to minimize the impact of frontend compromises
  • Create security boundaries based on window labels (not titles)
  • Support platform-specific targeting (desktop vs mobile)
Capabilities充当权限与窗口/Web视图之间的桥梁，它们：
  • 定义为特定窗口授予或拒绝的权限
  • 帮助开发者将前端被攻陷的影响降至最低
  • 基于窗口标签（而非标题）创建安全边界
  • 支持特定平台的目标配置（桌面端 vs 移动端）

Capability File Location

Capabilities文件位置

Capability files reside in 
src-tauri/capabilities/
and use JSON or TOML format.
Capabilities文件存放于
src-tauri/capabilities/
目录下，支持JSON或TOML格式。

Capability File Structure

Capabilities文件结构

A capability file contains:
FieldRequiredDescription
identifier
YesUnique capability name
description
NoPurpose explanation
windows
YesTarget window labels (supports wildcards)
permissions
YesArray of allowed/denied operations
platforms
NoTarget platforms (linux, macOS, windows, iOS, android)
remote
NoRemote URL access configuration
$schema
NoReference to generated schema for IDE support
一个Capabilities文件包含以下内容：
字段是否必填描述
identifier
是唯一的Capabilities名称
description
否用途说明
windows
是目标窗口标签（支持通配符）
permissions
是允许/拒绝操作的数组
platforms
否目标平台（linux、macOS、windows、iOS、android）
remote
否远程URL访问配置
$schema
否用于IDE支持的生成式Schema引用

Basic Capability Example

基础Capabilities示例

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

Default Capabilities

默认Capabilities

All capabilities in 
src-tauri/capabilities/
are automatically enabled by default. No additional configuration is required.
To explicitly control which capabilities are active, configure them in 
tauri.conf.json
:
json
{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability"]
    }
  }
}
When explicitly configured, only the listed capabilities apply.
src-tauri/capabilities/
目录下的所有Capabilities默认会自动启用，无需额外配置。
若要显式控制启用哪些Capabilities，可在
tauri.conf.json
中进行配置：
json
{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability"]
    }
  }
}
当进行显式配置后，仅会应用列出的Capabilities。

Configuration Methods

配置方式

Method 1: Separate Files (Recommended)

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

Store individual capability files in the capabilities directory:
src-tauri/
  capabilities/
    main.json
    editor.json
    settings.json
Reference by identifier in 
tauri.conf.json
:
json
{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability", "settings-capability"]
    }
  }
}
将各个Capabilities文件存储在capabilities目录中：
src-tauri/
  capabilities/
    main.json
    editor.json
    settings.json
在
tauri.conf.json
中通过identifier引用：
json
{
  "app": {
    "security": {
      "capabilities": ["main-capability", "editor-capability", "settings-capability"]
    }
  }
}

Method 2: Inline Definition

方式2：内联定义

Embed capabilities directly in 
tauri.conf.json
:
json
{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "Capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "core:window:default"]
        }
      ]
    }
  }
}
直接在
tauri.conf.json
中嵌入Capabilities：
json
{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "my-capability",
          "description": "Capability used for all windows",
          "windows": ["*"],
          "permissions": ["fs:default", "core:window:default"]
        }
      ]
    }
  }
}

Method 3: Mixed Approach

方式3：混合方式

Combine file-based and inline capabilities:
json
{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "file-based-capability"
      ]
    }
  }
}
结合基于文件和内联的Capabilities：
json
{
  "app": {
    "security": {
      "capabilities": [
        {
          "identifier": "inline-capability",
          "windows": ["*"],
          "permissions": ["fs:default"]
        },
        "file-based-capability"
      ]
    }
  }
}

Per-Window Capabilities

按窗口配置Capabilities

Assign different permissions to different windows using window labels:
使用窗口标签为不同窗口分配不同权限：

Single Window

单个窗口

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

Multiple Specific Windows

多个特定窗口

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

Wildcard (All Windows)

通配符（所有窗口）

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

Pattern Matching

模式匹配

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

Permission Syntax

权限语法

Permissions follow a naming convention:
PatternDescription
<plugin>:default
Default permission set for a plugin
<plugin>:allow-<command>
Allow a specific command
<plugin>:deny-<command>
Deny a specific command
权限遵循以下命名约定：
模式描述
<plugin>:default
插件的默认权限集合
<plugin>:allow-<command>
允许执行特定命令
<plugin>:deny-<command>
拒绝执行特定命令

Core Permissions

核心权限

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

Plugin Permissions

插件权限

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

Platform-Specific Capabilities

特定平台Capabilities

Target specific platforms using the 
platforms
array.
使用
platforms
数组针对特定平台进行配置。

Desktop-Only Capability

仅桌面端Capabilities

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

Mobile-Only Capability

仅移动端Capabilities

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

Separate Files for Platform Variants

为不同平台创建独立文件

Create platform-specific capability files:
src-tauri/capabilities/desktop.json
:
json
{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}
src-tauri/capabilities/mobile.json
:
json
{
  "identifier": "mobile-features",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": ["haptics:default", "biometric:default"]
}
创建特定平台的Capabilities文件：
src-tauri/capabilities/desktop.json
：
json
{
  "identifier": "desktop-features",
  "windows": ["main"],
  "platforms": ["linux", "macOS", "windows"],
  "permissions": ["global-shortcut:default", "shell:default"]
}
src-tauri/capabilities/mobile.json
：
json
{
  "identifier": "mobile-features",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": ["haptics:default", "biometric:default"]
}

Remote API Access

远程API访问

Allow remote URLs to access Tauri commands (use with caution):
json
{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "permissions": ["http:default"]
}
允许远程URL访问Tauri命令（请谨慎使用）：
json
{
  "$schema": "../gen/schemas/remote-schema.json",
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.example.com"]
  },
  "permissions": ["http:default"]
}

Custom Capabilities Example

自定义Capabilities示例

A multi-window application with different permission levels:
src-tauri/capabilities/main.json
:
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
:
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
:
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"
  ]
}
一个拥有不同权限级别的多窗口应用：
src-tauri/capabilities/main.json
：
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
：
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
：
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"
  ]
}

Security Boundaries

安全边界

Capabilities protect against:
  • Frontend compromise impact
  • Unintended system interface exposure
  • Frontend-to-backend privilege escalation
Capabilities do NOT protect against:
  • Malicious Rust code
  • Overly permissive scopes
  • WebView vulnerabilities
Capabilities可防范以下风险：
  • 前端被攻陷后的影响范围
  • 意外暴露系统接口
  • 前端到后端的权限提升
Capabilities无法防范以下风险：
  • 恶意Rust代码
  • 过于宽松的权限范围
  • WebView漏洞

Best Practices

最佳实践

  1. Principle of Least Privilege: Grant only the permissions each window needs
  2. Separate Capabilities by Window: Create distinct capability files for different windows
  3. Use Descriptive Identifiers: Name capabilities clearly (e.g., 
    main-window
    , 
    editor-readonly
    )
  4. Document Capabilities: Include descriptions explaining the purpose
  5. Review Remote Access: Carefully audit any remote URL access configurations
  6. Test Permission Boundaries: Verify windows cannot access unpermitted APIs
  1. 最小权限原则：仅为每个窗口授予所需的权限
  2. 按窗口分离Capabilities：为不同窗口创建独立的Capabilities文件
  3. 使用描述性标识符：为Capabilities赋予清晰的名称（例如
    main-window
    、
    editor-readonly
    ）
  4. 文档化Capabilities：添加描述说明其用途
  5. 审核远程访问：仔细审查所有远程URL访问配置
  6. 测试权限边界：验证窗口无法访问未被授权的API

Schema Support

Schema支持

Generated schemas provide IDE autocompletion. Reference them in capability files:
json
{
  "$schema": "../gen/schemas/desktop-schema.json"
}
Available schemas after build:
  • desktop-schema.json
    - Desktop platforms
  • mobile-schema.json
    - Mobile platforms
  • remote-schema.json
    - Remote access capabilities
生成的Schema可提供IDE自动补全功能，在Capabilities文件中引用：
json
{
  "$schema": "../gen/schemas/desktop-schema.json"
}
构建后可用的Schema：
  • desktop-schema.json
    - 桌面平台
  • mobile-schema.json
    - 移动平台
  • remote-schema.json
    - 远程访问Capabilities

Troubleshooting

故障排查

Permission Denied Errors

权限被拒绝错误

Check that the capability includes the required permission and targets the correct window label.
检查Capabilities是否包含所需权限，且目标窗口标签是否正确。

Capability Not Applied

Capabilities未生效

Verify the capability file is in 
src-tauri/capabilities/
or explicitly listed in 
tauri.conf.json
.
验证Capabilities文件是否位于
src-tauri/capabilities/
目录下，或是否在
tauri.conf.json
中被显式列出。

Window Label Mismatch

窗口标签不匹配

Window labels in capabilities must match the labels defined when creating windows in Rust code. Labels are case-sensitive.
Capabilities中的窗口标签必须与Rust代码中创建窗口时定义的标签一致，标签区分大小写。