9 使用插件权限

4 分钟阅读

原文链接: https://tauri.app/learn/security/using-plugin-permissions/

本练习的目标是更好地理解插件权限如何启用或禁用、它们在哪里描述，以及如何使用插件的默认权限。

完成后，你将有能力查找并使用任意插件的权限，并理解如何按需定制已有权限。你还会得到一个使用了插件及插件特定权限的示例 Tauri 应用。

1. 创建 Tauri 应用

创建你的 Tauri 应用。在我们的示例中，我们使用 create-tauri-app：

pnpm create tauri-app

✔ Project name · plugin-permission-demo
✔ Choose which language to use for your frontend · TypeScript / JavaScript - (pnpm, yarn, npm, bun)
✔ Choose your package manager · pnpm
✔ Choose your UI template · Vanilla
✔ Choose your UI flavor · TypeScript

Template created! To get started run:
cd plugin-permission-demo
pnpm install
pnpm tauri dev

本分步说明中我们使用 pnpm，但你可以选择其它包管理器并在命令中相应替换。

2. 把 `file-system` 插件添加到你的应用

查找已有插件可以使用多种途径。

最直接的方式是看看你的插件是否已经在文档的插件部分，也就是属于 Tauri 维护的插件集。 Filesystem 插件属于 Tauri 插件工作区，你可以按照说明把它加入项目。

如果插件属于社区贡献，你搜索 tauri-plugin-<your plugin name> 时很可能能在 crates.io 上找到它。

如果它是我们工作区中已有的插件，你可以使用自动化方式：

pnpm tauri add fs

如果你是在 crates.io 上找到的，就需要手动把它添加为依赖并修改 Tauri builder 来初始化插件：

1
    cargo add tauri-plugin-fs

修改 lib.rs 以初始化插件：

1
2
3
4
5
6
fn run() {
  tauri::Builder::default()
    .plugin(tauri_plugin_fs::init())
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

3. 理解 `fs` 插件的默认权限

每个插件都有一个 default 权限集，其中包含开箱即用、以合理最小功能集使用该插件所需的全部权限与作用域。

对官方维护的插件，你可以在文档中找到渲染后的说明（例如 fs 默认权限）。

如果你面对的是社区插件，就需要查看插件的源代码。它应当定义在 your-plugin/permissions/default.toml 中。

"$schema" = "schemas/schema.json"

[default]
description = """
# Tauri `fs` 默认权限

此配置文件定义了授予文件系统的默认权限。

### 授予的权限

该默认权限集启用所有与读取相关的命令，并允许访问 `$APP` 文件夹及在其中创建的子目录。
`$APP` 文件夹的位置取决于应用运行所在的操作系统。

一般来说，`$APP` 文件夹需要由应用在运行时手动创建，之后才能访问其中的文件或文件夹。

### 拒绝的权限

该默认权限集默认阻止访问 Tauri 应用的关键组件。
在 Windows 上，webview 数据文件夹的访问会被拒绝。

"""
permissions = ["read-all", "scope-app-recursive", "deny-default"]

4. 找到正确的权限

这一步的核心是为你的命令找到所需权限，以便在对系统最小访问的前提下把它们暴露给前端。

fs 插件有自动生成的权限，可以禁用或启用单个命令，并允许或禁用全局作用域。

这些可以在文档中，或插件的源代码（fs/permissions/autogenerated）中找到。

假设我们想启用对用户 $HOME 文件夹中文本文件 test.txt 的写入。

为此我们要在自动生成的权限中寻找启用写入文本文件的权限，例如 allow-write-text-file，然后寻找一个允许我们访问 $HOME/test.txt 文件的作用域。

我们需要把它们加入 src-tauri/tauri.conf.json 的 capabilities 部分，或 src-tauri/capabilities/ 文件夹中的某个文件。默认情况下 src-tauri/capabilities/default.json 中已经有一个能力，我们可以修改它。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": [
    "main"
  ],
  "permissions": [
    "path:default",
    "event:default",
    "window:default",
    "app:default",
    "image:default",
    "resources:default",
    "menu:default",
    "tray:default",
    "shell:allow-open",
    "fs:default",
    "fs:allow-write-text-file",
  ]
}

由于 fs 插件中只有访问整个 $HOME 文件夹的自动生成作用域，我们需要配置自己的作用域。该作用域应当只为 write-text-file 命令启用，并且只暴露我们的 test.txt 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
   {
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": [
    "main"
  ],
  "permissions": [
    "path:default",
    "event:default",
    "window:default",
    "app:default",
    "image:default",
    "resources:default",
    "menu:default",
    "tray:default",
    "shell:allow-open",
    "fs:allow-write-text-file",
    {
      "identifier": "fs:allow-write-text-file",
      "allow": [{ "path": "$HOME/test.txt" }]
    },
  ]
}

5. 在实践中测试权限

添加所需权限之后，我们要确认应用能访问该文件并写入内容。

我们可以在应用中使用这段代码写入文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';

let greetInputEl: HTMLInputElement | null;

async function write(message: string) {
    await writeTextFile('test.txt', message, { baseDir: BaseDirectory.Home });
}

window.addEventListener("DOMContentLoaded", () => {
  greetInputEl = document.querySelector("#greet-input");
  document.querySelector("#greet-form")?.addEventListener("submit", (e) => {
    e.preventDefault();
    if (!greetInputEl )
      return;

    write(greetInputEl.value == "" ? "No input provided": greetInputEl.value);

  });
});

把 src/main.ts 替换为这段代码，意味着在使用纯 Vanilla + TypeScript 应用时我们无需修改默认的 index.html。在运行中的应用里向输入框输入任意内容，提交时就会被写入该文件。

现在让我们实际测试：

pnpm run tauri dev

在输入框输入内容并点击 “Submit” 之后，我们可以通过终端模拟器或手动打开你主目录中的文件来检查。

cat $HOME/test.txt

你应该会看到自己的输入，并且完成了关于在 Tauri 应用中使用插件权限的学习。 🥳

如果你遇到这个错误：

1
(anonymous function) (main.ts:5)

那么你很可能没有正确遵循前面的说明。

最后修改 September 25, 2026: 更新 (4c0ee2db0)