Tauri 权限系统从零掌握 Permissions 与 Capabilities

一、什么是 Tauri 权限（Permissions）？

在 Tauri 中，权限（Permission） 是对命令（Command）访问特权的显式描述。它定义了：

哪些命令可以被调用（allow / deny）
命令可以操作的作用域（Scope） ，例如文件路径白名单/黑名单
多个权限的组合，形成更高层次的权限集

权限的核心作用是：将前端 WebView 对系统资源的访问限制在一个明确、可审计的范围内，避免恶意代码或意外操作对用户系统造成危害。

一个基础的权限配置示例如下：

lua 复制代码

[[permission]]
identifier = "my-identifier"
description = "This describes the impact and more."
commands.allow = [
    "read_file"
]

[[scope.allow]]
my-scope = "$HOME/*"

[[scope.deny]]
my-scope = "$HOME/secret"

在这个例子中：

允许调用 read_file 命令
允许访问 $HOME 下的所有文件
但明确拒绝访问 $HOME/secret 目录

权限配置完成后，需要在 Capability（能力） 文件中引用它，才能真正作用于应用窗口或 WebView。

二、权限能做什么？

Tauri 权限的能力可以概括为以下几点：

启用或禁用前端可调用的命令：控制哪些 Tauri 命令（Rust 侧暴露的函数）可以被前端 JavaScript 调用。
绑定作用域（Scope）到命令：限制命令操作的范围，例如只允许读取特定目录下的文件。
组合多个权限为权限集（Permission Set） ：将多个细粒度权限打包，便于复用和管理。

三、权限标识符规则

权限的 identifier 字段遵循严格的命名规范：

命名格式

格式	含义
`<name>:default`	插件或应用的默认权限
`<name>:<command-name>`	针对某个具体命令的权限

注意：这里的 <name> 是插件 crate 名称去掉 tauri-plugin- 前缀后的部分，用于命名空间隔离，降低命名冲突的可能性。对于应用自身的命令，不需要加前缀。

Tauri 编译时会自动为插件标识符添加 tauri-plugin- 前缀，开发者无需手动指定。

字符与长度限制

标识符只允许使用 ASCII 小写字母 [a-z] ，且长度有严格上限（最大 116 字符），原因如下：

ini 复制代码

const IDENTIFIER_SEPARATOR: u8 = b':';
const PLUGIN_PREFIX: &str = "tauri-plugin-";

const MAX_LEN_PREFIX: usize = 64 - PLUGIN_PREFIX.len();  // 51
const MAX_LEN_BASE: usize = 64;
const MAX_LEN_IDENTIFIER: usize = MAX_LEN_PREFIX + 1 + MAX_LEN_BASE;  // 116

四、配置文件结构

插件的目录结构

作为插件开发者 ，权限文件放置在插件项目的 permissions/ 目录下：

csharp 复制代码

tauri-plugin/
├── README.md
├── src/
│  └── lib.rs
├── build.rs
├── Cargo.toml
└── permissions/
   ├── <identifier>.json  # 或 .toml
   └── default.json       # 默认权限（特殊处理）

特别说明 ：default 权限文件会被 Tauri CLI 在添加插件时自动加入应用配置，无需手动引用。

应用的目录结构

作为应用开发者 ，除了 permissions/ 目录，还需要维护 capabilities/ 目录：

css 复制代码

tauri-app/
├── index.html
├── package.json
├── src/
└── src-tauri/
    ├── Cargo.toml
    ├── permissions/          # 权限定义（仅 TOML 格式）
    │  └── <identifier>.toml
    ├── capabilities/         # 能力配置（JSON/JSON5/TOML 均可）
    │  └── <identifier>.json
    ├── src/
    └── tauri.conf.json

格式区别 ：capabilities 文件支持 json、json5、toml 三种格式；而 permissions 文件只支持 toml 格式。

五、实战示例：文件系统插件权限

以 Tauri 官方文件系统（fs）插件为例，展示完整的权限配置方式。

1. 作用域权限：允许访问 HOME 目录

ini 复制代码

# plugins/fs/permissions/autogenerated/base-directories/home.toml

[[permission]]
identifier = "scope-home"
description = """This scope permits access to all files and
list content of top level directories in the `$HOME` folder."""

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

这个权限只定义了作用域，不开放任何命令，专门用于后续与命令权限组合使用。

2. 命令权限：开放所有文件读取命令

ini 复制代码

# plugins/fs/permissions/read-files.toml

[[permission]]
identifier = "read-files"
description = """This enables all file read related
commands without any pre-configured accessible paths."""
commands.allow = [
    "read_file",
    "read",
    "open",
    "read_text_file",
    "read_text_file_lines",
    "read_text_file_lines_next"
]

这个权限开放了一组读取相关命令，但没有限制路径范围，需要配合作用域权限使用。

3. 单命令权限：允许创建目录

ini 复制代码

# plugins/fs/permissions/autogenerated/commands/mkdir.toml

[[permission]]
identifier = "allow-mkdir"
description = "This enables the mkdir command."
commands.allow = [
    "mkdir"
]

六、权限集（Permission Set）：组合与复用

权限集（Permission Set） 是 Tauri 权限系统的强大特性，允许将多个权限合并为一个新的标识符，方便在 Capability 文件中统一引用。

应用层扩展插件权限

ini 复制代码

# my-app/src-tauri/permissions/home-read-extends.toml

[[set]]
identifier = "allow-home-read-extended"
description = """ This allows non-recursive read access to files and to create directories
in the `$HOME` folder.
"""
permissions = [
    "fs:read-files",    # 引用 fs 插件的读取命令权限
    "fs:scope-home",    # 引用 fs 插件的 HOME 作用域权限
    "fs:allow-mkdir"    # 引用 fs 插件的 mkdir 权限
]

通过权限集，我们将三个独立权限合并为 allow-home-read-extended，只需在 Capability 中引用这一个标识符，即可完整授予"在 HOME 目录下读取文件并创建目录"的能力。

权限集的典型应用场景

跨平台权限分组：将 Windows、macOS、Linux 各自的特定权限归组为操作系统级权限集
功能模块打包：将某个业务功能所需的所有权限打包为一个语义化的权限集
简化主配置文件：避免在 Capability 文件中罗列大量细粒度权限

七、权限引用规则总结

在引用插件权限时，格式为 <plugin-name>:<permission-identifier>，例如：

arduino 复制代码

fs:read-files          → 文件系统插件的 read-files 权限
fs:scope-home          → 文件系统插件的 scope-home 权限
fs:allow-mkdir         → 文件系统插件的 allow-mkdir 权限

对于应用自身定义的权限，直接使用 identifier 即可，无需前缀。

八、最佳实践建议

最小权限原则：只开放应用实际需要的命令，避免给予过于宽泛的权限。
作用域配合命令：不要只配置命令权限而不限制作用域，尤其是文件系统相关操作。
善用权限集：将相关权限打包为语义明确的权限集，提升配置可读性和可维护性。
利用 default 权限 ：插件开发者应提供合理的 default 权限，让应用开发者开箱即用。
显式拒绝敏感路径 ：在 scope.deny 中明确排除敏感目录（如 $HOME/secret、.ssh 等）。

总结

Tauri 的权限系统通过 Permission（权限） 、Scope（作用域） 、Permission Set（权限集） 和 Capability（能力） 四个层次，构建了一套完整、灵活且安全的访问控制体系。

权限定义"能做什么"
作用域定义"能操作哪些资源"
权限集负责复用和组合
Capability 将权限授予具体的窗口/WebView

理解并善用这套机制，是构建安全 Tauri 应用的基础。随着 Tauri 生态的不断完善，权限系统也会持续演进，建议关注官方文档获取最新信息。