用途
Capabilities 是 Tauri 的权限管理系统，用于精细控制前端可以访问哪些 API 和命令。它通过指定哪些权限应用于哪些窗口或 WebView 来定义安全边界，帮助开发者将前端被攻破时的影响降到最低。
主要能力
Capabilities 作为权限与窗口/WebView 之间的桥梁，可以：
- 定义针对特定窗口授予或拒绝哪些权限
- 基于窗口标签（而非标题）创建安全边界
- 支持平台特定目标（桌面端与移动端）
能力文件位置与结构
能力文件位于 src-tauri/capabilities/，使用 JSON 或 TOML 格式。文件包含以下字段：
| 字段 | 是否必需 | 说明 |
|---|---|---|
| identifier | 是 | 唯一能力名称 |
| description | 否 | 用途说明 |
| windows | 是 | 目标窗口标签（支持通配符） |
| permissions | 是 | 允许/拒绝的操作数组 |
| platforms | 否 | 目标平台（linux、macOS、windows、iOS、android） |
| remote | 否 | 远程 URL 访问配置 |
| $schema | 否 | 生成的 schema 引用，用于 IDE 支持 |
基础示例（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"
]
}
默认情况下，src-tauri/capabilities/ 中的所有能力都会自动启用，无需额外配置。若要显式控制启用哪些能力，可在 tauri.conf.json 中配置：
{
"app": {
"security": {
"capabilities": ["main-capability", "editor-capability"]
}
}
}
显式配置后，只有列出的能力会生效。
使用方式
配置方法
方法一：独立文件（推荐）
将各个能力文件存放在 capabilities 目录中，并在 tauri.conf.json 中按 identifier 引用：
{
"app": {
"security": {
"capabilities": ["main-capability", "editor-capability", "settings-capability"]
}
}
}
方法二：内联定义
直接在 tauri.conf.json 中嵌入能力：
{
"app": {
"security": {
"capabilities": [
{
"identifier": "my-capability",
"description": "Capability used for all windows",
"windows": ["*"],
"permissions": ["fs:default", "core:window:default"]
}
]
}
}
}
方法三：混合方式
结合基于文件与内联的能力：
{
"app": {
"security": {
"capabilities": [
{
"identifier": "inline-capability",
"windows": ["*"],
"permissions": ["fs:default"]
},
"file-based-capability"
]
}
}
}
按窗口分配能力
使用窗口标签为不同窗口分配不同权限：
- 单窗口：
"windows": ["main"] - 多个指定窗口：
"windows": ["editor", "preview"] - 通配符（所有窗口）：
"windows": ["*"] - 模式匹配：
"windows": ["dialog-*"]
权限语法
权限遵循命名约定：
| 模式 | 说明 |
|---|---|
<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"
]
}
平台特定能力
使用 platforms 数组指定目标平台。
仅桌面端：
{
"$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"
]
}
仅移动端：
{
"$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"
]
}
也可为平台变体创建独立文件，例如 src-tauri/capabilities/desktop.json 与 src-tauri/capabilities/mobile.json。
远程 API 访问
允许远程 URL 访问 Tauri 命令（需谨慎使用）：
{
"$schema": "../gen/schemas/remote-schema.json",
"identifier": "remote-capability",
"windows": ["main"],
"remote": {
"urls": ["https://*.example.com"]
},
"permissions": ["http:default"]
}
自定义能力示例
多窗口应用可按窗口设置不同权限级别，例如主窗口拥有完整访问权限，设置窗口权限受限，预览窗口为只读访问。
适用场景
- 需要为多窗口应用设置差异化权限边界
- 需要针对桌面端与移动端分别配置权限
- 需要限制前端可访问的系统接口，降低前端被攻破的影响
- 需要为远程 URL 配置受控的 API 访问
限制
Capabilities 可以防护：前端被攻破的影响、非预期的系统接口暴露、前端到后端的权限提升。
Capabilities 不能防护：恶意的 Rust 代码、过于宽松的 scope、WebView 漏洞。
最佳实践
- 最小权限原则：只授予每个窗口所需的权限
- 按窗口分离能力：为不同窗口创建独立的能力文件
- 使用描述性标识符：清晰命名能力（如 main-window、editor-readonly）
- 记录能力：包含说明用途的 description
- 审查远程访问：仔细审计任何远程 URL 访问配置
- 测试权限边界：验证窗口无法访问未授权的 API
Schema 支持
生成的 schema 提供 IDE 自动补全，可在能力文件中引用：
{
"$schema": "../gen/schemas/desktop-schema.json"
}
构建后可用 schema：desktop-schema.json（桌面平台）、mobile-schema.json（移动平台）、remote-schema.json（远程访问能力）。
故障排查
- 权限被拒绝错误：检查能力是否包含所需权限并指向正确的窗口标签
- 能力未生效：确认能力文件位于
src-tauri/capabilities/或在tauri.conf.json中显式列出 - 窗口标签不匹配：能力中的窗口标签必须与 Rust 代码中创建窗口时定义的标签一致，标签区分大小写