> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 静态

> 通过内核提供插件包中的文件。

静态挂载允许插件直接通过内核的 HTTP 服务器公开其包中的文件。
适用于页面、样式表、脚本、图像以及其他无需插件代码处理每个请求的文件。
插件在注册期间声明静态挂载。挂载被接受后，内核将从声明的文件或目录中提供匹配的请求。
请求无需跨越插件进程或 WASM 边界。

## 声明静态挂载

静态挂载包含三个部分：

| 属性          | 含义                                                  |
| ----------- | --------------------------------------------------- |
| `prefix`    | 资源可用的 URL 路径。                                       |
| `directory` | 要提供的文件或目录。使用 `$PLUGIN_ROOT` 引用插件包中提取的 `Content` 目录。 |
| `access`    | 挂载资源的可选访问策略。                                        |

具体语法取决于您使用的语言和生成的 SDK。以下语言无关的声明显示了挂载点包含的信息：

```text theme={null}
prefix: /my-plugin/assets/
directory: $PLUGIN_ROOT/assets
access: public
```

内核加载插件时，目录或文件必须存在。将资源打包到 `Content/` 目录下，并通过 `$PLUGIN_ROOT` 引用它：

```text theme={null}
my-plugin.plg
├── info.yaml
└── Content/
    └── assets/
        ├── app.js
        └── app.css
```

## 挂载目录

挂载目录时，请使用以 `/` 结尾的 URL 前缀：

```text theme={null}
prefix: /my-plugin/assets/
directory: $PLUGIN_ROOT/assets
```

前缀映射到目录子树。例如：

```text theme={null}
/my-plugin/assets/app.js → Content/assets/app.js
/my-plugin/assets/app.css → Content/assets/app.css
```

URL 前缀应以 `/` 开头。末尾的 `/` 表示该前缀匹配其下方的子树。
不带尾部斜杠的路径 `/my-plugin/assets` 不是同一个子树路径；
如果您需要重定向或在该路径上获取索引响应，请添加 HTTP 路由。

如果前缀不包含尾部斜杠，内核会将目录挂载规范化为子树前缀。
请显式使用尾部斜杠，以便读者和客户端能够清楚地了解映射关系。

## 挂载单个文件

提供单个文件时，请使用不带尾部斜杠 `/` 的精确 URL 路径：

```text theme={null}
prefix: /my-plugin/index.html
directory: $PLUGIN_ROOT/pages/index.html
```

仅提供精确路径。对 `/my-plugin/index.html/anything` 的请求与此挂载不匹配。
尽管声明属性名为 `directory`，但它既可以接受目录，也可以接受单个文件。

不要在文件挂载点末尾添加斜杠 `/`。末尾的斜杠会告诉内核将源视为目录挂载点。

## URL 路径规则

静态挂载点前缀遵循内核的路径模式规则：

* 前缀必须是以 `/` 开头的绝对路径；
* 不带末尾斜杠 `/` 的前缀匹配一个精确路径；
* 以 `/` 结尾的前缀匹配该路径的子树；并且
* `/*` 不是通配符，会被拒绝。

根前缀 `/` 被视为静态文件的子树，可以匹配所有绝对请求路径。除非插件旨在提供应用程序的通用静态内容，否则请避免声明根路径。

## 访问控制

内核在提供文件之前应用 `access` 策略。
请求还必须满足为插件配置的插件级访问策略。
如果任一策略拒绝请求，则不会提供文件。
空的挂载策略不会绕过非空的插件级策略。
使用插件配置来限制插件拥有的所有资源，
并使用挂载策略来对单个静态资源进行更具体的限制。有关策略模型，请参阅[访问控制](../kernel/config-access)。

## 冲突和匹配

静态挂载与插件 HTTP 路由和其他静态挂载共享应用程序的 URL 空间。
保持每个插件的前缀唯一。如果另一个插件已经拥有相同的静态前缀或冲突的HTTP 路由模式，内核将拒绝该挂载。

当多个挂载可以匹配一个请求时，匹配前缀最长的挂载优先。
当静态挂载与插件 HTTP 路由的匹配长度相同时，该挂载也优先。
选择特定的前缀以避免 URL 的意外所有权。

## 打包检查清单

加载插件之前，请验证：

* 每个挂载的文件或目录都位于包的 `Content/` 树中；
* `directory` 值使用 `$PLUGIN_ROOT` 而不是构建机器路径；
* 目录前缀以 `/` 结尾；
* 文件前缀不以 `/` 结尾；并且
* 该软件包包含挂载点引用的所有文件。

静态文件适用于可以直接提供的文件。
如果请求需要应用程序逻辑、请求数据或生成的响应，请改用 HTTP 传输方式。