资源协议范围

Tauri 可以通过 asset 自定义协议将磁盘中的文件提供到 WebView（例如当你在前端使用 convertFileSrc 时）。路径是否被允许由 tauri.conf.json 中的 app.security.assetProtocol 控制。

🌐 Tauri can serve files from disk into the WebView through the asset custom protocol (for example when you use convertFileSrc in the frontend). Whether a path is allowed is controlled by app.security.assetProtocol in tauri.conf.json.

你必须将 enable 设置为 true 并定义一个 scope，列出可以暴露的文件系统路径。在运行时解析的路径必须符合该范围，否则 WebView 将拒绝加载（通常会出现类似“资源协议未配置以允许该路径”的错误）。

🌐 You must set enable to true and define a scope that lists which filesystem paths may be exposed. Paths resolved at runtime must match that scope, or the WebView will refuse the load (often with an error such as “asset protocol not configured to allow the path”).

asset: 源的内容安全策略记录在 内容安全策略 (CSP) 页面上。本页面的重点是 作用域 以及它如何与通配符和隐藏路径段交互。

🌐 Content Security Policy for asset: sources is documented on the Content Security Policy (CSP) page. This page focuses on scope and how it interacts with globs and hidden path segments.

scope 是如何定义的

🌐 How scope is defined

assetProtocol.scope 使用与其他文件系统相关配置相同的 FsScope 类型：要么是允许的 glob 模式的 JSON 数组，要么是包含 allow、可选 deny 和可选 requireLiteralLeadingDot 的 JSON 对象。有关“作用域”如何更广泛地融入 Tauri 的安全模型，请参见 Command scopes。

模式可以以基本目录变量开始（例如 $HOME、$CACHE、$APPCACHE、$APPDATA、$RESOURCE）。有关你的应用可以依赖的完整变量集，请参阅 路径 / 基本目录 API。

🌐 Patterns may start with a base directory variable (for example $HOME, $CACHE, $APPCACHE, $APPDATA, $RESOURCE). See the path / base directory APIs for the full set of variables your app can rely on.

在加载资源时解析的路径通常是绝对的（在 Linux 上，通常位于 /home/... 下）。像 ["*/**"] 这样的模式通常不匹配这些路径，因为它与开头的 / 或基目录变量不一致。建议使用像 $HOME/**/*、/home/username/**/* 或其他与解析路径相对应的模式。

🌐 Paths resolved when loading assets are usually absolute (on Linux, often under /home/...). A pattern like ["*/**"] typically does not match those paths, because it does not line up with a leading / or a base-directory variable. Prefer patterns such as $HOME/**/*, /home/username/**/*, or another form that mirrors the resolved path.

数组形式（仅允许的路径）

🌐 Array form (allowed paths only)

当你只需要固定的允许列表且默认的通配符行为就足够时，使用列表：

🌐 Use a list when you only need a fixed allow list and default glob behavior is enough:

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": ["$APPCACHE/**/*", "$RESOURCE/**/*"]
      }
    }
  }
}

使用数组形式你无法设置 requireLiteralLeadingDot；要设置它，请使用下面的对象形式。

🌐 With the array form you cannot set requireLiteralLeadingDot; for that, use the object form below.

对象形式 (allow、deny、requireLiteralLeadingDot)

🌐 Object form (allow, deny, requireLiteralLeadingDot)

当你需要拒绝规则或更改前导点匹配时使用对象：

🌐 Use an object when you need deny rules or to change leading-dot matching:

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "allow": ["$APPCACHE/**/*"],
          "deny": ["$APPCACHE/**/secrets/**"]
        }
      }
    }
  }
}

deny 在两者都匹配时优先于 allow。

Unix：以 . 开头的路径段

🌐 Unix: path segments starting with .

在 Unix 上，requireLiteralLeadingDot 默认为 true。然后诸如 *、?、** 和 [...] 的通配符标记 不会匹配以 . 开头的路径组件（如 .cache 或 .ssh 的点文件和点目录）。

🌐 On Unix, requireLiteralLeadingDot defaults to true. Then wildcard tokens such as *, ?, **, and [...] do not match a path component that starts with . (dotfiles and dot-directories such as .cache or .ssh).

所以像 $HOME/** 这样的模式可以允许 /home/user/Documents/file.png，但不允许 /home/user/.cache/myapp/preview.png，因为 .cache 是一个点前缀组件。一个字面命名该段的模式（例如 $HOME/.cache/myapp/**）确实会匹配。

🌐 So a pattern like $HOME/** can allow /home/user/Documents/file.png but not /home/user/.cache/myapp/preview.png, because .cache is a dot-prefixed component. A pattern that names the segment literally (for example $HOME/.cache/myapp/**) does match.

要允许在通配符匹配下使用点前缀的组件，你可以在 对象 scope 上将 requireLiteralLeadingDot 设置为 false（这会扩大 WebView 可以加载的内容范围；请仔细查看）：

🌐 To allow dot-prefixed components under a broad glob, you can set requireLiteralLeadingDot to false on the object scope (this widens what the WebView can load; review carefully):

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "requireLiteralLeadingDot": false,
          "allow": ["$HOME/**/*"]
        }
      }
    }
  }
}

Still blocked on Linux-style paths?

当路径经过一个 点目录（例如 ~/.cache/...）而允许模式只在 $HOME 下使用 ** 时，社区成员经常会遇到这个问题。有关具体示例和解决方法，请参见 tauri#13788 中的讨论。

🌐 Community members often hit this when a path goes through a dot-directory (for example ~/.cache/...) while the allow pattern only uses ** under $HOME. See the discussion in tauri#13788 for concrete examples and fixes.

对于“此处下的所有文件”，优先使用 **/* 而不是裸用 **

🌐 Prefer **/* over bare ** for “all files under here”

对于应该匹配树下文件的通配符，优先使用 **/*（以及类似的 $DIR/**/* 变体），而不是单独的 **，这与其他 Tauri 路径示例保持一致。当你想要“递归匹配此目录下的所有内容”时，单独的 ** 很容易被误用。

🌐 For globs that should match files under a tree, prefer **/* (and variants like $DIR/**/*) rather than bare **, consistent with other Tauri path examples. Bare ** is easy to misuse when you intend “everything under this directory recursively.”

高度宽容的配置（使用时需极度小心）

🌐 Highly permissive configuration (use with extreme care)

如果你有意需要尽可能广泛的访问权限 并且 包含点前缀的部分，维护者建议的形式如下。这不是默认推荐；它会增加隐藏和敏感文件的暴露风险。

🌐 If you intentionally need the broadest possible access and dot-prefixed segments, a maintainer-suggested shape looks like this. This is not a default recommendation; it increases exposure of hidden and sensitive files.

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "requireLiteralLeadingDot": false,
          "allow": ["**/*"]
        }
      }
    }
  }
}

Caution

优先选择狭窄的目录（如 $APPCACHE、$RESOURCE、$HOME 下的单个应用子文件夹等），而不是广泛的 $HOME/**/* 或 **/*，除非你有充分的理由并理解安全权衡。

🌐 Prefer narrow directories ($APPCACHE, $RESOURCE, a single app subfolder under $HOME, etc.) instead of broad $HOME/**/* or **/* unless you have a strong reason and understand the security tradeoffs.

静态配置与动态选择的路径

🌐 Static config vs dynamically chosen paths

tauri.conf.json 中的条目描述了 静态 的允许/拒绝模式。它们不能替代用户选择任意文件夹或文件的运行时工作流（例如使用 dialog 插件时）：这些路径可能需要使用 persisted-scope 插件在重启后 保留。

🌐 Entries in tauri.conf.json describe static allow/deny patterns. They do not replace runtime workflows where the user picks arbitrary folders or files (for example with the dialog plugin): those paths may need to be persisted across restarts using the persisted-scope plugin.

要在该插件中保持 资源 / 协议相关的范围，请在 src-tauri/Cargo.toml 中启用其 protocol-asset Cargo 功能，例如：

🌐 To persist asset / protocol-related scope with that plugin, enable its protocol-asset Cargo feature in src-tauri/Cargo.toml, for example:

tauri-plugin-persisted-scope = { version = "2", features = ["protocol-asset"] }

按照插件指南，在 tauri_plugin_persisted_scope 之前注册 tauri_plugin_fs。

🌐 Register tauri_plugin_fs before tauri_plugin_persisted_scope as described in the plugin guide.

故障排除

🌐 Troubleshooting

症状	需要检查的事项
“资源协议未配置以允许该路径”	路径必须符合 allow 模式；deny 会覆盖 allow。使用 绝对 模式或符合路径在磁盘上解析方式的 $VAR/$HOME 风格变量。
对于普通文件夹有效，但在 .cache / .config 下无效	在 Unix 上，默认 requireLiteralLeadingDot 行为：在模式中使用字面量 .segment，或在对象 scope 中设置 requireLiteralLeadingDot: false（参见 tauri#13788）。
用户在运行时选择了一个文件夹；重启后仍被阻止	你可能需要使用带有 protocol-asset 功能的 persisted-scope，而不仅仅是 tauri.conf.json 条目。
广义的 ** 似乎不对	对于面向文件的通配符，请尝试 **/*；有关在打包资源中 ** 与 **/* 的类似指导，请参见 嵌入其他文件。
类似 ["*/**"] 的作用域在 Linux 上从不匹配	已解析的路径是 绝对的；请使用 $... 变量、前导 /，或其他匹配实际路径的模式（见上文）。

assetProtocol 和 FsScope 的权威 Rust 类型位于 Tauri 的 config.rs（AssetProtocolConfig，FsScope）。生成的配置参考 可能会以紧凑或难以阅读的方式呈现嵌套的 FsScope 字段；如果某些地方看起来不清楚，请核对本页和文件系统插件的 requireLiteralLeadingDot 部分（插件配置在其自己的作用域中使用相同的选项名称）。如果参考文档仍未清晰记录这些字段，请考虑在 tauri-docs 仓库中提出 issue，以便改进配置生成器。

🌐 The authoritative Rust types for assetProtocol and FsScope live in Tauri’s config.rs (AssetProtocolConfig, FsScope). The generated configuration reference may render nested FsScope fields in a compact or hard-to-read way; if something looks unclear there, cross-check this page and the file system plugin requireLiteralLeadingDot section (plugin config uses the same option name for its own scopes). If the reference still does not document those fields clearly, consider opening an issue on the tauri-docs repository so the config generator can be improved.