授权配置
Tauri 为应用和插件开发者提供了一套授权配置(capability)系统,用于精细控制运行在系统 WebView 中的应用前端对核心功能的访问。
授权配置规定了向哪些窗口或 WebView 授予或拒绝哪些 权限。
一份授权配置可以作用于多个窗口和 WebView,而同一个窗口或 WebView 也可以同时关联多份授权配置。
授权配置文件可以使用 JSON 或 TOML 格式定义,并存放在 src-tauri/capabilities 目录中。
推荐将各份授权配置分别定义在独立文件中,并在 tauri.conf.json 中仅通过标识符引用它们。
当然,也可以直接在 capabilities 字段中定义授权配置。
默认情况下,capabilities 目录中的所有授权配置都会自动启用。
一旦在 tauri.conf.json 中显式启用了授权配置,应用构建时就只会使用其中指定的授权配置。
有关完整的配置结构,请参阅 配置参考。
下面的 JSON 示例定义了一份授权配置,允许主窗口使用核心插件的默认功能以及 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 配置 文件。
这可能是最常见的配置方式:将各份授权配置直接内联到配置中,而权限仅通过标识符引用。
这种方式要求 capabilities 目录中已经存在定义完整的授权配置文件。
{ "app": { "security": { "capabilities": ["my-capability", "main-capability"] } }}内联授权配置也可以与预先定义的授权配置混合使用。
{ "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" ] } }}默认情况下,应用中的所有窗口和 WebView 都可以调用通过
tauri::Builder::invoke_handler
函数注册的命令。
如果需要改变这一行为,可以考虑使用
AppManifest::commands。
fn main() { tauri_build::try_build( tauri_build::Attributes::new() .app_manifest(tauri_build::AppManifest::new().commands(&["your_command"])), ) .unwrap();}可以通过定义 platforms 数组,让授权配置仅应用于特定平台。
默认情况下,授权配置会应用于所有目标平台,
但你也可以只选择 linux、macOS、windows、iOS 和 android 中的部分平台。
例如,下面定义了一份适用于桌面操作系统的授权配置。 请注意,它启用了仅在桌面端可用的插件权限:
{ "$schema": "../gen/schemas/desktop-schema.json", "identifier": "desktop-capability", "windows": ["main"], "platforms": ["linux", "macOS", "windows"], "permissions": ["global-shortcut:allow-register"]}下面则是一个适用于移动端的授权配置示例。 请注意,它启用了仅在移动端可用的插件权限:
{ "$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 访问
Section titled “远程 API 访问”默认情况下,只有随 Tauri 应用一同打包的代码才能访问 API。 如果需要允许远程来源访问特定的 Tauri 命令,可以在授权配置文件中进行定义。
下面的示例允许 tauri.app 所有子域名的页面扫描 NFC 标签并使用条形码扫描器。
{ "$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"]}它能够防范什么?
根据所配置的权限和授权配置,它可以:
- 尽量降低前端遭到入侵后的影响
- 避免或减少本地系统接口和数据的(意外)暴露
- 避免或降低从前端向后端或系统进行权限提升的可能性
它无法防范什么?
- 恶意或不安全的 Rust 代码
- 过于宽松的作用域和配置
- 命令实现中不正确的作用域检查
- Rust 代码有意绕过安全限制
- 应用 Rust 核心代码中的几乎所有问题
- 系统 WebView 中的 0-day 漏洞或尚未修补的 1-day 漏洞
- 供应链攻击或开发者系统以其他方式遭到入侵
Schema 文件
Section titled “Schema 文件”Tauri 会通过 tauri-build 生成 JSON Schema 文件,
其中包含应用可用的所有权限,以便 IDE 提供自动补全。
若要使用 Schema,请将配置文件(.json 或 .toml)中的
$schema 属性设置为 gen/schemas 目录下对应平台的 Schema。
通常应将其设置为 ../gen/schemas/desktop-schema.json
或 ../gen/schemas/mobile-schema.json,
不过你也可以为特定目标平台单独定义一份授权配置。
下面是一个 Tauri 应用目录结构的简化示例:
tauri-app├── index.html├── package.json├── src/├── src-tauri/│ ├── Cargo.toml│ ├── capabilities/│ │ └── <identifier>.json/toml│ ├── src/│ ├── tauri.conf.json所有配置都可以直接写入 tauri.conf.json 中,
但配置稍微复杂一些,就会使该文件变得臃肿。
这种设计旨在尽可能抽象出权限细节,让配置更易于理解。
完整的核心权限列表请参见 核心权限 页面。
© 2026 Tauri Contributors. CC-BY / MIT