如何用 Dioxus 的 asset! 宏引用图片、JS 与 CSS 资源并自动优化
如何用 Dioxus 的 asset! 宏引用图片、JS 与 CSS 资源并自动优化
在 Dioxus 里给应用引入图片、CSS 和 JavaScript 时,直接写死相对路径在 web 和 Android 这类资源按平台 API 懒加载的环境中很容易失效。Dioxus 的 asset! 宏(来自 manganis 包,dioxus crate 的默认 lib 特性已包含它)解决的就是这个问题:编译时把资源路径嵌入二进制,构建后由 Dioxus CLI 提取这些元数据,对资源做压缩、转换等后处理,并按内容哈希改写输出文件名以支持缓存失效(cache-busting)。本文按「声明资源 → 在 UI 中使用 → 构建验证」的顺序,给出图片、CSS、JS 三类资源的完整用法。
asset! 宏如何工作
基本写法是把资源声明为一个 Asset 常量:
use manganis::{Asset, asset};
const STYLE: Asset = asset!("/assets/style.css");
要点(均来自 manganis README):
- 路径以
/开头的绝对路径是相对于包(package)根目录解析的,宏会校验文件存在且位于 crate 内部; - cargo 构建完成后,资源路径直接嵌入二进制的数据段;
- Dioxus CLI 之类的工具随后提取这份元数据并后处理这些资源——包括压缩 CSS/JS、优化/转换图片、给输出文件名加哈希。
在 Dioxus 应用里通常通过预lude 直接写 asset! 即可。仓库中的 custom_assets 示例 就是这样做的(其中 /examples/... 是相对示例所在包根目录的路径,换成你自己项目的路径即可):
use dioxus::prelude::*;
static ASSET_PATH: Asset = asset!("/examples/assets/logo.png");
fn main() {
dioxus::launch(app);
}
fn app() -> Element {
rsx! {
div {
h1 { "This should show an image:" }
img { src: ASSET_PATH }
}
}
}
在 UI 中引用资源
三种资源在 rsx 中的挂法不同:
图片:把 Asset 直接赋给 img 的 src,如上例。
CSS:用 Stylesheet 组件渲染 <link rel="stylesheet"> 到文档 head。它不要求必须写在树的最顶层,放在树中任意位置都会被收集进 <head>。stylesheet 示例 的做法:
use dioxus::prelude::*;
const STYLE: Asset = asset!("/examples/assets/stylesheet.css");
fn app() -> Element {
rsx! {
// Placing the Stylesheet anywhere in the tree is fine — it's collected into <head>
Stylesheet { href: STYLE }
h1 { "Styled with a CSS file" }
}
}
JavaScript:在 manganis README 中,JS 资源的推荐方式是用 AssetOptions::js() 的 with_static_head(true) 选项,让 CLI 在文档 head 中追加指向该资源的 <script> 标签,无需自己在 rsx 里手写标签:
use manganis::{asset, Asset, AssetOptions};
// Vendored UMD library: copy verbatim, emitted as a classic <script>.
const SWEETALERT: Asset = asset!(
"/assets/sweetalert2.all.min.js",
AssetOptions::js().with_minify(false).with_static_head(true)
);
// Authored ES module with local imports: auto-detected from the top-level
// `import`/`export`, bundled and minified into a single ESM file, emitted as
// `<script type="module">`.
const APP: Asset = asset!(
"/assets/app.js",
AssetOptions::js().with_static_head(true)
);
注意 asset! 声明的资源常量必须被 Rust 代码实际使用,宏才会把它包含进二进制;如果资源在 Rust 代码之外使用且你明确知道它的哈希,需要给常量加 #[used] 属性(见 manganis-core 的 builder 文档)。
自动优化:图片、CSS 与 JS 各做了什么
图片——编译时即可做尺寸缩放和格式转换:
use manganis::{ImageFormat, Asset, asset, ImageSize, AssetOptions};
// You can collect images which will be automatically optimized
pub const PNG_ASSET: Asset = asset!("/assets/image.png");
// Resize the image at compile time to make the assets smaller
pub const RESIZED_PNG_ASSET: Asset =
asset!("/assets/image.png", AssetOptions::image().with_size(ImageSize::Manual { width: 52, height: 52 }));
// Or convert the image at compile time to a web friendly format
pub const AVIF_ASSET: Asset = asset!("/assets/image.png", AssetOptions::image().with_format(ImageFormat::Avif));
文档给出的格式取舍(images.rs):Webp 和 Avif 对大多数图片是较好的默认值;Avif 压缩率略优于 Webp,但并非所有浏览器都支持;Png 压缩效果差,不建议用于大图。with_size 适合「图片只在一个位置展示」的场景——按显示尺寸设置,加载更快。另有 with_preload(true) 让图片尽早开始加载。
CSS——AssetOptions::css() 的 minify 默认为 true,即默认压缩(css.rs);可选 with_preload(true)、with_static_head(true)(编译期静态插入)。
JS——CLI 会自动检测每个 .js 资源是 ES module(存在顶层 import/export 或 import.meta)还是经典脚本,并分别处理:
with_minify(true)(默认):就地压缩。经典脚本原样压缩、不改变格式;ES module 会被压缩并打包——本地相对 import 内联成单个 ESM 文件,http:///https://的 import 保留为外部语句由浏览器运行时解析;with_minify(false):逐字节原样复制,适用于不想被再处理的预构建第三方库;with_static_head(true):向文档 head 追加<script>标签,检测到(或声明为)ES module 时输出<script type="module" ...>,否则输出普通<script>;with_preload(true):为该资源输出<link rel="preload" as="script">;with_module(true):即使自动检测判断不是,也强制按 ES module 处理。适用于只有副作用、没有顶层import/export的模块。*.mjs文件始终按 module 处理,*.cjs始终按经典脚本处理。
缓存失效:manganis 默认给资源路径加哈希后缀,使资源可以带长过期时间发布,内容一变哈希就变,浏览器自动拉取新版本。构建后的输出文件名形如 style-{hash}.css、photo-{hash}.webp(架构说明中的 示例,具体哈希值随内容变化,不是固定值)。
可选资源与开发/生产的解析差异
如果某个资源不一定总是随包发布,用 option_asset! 优雅降级:
use manganis::{Asset, asset, option_asset};
const REQUIRED: Asset = asset!("/assets/style.css");
const OPTIONAL: Option<Asset> = option_asset!("/assets/missing.css");
运行时的解析行为分两种模式(08-ASSETS.md):
- 开发模式(非打包应用):
Asset::resolve()返回源文件的绝对路径,浏览器/原生环境直接访问原始文件; - 生产模式(打包应用):
Asset::resolve()用base_path()(例如/app)拼接资源输出路径,返回形如/app/assets/{output-filename}的地址。
同一个 Asset 实例在两种配置下都能工作,代码无需改动。平台侧的落地位置文档也有说明:web(WASM)通过 HTTP fetch() 拉取;桌面端按打包结构从 ../Resources/assets/(macOS)、../lib/{product}/assets/(Linux)、assets/(Windows)读取;Android 走 NDK AssetManager 访问 APK 的 assets/ 目录。
构建与验证
准备工作只有两项:
- 安装 Dioxus CLI:
cargo install dioxus-cli(CLI README); - 应用依赖
dioxuscrate 即可,asset!相关的 manganis 依赖由它的lib特性默认带入(见 dioxus/Cargo.toml 中lib特性列表包含asset)。资源文件放在资源声明所在包的根目录树下,例如示例使用的assets/目录。
执行构建:
dx build --release
该命令用于构建项目以便部署到 web 服务器(仓库 pwa 示例 README 中的用法)。本地迭代也可以用 dx 开发模式:开发模式下资源直接从源文件解析,修改 CSS/图片刷新即可看到,stylesheet 示例 说明中也提到样式文件在开发期可热重载。
验证成功的判断依据:
- 资源进入包中:所有在 Rust 代码中用
asset!声明的资源都会随 bundle 输出;在构建产物中应能看到带哈希后缀的资源文件(如style-{hash}.css,文件名中的哈希是文档示例格式,实际值由内容决定); - 页面行为:图片正常显示、CSS 生效、JS 按预期注入
<head>(module 检测正确时是<script type="module">); - 缓存失效生效:修改资源内容重新构建后,输出文件名中的哈希随之变化。
版本兼容性与限制
- CLI 版本:0.7.2 及以上的
dx使用新的__ASSETS__{hash}符号(CBOR 序列化);0.7.0–0.7.1 的 CLI 使用旧的__MANGANIS__{hash}符号。CLI 会优先尝试新格式,失败时回退旧格式(版本兼容说明)。若用旧版 CLI 处理新版本产出的二进制可能出现资源解析问题,升级 CLI 是最直接的办法。 - CLI 调试构建限制:从本地目录安装的 CLI 在 debug profile 下构建项目会失败,CLI README 标注了这一点(尚在调查中),生产验证请使用
--release。 - 路径限制:
asset!校验路径必须存在且位于 crate 内部,跨包引用时以资源声明所在包的根目录为基准写绝对路径(如仓库示例中的/examples/assets/logo.png)。 - Avif 兼容性:文档明确 Avif 不被所有浏览器支持,面向广泛浏览器兼容时用
with_webp()作为默认。
按以上路径完成后,资源即通过 asset! 宏统一进入 bundle:开发期直接读源文件,构建后由 CLI 压缩、转格式并加哈希发布,同一份 Rust 代码无需为 web、桌面和移动端分别处理资源路径。