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

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

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

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

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

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

[[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 权限的能力可以概括为以下几点：

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

三、权限标识符规则

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

命名格式

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

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

字符与长度限制

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

constIDENTIFIER_SEPARATOR:u8=b':';constPLUGIN_PREFIX:&str="tauri-plugin-";constMAX_LEN_PREFIX:usize=64-PLUGIN_PREFIX.len();// 51constMAX_LEN_BASE:usize=64;constMAX_LEN_IDENTIFIER:usize=MAX_LEN_PREFIX+1+MAX_LEN_BASE;// 116

四、配置文件结构

插件的目录结构

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

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

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

应用的目录结构

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

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 目录

# 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. 命令权限：开放所有文件读取命令

# 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. 单命令权限：允许创建目录

# 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 文件中统一引用。

应用层扩展插件权限

# 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>，例如：

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

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

八、最佳实践建议

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

总结

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

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

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