嵌入附加文件

你可能需要在你的应用包中包含一些额外的文件，这些文件不是你的前端（你的 frontendDist）的一部分，或者文件太大而无法内联到二进制文件中。我们称这些文件为 resources。

🌐 You may need to include additional files in your application bundle that aren’t part of your frontend (your frontendDist) directly or which are too big to be inlined into the binary. We call these files resources.

配置

🌐 Configuration

要打包你选择的文件，请在你的 tauri.conf.json 文件中的 bundle 对象中添加 resources 属性。

🌐 To bundle the files of your choice, add the resources property to the bundle object in your tauri.conf.json file.

要包含文件列表：

🌐 To include a list of files:

Syntax
Explanation

{
  "bundle": {
    "resources": [
      "./path/to/some-file.txt",
      "/absolute/path/to/textfile.txt",
      "../relative/path/to/jsonfile.json",
      "some-folder/",
      "resources/**/*.md"
    ]
  }
}

{
  "bundle": {
    "resources": [
      // Will be placed to `$RESOURCE/path/to/some-file.txt`
      "./path/to/some-file.txt",

      // The root in an absolute path will be replaced by `_root_`,
      // so `textfile.txt` will be placed to `$RESOURCE/_root_/absolute/path/to/textfile.txt`
      "/absolute/path/to/textfile.txt",

      // `..` in a relative path will be replaced by `_up_`,
      // so `jsonfile.json` will be placed to `$RESOURCE/_up_/relative/path/to/textfile.txt`,
      "../relative/path/to/jsonfile.json",

      // If the path is a directory, the entire directory will be copied to the `$RESOURCE` directory,
      // preserving the original structures, for example:
      //   - `some-folder/file.txt`                   -> `$RESOURCE/some-folder/file.txt`
      //   - `some-folder/another-folder/config.json` -> `$RESOURCE/some-folder/another-folder/config.json`
      // This is the same as `some-folder/**/*`
      "some-folder/",

      // You can also include multiple files at once through glob patterns.
      // All the `.md` files inside `resources` will be placed to `$RESOURCE/resources/`,
      // preserving their original directory structures, for example:
      //   - `resources/index.md`      -> `$RESOURCE/resources/index.md`
      //   - `resources/docs/setup.md` -> `$RESOURCE/resources/docs/setup.md`
      "resources/**/*.md"
    ]
  }
}

打包的文件将位于 $RESOURCES/ 中，并保留原始目录结构，例如：./path/to/some-file.txt -> $RESOURCE/path/to/some-file.txt

🌐 The bundled files will be in $RESOURCES/ with the original directory structure preserved, for example: ./path/to/some-file.txt -> $RESOURCE/path/to/some-file.txt

要精确控制文件复制到的位置，请使用映射：

🌐 To fine control where the files will get copied to, use a map instead:

Syntax
Explanation

{
  "bundle": {
    "resources": {
      "/absolute/path/to/textfile.txt": "resources/textfile.txt",
      "relative/path/to/jsonfile.json": "resources/jsonfile.json",
      "resources/": "",
      "docs/**/*md": "website-docs/"
    }
  }
}

{
  "bundle": {
    "resources": {
      // `textfile.txt` will be placed to `$RESOURCE/resources/textfile.txt`
      "/absolute/path/to/textfile.txt": "resources/textfile.txt",

      // `jsonfile.json` will be placed to `$RESOURCE/resources/jsonfile.json`
      "relative/path/to/jsonfile.json": "resources/jsonfile.json",

      // Copy the entire directory to `$RESOURCE`, preserving the original structures,
      // the target is "" which means it will be placed directly in the resource directory `$RESOURCE`, for example:
      //   - `resources/file.txt`                -> `$RESOURCE/file.txt`
      //   - `resources/some-folder/config.json` -> `$RESOURCE/some-folder/config.json`
      "resources/": "",

      // When using glob patterns, the behavior is different from the list one,
      // all the matching files will be placed to the target directory without preserving the original file structures
      // for example:
      //   - `docs/index.md`         -> `$RESOURCE/website-docs/index.md`
      //   - `docs/plugins/setup.md` -> `$RESOURCE/website-docs/setup.md`
      "docs/**/*md": "website-docs/"
    }
  }
}

要了解 $RESOURCE 在各个平台上的解析情况，请参阅 resource_dir 的文档

🌐 To learn about where $RESOURCE resolves to on each platforms, see the documentation of resource_dir

源路径语法

在以下解释中，“目标资源目录”要么是对象表示法中冒号后的值，要么是数组表示法中原始文件路径的重建。

🌐 In the following explanations “target resource directory” is either the value after the colon in the object notation, or a reconstruction of the original file paths in the array notation.

"dir/file.txt"：将 file.txt 文件复制到目标资源目录中。
"dir/"：将所有文件和目录_递归地_复制到目标资源目录中。如果你还想保留文件和目录的文件系统结构，请使用此方法。
"dir/*"：将 dir 目录中的所有文件_非递归地_（子目录将被忽略）复制到目标资源目录中。
"dir/**：抛出错误，因为 ** 只匹配目录，因此找不到任何文件。
"dir/**/*"：将 dir 目录中的所有文件_递归地_（dir/ 中的所有文件以及所有子目录中的所有文件）复制到目标资源目录中。
"dir/**/**：抛出错误，因为 ** 只匹配目录，因此找不到任何文件。

解析资源文件路径

🌐 Resolve resource file paths

要解析资源文件的路径（而不是手动计算路径），请使用以下 API。

🌐 To resolve the path for a resource file, instead of manually calculating the path, use the following APIs

Rust
JavaScript

在 Rust 端，你需要一个 PathResolver 的实例，你可以从 App 和 AppHandle 获取，然后调用 PathResolver::resolve：

🌐 On the Rust side, you need an instance of the PathResolver which you can get from App and AppHandle, then call PathResolver::resolve:

tauri::Builder::default()
  .setup(|app| {
    let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource)?;
    Ok(())
  })

要在命令中使用：

🌐 To use it in a command:

#[tauri::command]
fn hello(handle: tauri::AppHandle) {
  let resource_path = handle.path().resolve("lang/de.json", BaseDirectory::Resource)?;
}

要在 JavaScript 中解析路径，请使用 resolveResource：

🌐 To resolve the path in JavaScript, use resolveResource:

import { resolveResource } from '@tauri-apps/api/path';
const resourcePath = await resolveResource('lang/de.json');

路径语法

🌐 Path syntax

API 调用中的路径可以是像 folder/json_file.json 这样的普通相对路径，它会解析为 $RESOURCE/folder/json_file.json，或者是像 ../relative/folder/toml_file.toml 这样的路径，它会解析为 $RESOURCE/_up_/relative/folder/toml_file.toml，这些 API 使用的规则与你编写 tauri.conf.json > bundle > resources 时相同，例如：

🌐 The path in the API calls can be either a normal relative path like folder/json_file.json that resolves to $RESOURCE/folder/json_file.json, or a paths like ../relative/folder/toml_file.toml that resolves to $RESOURCE/_up_/relative/folder/toml_file.toml, these APIs use the same rules as you write tauri.conf.json > bundle > resources, for example:

{
  "bundle": {
    "resources": ["folder/json_file.json", "../relative/folder/toml_file.toml"]
  }
}

let json_path = app.path().resolve("folder/json_file.json", BaseDirectory::Resource)?;
let toml_path = app.path().resolve("../relative/folder/toml_file.toml", BaseDirectory::Resource)?;

Android

目前这些资源是作为资源存储在APK中，因此这些API的返回值不是普通的文件系统路径，我们在这里使用一个特殊的URI前缀 asset://localhost/，可以与[fs插件]一起使用，有了它，你可以像这样通过FsExt::fs读取文件:

🌐 Currently the resources are stored in the APK as assets so the return value of those APIs are not normal file system paths, we use a special URI prefix asset://localhost/ here that can be used with the fs plugin, with that, you can read the files through FsExt::fs like this:

let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource).unwrap();
let json = app.fs().read_to_string(&resource_path);

如果你想要或必须让资源文件存在于真实的文件系统上，请通过 [fs 插件] 手动复制内容

🌐 If you want or must have the resource files to be on a real file system, copy the contents out manually through the fs plugin

读取资源文件

🌐 Reading resource files

在此示例中，我们希望像这样打包额外的 i18n json 文件：

🌐 In this example we want to bundle additional i18n json files like this:

.
├── src-tauri/
│   ├── tauri.conf.json
│   ├── lang/
│   │   ├── de.json
│   │   └── en.json
│   └── ...
└── ...

{
  "bundle": {
    "resources": ["lang/*"]
  }
}

{
  "hello": "Guten Tag!",
  "bye": "Auf Wiedersehen!"
}

Rust

在 Rust 端，你需要一个 PathResolver 的实例，你可以从 App 和 AppHandle 获取它：

🌐 On the Rust side, you need an instance of the PathResolver which you can get from App and AppHandle:

tauri::Builder::default()
  .setup(|app| {
    // The path specified must follow the same syntax as defined in
    // `tauri.conf.json > bundle > resources`
    let resource_path = app.path().resolve("lang/de.json", BaseDirectory::Resource)?;

    let json = std::fs::read_to_string(&resource_path).unwrap();
    // Or when dealing with Android, use the file system plugin instead
    // let json = app.fs().read_to_string(&resource_path);

    let lang_de: serde_json::Value = serde_json::from_str(json).unwrap();

    // This will print 'Guten Tag!' to the terminal
    println!("{}", lang_de.get("hello").unwrap());

    Ok(())
  })

#[tauri::command]
fn hello(handle: tauri::AppHandle) -> String {
    let resource_path = handle.path().resolve("lang/de.json", BaseDirectory::Resource)?;

    let json = std::fs::read_to_string(&resource_path).unwrap();
    // Or when dealing with Android, use the file system plugin instead
    // let json = handle.fs().read_to_string(&resource_path);

    let lang_de: serde_json::Value = serde_json::from_str(json).unwrap();

    lang_de.get("hello").unwrap()
}

JavaScript

对于 JavaScript 端，你可以使用上面类似的命令并通过 await invoke('hello') 调用它，或者使用 [fs 插件] 访问这些文件。

🌐 For the JavaScript side, you can either use a command like the one above and call it through await invoke('hello') or access the files using the fs plugin.

在使用 [fs 插件] 时，除了 [基本设置]，你还需要配置访问控制列表，以启用你需要的任何插件 API 以及访问 $RESOURCE 文件夹的权限：

🌐 When using the fs plugin, in addition to the basic setup, you’ll also need to configure the access control list to enable any plugin APIs you need as well as the permissions to access the $RESOURCE folder:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:allow-read-text-file",
    "fs:allow-resource-read-recursive"
  ]
}

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

const resourcePath = await resolveResource('lang/de.json');
const langDe = JSON.parse(await readTextFile(resourcePath));
console.log(langDe.hello); // This will print 'Guten Tag!' to the devtools console

权限

🌐 Permissions

由于在使用列表时我们将相对路径中的 ../ 替换为 _up_，将绝对路径的根替换为 _root_，这些文件将位于资源目录内的子文件夹中，为了在 Tauri 的权限系统中允许这些路径，请使用 $RESOURCE/**/* 来允许递归访问这些文件

🌐 Since we replace ../ to _up_ in relative paths and the root to _root_ in absolute paths when using a list, those files will be in sub folders inside the resource directory, to allow those paths in Tauri’s permission system, use $RESOURCE/**/* to allow recursive access to those files

示例

🌐 Examples

打包文件如下：

🌐 With a file bundled like this:

{
  "bundle": {
    "resources": ["../relative/path/to/jsonfile.json"]
  }
}

要与[fs插件]一起使用：

🌐 To use it with the fs plugin:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:allow-stat",
    "fs:allow-read-text-file",
    "fs:allow-resource-read-recursive",
    {
      "identifier": "fs:scope",
      "allow": ["$RESOURCE/**/*"],
      "deny": ["$RESOURCE/secret.txt"]
    }
  ]
}

要与[opener插件]一起使用:

🌐 To use it with the opener plugin:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    {
      "identifier": "opener:allow-open-path",
      "allow": [
        {
          "path": "$RESOURCE/**/*"
        }
      ]
    }
  ]
}