11.1 文件系统 API

权限配置：先“开门”才能用

在使用任何文件操作之前，你需要在 tauri.conf.json 中显式声明应用需要哪些文件系统权限。所有权限默认都是关闭的，这符合“最小权限”原则。

例如，要允许应用读取文档目录和写入应用数据目录：

{
  "tauri": {
    "allowlist": {
      "fs": {
        "scope": ["$DOCUMENT/*", "$APPDATA/*"],
        "readFile": true,
        "writeFile": true,
        "createDir": true,
        "existsDir": true
      }
    }
  }
}

scope 中的路径可以使用 Tauri 预定义变量（$DOCUMENT、$APPDATA、$HOME 等），也可以写相对路径或绝对路径。只有被列入 scope 的路径，前端才能在运行时通过 API 访问。这一步看似繁琐，实际上是对用户数据负责——它确保了你的应用无法随意读取整个磁盘。

前端调用：封装好的 @tauri-apps/api/fs

Tauri 的 @tauri-apps/api 提供了 fs 模块，接口风格贴近现代 JavaScript，与 Node.js 的 fs/promises 相似，但底层走的是 Rust 的 IPC 通道。

读取文本文件

import { readTextFile } from '@tauri-apps/api/fs';

const readConfig = async () => {
  try {
    const content = await readTextFile('config/settings.json');
    console.log(content);
  } catch (error) {
    console.error('读取失败：', error);
  }
};

写入文本文件

import { writeTextFile } from '@tauri-apps/api/fs';

writeTextFile('config/settings.json', JSON.stringify({ theme: 'dark' }))
  .then(() => console.log('保存成功'))
  .catch(err => console.error(err));

处理二进制文件
对于图片、数据库文件等，可以使用 readBinaryFile 和 writeBinaryFile，数据以 Uint8Array 形式传递：

import { readBinaryFile, writeBinaryFile } from '@tauri-apps/api/fs';

const imageData = await readBinaryFile('images/avatar.png');
// 处理二进制数据...
await writeBinaryFile('images/avatar-backup.png', imageData);

目录操作
创建目录、检查存在、列出内容都很直接：

import { createDir, existsDir, readDir } from '@tauri-apps/api/fs';

await createDir('output', { recursive: true });
if (await existsDir('output')) {
  const entries = await readDir('output');
  // entries 是一个数组，包含每个条目的路径、名称、类型（文件或目录）等信息
}

路径处理：搭配 path 模块

由于不同操作系统的路径分隔符不同，Tauri 也提供了轻量的 path 模块来辅助拼接。常见的预定义目录可以通过 appDir、configDir、desktopDir 等函数获取，例如：

import { documentDir } from '@tauri-apps/api/path';
import { readTextFile } from '@tauri-apps/api/fs';

const docPath = await documentDir();
const content = await readTextFile(`${docPath}/my-app/data.txt`);

这样你就不用手动拼接 ~/Documents 或 C:\Users\xxx，跨平台兼容性由 Tauri 处理。

性能与安全提示

• 避免频繁小碎盘操作：每次文件 API 调用都会通过 IPC 转到 Rust 侧执行，虽然很快，但大量密集调用（比如逐行读大文件）仍可能造成性能损耗。必要时可以一次性读写整个文件，或通过自定义 Rust 命令在后台批量处理。
• scope 是最后防线：即使前端代码出现漏洞，注入攻击也不能突破 scope 限制去读取 $HOME/.ssh 之类的敏感路径。所以请始终最小化你的 scope 范围，不要添加 "*" 通配符到所有路径。
• 异步为主：文件操作请使用异步接口，避免阻塞 UI 线程。Tauri 的 fs API 都返回 Promise，与现代 UI 框架（React、Vue 等）的异步流程完美配合。

一句话总结：Tauri 的文件系统 API 让你安全、高效地操作文件，只需记住“先配置 scope，再用简洁的异步函数调用”，就能在享受原生性能的同时守住用户数据安全的底线。