声明要由 Trunk 处理的资源非常简单且可扩展。

链接资源类型

所有要由 Trunk 处理的链接资源必须遵循以下三个规则

• 必须声明为有效的 HTML link 标签。
• 必须具有属性 data-trunk。
• 必须具有属性 rel="{type}"，其中 {type} 是下面列出的资源类型之一。

这通常看起来像这样：<link data-trunk rel="{type}" href="{path}" ..其他选项.. />。下面描述的每种资源类型都指定了其资源类型的必需和可选属性。所有 <link data-trunk .../> HTML 元素都将被替换为关联管道的输出 HTML。

rust

✅ rel="rust"：Trunk 将编译指定的 Cargo 项目为 WASM 并加载它。这是可选的。如果未指定，Trunk 将在源 HTML 文件的父目录中查找 Cargo.toml。

• href: (可选) Rust 项目的 Cargo.toml 路径。如果指定了目录，则 Trunk 将在给定目录中查找 Cargo.toml。如果未指定值，则 Trunk 将在源 HTML 文件的父目录中查找 Cargo.toml。
• data-target-name: (可选) 要加载的目标工件的名称。如果 Cargo 项目有多个目标（二进制文件和库），则可以使用此值来选择 Trunk 应使用哪个目标。
• data-bin: (可选) 要编译和加载的二进制文件的名称。如果 Cargo 项目有多个二进制文件，则可以使用此值来指定应编译特定的二进制文件（使用 --bin）并由 Trunk 使用。这隐式地包含 data-target-name。
• data-type: (可选) 指定二进制文件应如何加载到项目中。可以设置为 main 或 worker。main 是默认值。只能有一个 main 链接。对于 worker，将创建一个 wasm-bindgen javascript 包装器和 wasm 文件（带有 _bg.wasm 后缀），以二进制名称（如果提供）或项目名称命名。请参阅 webworker 示例之一，了解如何加载它们。
• data-cargo-features: (可选) 要激活的 cargo feature 的空格或逗号分隔列表。
• data-cargo-no-default-features: (可选) 禁用默认的 Cargo feature。
• data-cargo-all-features: (可选) 启用所有 Cargo feature。
  • 与 data-cargo-features 和 data-cargo-no-default-features 均不兼容。
• data-wasm-opt: (可选) 使用设置的优化级别运行 wasm-opt。可能的值为 0、1、2、3、4、s、z 或 空值 表示 wasm-opt 的默认值。将此选项设置为 0 以显式禁用 wasm-opt。值 1-4 是速度越来越快的优化级别。s 和 z（z 表示更多优化）针对二进制文件大小进行优化。仅在 --release 模式下使用。
• data-wasm-opt-params: (可选) 使用附加参数运行 wasm-opt。仅在 --release 模式下使用。
• data-keep-debug: (可选) 指示 wasm-bindgen 在最终 WASM 输出中保留调试信息，即使对于 --release 模式也是如此。这可能与 wasm-opt 的使用冲突，因此为了确保安全，建议在使用此选项时设置 data-wasm-opt="0"。
• data-no-demangle: (可选) 指示 wasm-bindgen 不要解构 Rust 符号名称。
• data-reference-types: (可选) 指示 wasm-bindgen 启用 引用类型。
• data-weak-refs: (可选) 指示 wasm-bindgen 启用 弱引用。
• data-typescript: (可选) 指示 wasm-bindgen 输出 Typescript 绑定。默认为 false。
• data-bindgen-target: (可选) 指定 wasm-bindgen 标志 --target 的值（有关可能的值，请参见链接）。默认为 no-modules。主要用例是切换到 web 与 data-type="worker"，这降低了向后 兼容性，但具有一些 优点。
• data-loader-shim: (可选) 指示 trunk 为 web worker 创建加载器垫片。默认为 false。
• data-cross-origin: (可选) 加载代码 & 脚本资源时的 crossorigin 设置。默认为纯 anonymous。
• data-integrity: (可选) 代码 & 脚本资源的 integrity 摘要类型。默认为纯 sha384。
• data-wasm-no-import: (可选) 默认情况下，Trunk 将生成从 Rust 导出的函数的导入。启用此标志将禁用此功能。默认为 false。
• data-wasm-import-name: (可选) 从 WASM 导入的函数可用的全局变量的名称（在 window 对象下）。默认为 wasmBindings（使其可以通过 window.wasmBindings.<functionName> 访问）。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

sass/scss

✅ rel="sass" 或 rel="scss"：Trunk 使用官方的 dart-sass 进行编译。只需从源 HTML 链接到您的 sass 文件，Trunk 将处理其余的事情。此内容已哈希处理以进行缓存控制。href 属性必须包含在指向要处理的 sass/scss 文件的链接中。

• data-inline: (可选) 此属性将 SASS/SCSS 文件中编译的 CSS 内联到 <style> 标签中，而不是使用 <link rel="stylesheet"> 标签。
• data-integrity: (可选) 代码 & 脚本资源的 integrity 摘要类型。默认为纯 sha384。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

css

✅ rel="css"：Trunk 将复制在源 HTML 中找到的链接 css 文件，而无需内容修改。此内容已哈希处理以进行缓存控制。href 属性必须包含在指向要处理的 css 文件的链接中。

• 将来，Trunk 将解析本地 @imports，将处理压缩（请参阅 trunk#7），我们甚至可能会研究一种模式，其中源树中找到的任何 CSS 都将被捆绑在一起，这将启用一种不错的零配置“组件样式”模式。有关更多详细信息，请参见 trunk#3。
• data-integrity: (可选) 代码 & 脚本资源的 integrity 摘要类型。默认为纯 sha384。
• data-no-minify: (可选) 选择不进行压缩。另请参阅：压缩。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

tailwind

✅ rel="tailwind-css"：Trunk 使用官方的 tailwindcss cli 进行编译。只需从源 HTML 链接到您的 tailwind css 文件，Trunk 将处理其余的事情。此内容已哈希处理以进行缓存控制。href 属性必须包含在指向要处理的 sass/scss 文件的链接中。

• data-inline: (可选) 此属性将 tailwind 编译中编译的 CSS 内联到 <style> 标签中，而不是使用 <link rel="stylesheet"> 标签。
• data-integrity: (可选) 代码 & 脚本资源的 integrity 摘要类型。默认为纯 sha384。
• data-no-minify: (可选) 选择不进行压缩。另请参阅：压缩。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。
• data-config: (可选) tailwind 配置文件的路径，如果它不在工作目录中。

icon

✅ rel="icon"：Trunk 将复制 href 属性中指定的图标图像到 dist 目录。此内容已哈希处理以进行缓存控制。

• data-integrity: (可选) 代码 & 脚本资源的 integrity 摘要类型。默认为纯 sha384。
• data-no-minify: (可选) 选择不进行压缩。另请参阅：压缩。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

inline

✅ rel="inline"：Trunk 将 href 属性中指定的文件内容内联到 index.html 中。此内容完全复制，不执行哈希处理。

• type: (可选) – 如果不存在，则类型由文件扩展名推断。
  • html, svg
  • css：用 style 标签包裹的 CSS
  • js：用 script 标签包裹的 JavaScript
  • mjs, module：用 script 标签包裹的 JavaScript，带有 type="module"

copy-file

✅ rel="copy-file"：Trunk 将复制 href 属性中指定的文件到 dist 目录。此内容完全复制，不执行哈希处理。

• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

copy-dir

✅ rel="copy-dir"：Trunk 将递归复制 href 属性中指定的目录到 dist 目录。此内容完全复制，不执行哈希处理。

• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

脚本资源类型

脚本资源更加多样化。

脚本资源

由 Trunk 处理的经典脚本资源必须遵循以下三个规则

• 必须声明为有效的 HTML script 标签。
• 必须具有属性 data-trunk。
• 必须具有指向脚本文件的属性 src

这通常看起来像这样：<script data-trunk src="{path}" ..其他选项..></script>。所有 <script data-trunk ...></script> HTML 元素都将被替换为关联管道的输出 HTML。

Trunk 将复制在源 HTML 中找到的脚本文件，而无需内容修改。此内容已哈希处理以进行缓存控制。src 属性必须包含在指向要处理的脚本文件的脚本中。

• data-no-minify: (可选) 选择不进行压缩。另请参阅：压缩。
• data-target-path: (可选) 输出放置在 dist 目录内的路径。如果不存在，则该目录放置在 dist 根目录中。该路径必须是相对路径，不带 ..。

JS 代码片段

从 wasm-bindgen JS 代码片段功能 生成的 JS 代码片段会自动复制到 dist 目录，进行哈希处理并准备就绪。无需其他设置。只需在您的应用程序中使用该功能，Trunk 将负责其余的工作。

图片 & 其他资源

通过将如下链接添加到源 HTML：<link data-trunk rel="copy-file" href="path/to/image"/>，可以将图像和其他资源类型复制到 dist 目录中。支持任何普通文件类型。这将导致 Trunk 查找目标资源，并将其未修改地复制到 dist 目录。不会应用哈希处理。链接本身将从 HTML 中删除。要复制整个资源/图像目录，可以使用以下 HTML：<link data-trunk rel="copy-dir" href="path/to/images-dir"/>。

这将允许您的 WASM 应用程序直接从 dist 目录引用图像，并且 Trunk 将确保图像在 dist 目录中可用以供服务。

注意： 随着 Trunk 的不断成熟，我们将找到更好的方法来包含图像和其他资源。为缓存控制哈希内容很棒，我们只需要找到一种与 Rust 组件中引用的图像配合使用的良好模式。请参与 trunk#9 中的讨论！在那里见。

子资源完整性 (SRI)

Trunk 可以自动生成文件的哈希值，并为 Web 应用程序获取的资源添加 integrity 属性。默认情况下启用此功能，但可以使用 data-integrity 属性覆盖。请参阅不同的资源类型。

以下值可用

• none
• sha256
• sha384 (默认)
• sha512

指令

您可以通过将此添加到 <head> 中来指示 Trunk 将传递给 --public-url 的 URL 写入 HTML 输出：<base data-trunk-public-url/>。

Trunk 将元素的 href 属性设置为公共 URL。这会将相对 URL 的行为更改为相对于公共 URL 而不是当前位置。

您还可以在运行时使用 document.baseURI 访问此值，这对于需要知道其托管基本 URL 的应用程序（例如，用于路由）很有用。

钩子

如果您发现需要 Trunk 执行其他不支持的构建操作，则可以使用 Trunk 灵活的钩子系统在管道的各个阶段启动外部进程。钩子可以专门在 Trunk.toml 中声明，并且包含 stage、command 和 command_arguments

• stage: (必需) pre_build、build 或 post_build 之一。它指定钩子在 Trunk 的构建管道中的执行时间。
• command: (必需) 所需可执行文件的名称或路径。
• command_arguments: (可选，默认为 none) 要按给定顺序传递给可执行文件的任何参数。

在每个阶段的相关点，该阶段的所有钩子都会同时生成。之后，Trunk 会立即等待所有钩子退出后再继续，build 阶段的情况除外，这将在下面进一步描述。

Trunk 的构建流程

这是 Trunk 构建流程的简要概述，目的是描述何时执行钩子。请注意，确切的顺序将来可能会更改以添加新功能。

• 步骤 1 — 读取并解析 HTML 文件。
• 步骤 2 — 生成要构建的所有资源的计划。
• 步骤 3 — 并行构建所有资源。
• 步骤 4 — 完成并将资源写入暂存目录。
• 步骤 5 — 将 HTML 写入暂存目录。
• 步骤 6 - 将 dist 目录内容替换为暂存目录内容。

钩子阶段与此对应关系如下

• pre_build：发生在步骤 1 之前。
• build：与步骤 3 同时发生，与资源构建并行执行。
• post_build：发生在步骤 5 之后和步骤 6 之前。

钩子环境 & 执行

所有钩子都使用与 trunk 相同的 stdin 和 stdout 执行。可执行文件应返回错误代码 0 以指示成功。任何其他代码都将被视为错误并终止构建过程。此外，以下环境变量提供给该进程

• TRUNK_PROFILE：正在使用的构建 profile。当前为 debug 或 release。
• TRUNK_HTML_FILE：HTML 文件的完整路径（通常是 TRUNK_SOURCE_DIR 中的 index.html），trunk 使用它。
• TRUNK_SOURCE_DIR：Trunk 使用的源目录的完整路径。这始终是 TRUNK_HTML_FILE 所在的目录。
• TRUNK_STAGING_DIR：Trunk 暂存目录的完整路径。
• TRUNK_DIST_DIR：Trunk dist 目录的完整路径。
• TRUNK_PUBLIC_URL：为 Trunk 配置的公共 URL。

操作系统特定的覆盖

通常，您希望在不同的操作系统上执行相同的构建步骤，这需要不同的命令。一个典型的例子是在 Linux 上使用 sh 命令，但在 Windows 上使用 cmd。为了适应这一点，您可以选择为每个钩子创建特定于操作系统的覆盖。为此，请指定默认钩子，然后在正下方创建一个 [hooks.<os>] 条目，其中 <os> 可以是 windows、macos 或 linux 之一。在此条目中，您必须仅指定 command 和 command_argumnets 键。您可以为每个钩子提供多个覆盖。例如，一个用于 windows，一个用于 macos，一个用于 linux。

自动重载

从 v0.14.0 开始，Trunk 现在附带在 Trunk 构建管道完成时自动重新加载您的 Web 应用程序的功能。

压缩

Trunk 支持压缩资源。默认情况下禁用此功能，并且可以在不同级别进行控制。

在任何情况下，Trunk 本身不执行压缩，而是将该过程委托给执行实际实现的依赖项。如果压缩破坏了某些东西，则很可能是该依赖项的问题。

从 Trunk 0.20.0 开始，默认情况下禁用压缩。可以使用命令行中的 --minify (或 -M) 开关来启用它。或者，可以使用 Trunk.toml 文件中的 build.minify 字段来控制它。此字段的值是一个枚举，具有以下可能的值：never（默认，从不压缩）、on_release（在运行 Trunk 时使用 --release 进行压缩）、always（始终压缩）。

启用压缩后，所有 Trunk 已知的资源（这不包括对 Trunk 不透明的 copy-dir 和 copy-file blob）都将被压缩。可以使用 data-no-minify 属性（请参阅单个资源配置）选择退出此过程（按资源）。在这种情况下，资源将永远不会被压缩。