configuring-tauri-permissions

Tauri 权限配置

本技能介绍 Tauri v2 权限系统，用于控制前端对后端命令和系统资源的访问。

权限系统概览

Tauri 中的权限是明确的特权，可授予或拒绝对特定命令的访问。它们构成前端代码与系统资源之间的安全边界。

核心组件

组件	用途
权限	定义对特定命令的访问权限
作用范围	将命令限制在特定路径/资源内
能力	将权限关联到窗口/webview
标识符	引用权限的唯一名称

安全模型

• 未获明确授权时，前端代码无法访问命令
• 拒绝规则始终优先于允许规则
• 权限必须关联到能力后才会生效
• 每个窗口/webview 可以拥有不同的权限

权限标识符

命名约定

格式：<plugin-name>:<permission-type>

模式	示例	说明
<name>:default	fs:default	默认权限集
<name>:allow-<command>	fs:allow-read-file	允许特定命令
<name>:deny-<command>	fs:deny-write-file	拒绝特定命令
<name>:allow-<scope>	fs:allow-app-read	允许使用预定义作用范围

标识符规则

• 仅限小写 ASCII 字母：[a-z]
• 最大长度：116 个字符
• 插件前缀（tauri-plugin-）会在编译时自动添加

目录结构

应用结构

src-tauri/
├── capabilities/
│   ├── default.json          # Main capability file
│   └── admin.toml            # Additional capabilities
├── permissions/
│   └── custom-permission.toml # Custom app permissions
└── tauri.conf.json

插件结构

tauri-plugin-example/
├── permissions/
│   ├── default.toml          # Default permission set
│   ├── autogenerated/        # Auto-generated from commands
│   │   └── commands/
│   └── custom-scope.toml     # Custom scopes
└── src/
    ├── commands.rs
    └── build.rs

能力配置

能力将权限关联到窗口，并定义前端上下文可以访问的内容。

JSON 格式（应用推荐）

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Main window permissions",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    "fs:allow-read-text-file",
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$APPDATA/*" }]
    }
  ]
}

TOML 格式

"$schema" = "../gen/schemas/desktop-schema.json"
identifier = "main-capability"
description = "Main window permissions"
windows = ["main"]
permissions = [
  "core:default",
  "fs:default",
  "fs:allow-read-text-file"
]

[[permissions]]
identifier = "fs:allow-write-text-file"
allow = [{ path = "$APPDATA/*" }]

窗口定位

{
  "identifier": "admin-capability",
  "windows": ["admin", "settings"],
  "permissions": ["fs:allow-write-all"]
}

使用 "*" 定位所有窗口：

{
  "windows": ["*"],
  "permissions": ["core:default"]
}

平台专属能力

{
  "identifier": "desktop-capability",
  "platforms": ["linux", "macOS", "windows"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read-recursive"]
}

{
  "identifier": "mobile-capability",
  "platforms": ["iOS", "android"],
  "windows": ["main"],
  "permissions": ["fs:allow-app-read"]
}

允许和拒绝列表

基本作用范围配置

{
  "identifier": "fs:allow-read-file",
  "allow": [
    { "path": "$HOME/Documents/*" },
    { "path": "$APPDATA/**" }
  ],
  "deny": [
    { "path": "$HOME/Documents/secrets/*" }
  ]
}

作用范围变量

变量	说明
$APP	应用安装目录
$APPCONFIG	应用配置目录
$APPDATA	应用数据目录
$APPLOCALDATA	应用本地数据目录
$APPCACHE	应用缓存目录
$APPLOG	应用日志目录
$HOME	用户主目录
$DESKTOP	桌面目录
$DOCUMENT	文档目录
$DOWNLOAD	下载目录
$RESOURCE	应用资源目录
$TEMP	临时目录

Glob 模式

模式	匹配内容
*	目录中的任意文件
**	递归匹配（所有子目录）
*.txt	扩展名为 .txt 的文件

拒绝优先级

拒绝规则始终优先于允许规则：

{
  "permissions": [
    {
      "identifier": "fs:allow-read-file",
      "allow": [{ "path": "$HOME/**" }],
      "deny": [{ "path": "$HOME/.ssh/**" }]
    }
  ]
}

插件权限

使用插件默认权限

{
  "permissions": [
    "fs:default",
    "shell:default",
    "http:default",
    "dialog:default"
  ]
}

常见插件权限模式

文件系统插件

{
  "permissions": [
    "fs:default",
    "fs:allow-read-text-file",
    "fs:allow-write-text-file",
    "fs:allow-app-read-recursive",
    "fs:allow-app-write-recursive",
    "fs:deny-default"
  ]
}

HTTP 插件

{
  "permissions": [
    "http:default",
    {
      "identifier": "http:default",
      "allow": [{ "url": "https://api.example.com/*" }],
      "deny": [{ "url": "https://api.example.com/admin/*" }]
    }
  ]
}

Shell 插件

{
  "permissions": [
    "shell:allow-open",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        { "name": "git", "cmd": "git", "args": true }
      ]
    }
  ]
}

特定目录的文件系统权限

权限	访问权限
fs:allow-appdata-read	读取 $APPDATA（非递归）
fs:allow-appdata-read-recursive	读取 $APPDATA（递归）
fs:allow-appdata-write	写入 $APPDATA（非递归）
fs:allow-appdata-write-recursive	写入 $APPDATA（递归）
fs:allow-home-read-recursive	读取 $HOME（递归）
fs:allow-temp-write	写入临时目录

自定义权限定义

TOML 权限文件

创建 src-tauri/permissions/my-permission.toml：

[[permission]]
identifier = "my-app:config-access"
description = "Access to app configuration files"
commands.allow = ["read_config", "write_config"]

[[scope.allow]]
path = "$APPCONFIG/*"

[[scope.deny]]
path = "$APPCONFIG/secrets.json"

权限集

将多个权限分组：

[[set]]
identifier = "my-app:full-access"
description = "Full application access"
permissions = [
  "my-app:config-access",
  "fs:allow-app-read-recursive",
  "fs:allow-app-write-recursive"
]

自动生成的命令权限

在插件的 src/build.rs 中：

const COMMANDS: &[&str] = &["get_user", "save_user", "delete_user"];

fn main() {
    tauri_plugin::Builder::new(COMMANDS)
        .build();
}

这会生成：

• allow-get-user / deny-get-user
• allow-save-user / deny-save-user
• allow-delete-user / deny-delete-user

默认权限集

创建 permissions/default.toml：

[default]
description = "Default permissions for my-plugin"
permissions = [
  "allow-get-user",
  "allow-save-user"
]

远程访问配置

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

{
  "identifier": "remote-capability",
  "windows": ["main"],
  "remote": {
    "urls": ["https://*.myapp.com"]
  },
  "permissions": [
    "core:default"
  ]
}

安全警告：Linux 和 Android 无法区分 iframe 请求与窗口请求。

tauri.conf.json 中的配置

通过标识符引用权限配置：

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

或直接内联权限配置：

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

故障排除

常见错误

“Not allowed on this command”

• 确认权限配置中包含该命令的权限
• 检查作用域是否包含目标路径
• 确保权限配置的目标窗口正确

未找到权限

• 检查标识符拼写（仅限小写）
• 确认已安装插件
• 运行 cargo build 以重新生成权限

权限调试

1. 检查生成的架构：src-tauri/gen/schemas/
2. 检查权限配置文件是否正确加载
3. 确认窗口名称与权限配置的目标一致
4. 检查拒绝规则是否阻止了访问

最佳实践

1. 最小权限原则：仅授予实际需要的权限
2. 使用具体作用域：优先使用 $APPDATA/*，而不是 $HOME/**
3. 拒绝访问敏感路径：始终拒绝访问 .ssh、凭据等内容
4. 分离权限配置：为不同类型的窗口使用不同的权限配置
5. 记录自定义权限：提供清晰的说明
6. 检查插件默认设置：了解默认权限授予了什么
7. 特定平台配置：针对操作系统的特定需求使用平台定向配置