dioxus-knowledge-patch

Dioxus 知识补丁

注意

Dioxus 0.8.0-alpha.1 是预发布指南，正式发布前可能会有变更。

在创建、迁移、调试、测试或打包 Dioxus 应用时使用此技能。选择 API 前先检查项目：稳定版与预发布版的行为有所不同。

参考索引

参考资料	主题
components-reactivity.md	组件、属性、信号、存储、钩子、任务、资源、悬念、错误、事件
assets-styling-ui.md	资源、RSX、属性、CSS、Tailwind、文档元素、评估、无障碍 UI
fullstack-routing.md	服务端函数、Axum、SSR、水合、表单、流式传输、WebSockets、文件、路由
cli-platforms-bundling.md	CLI、项目配置、Web/桌面/移动端、日志记录、调试、部署、安装程序
renderers-testing-internals.md	原生与自定义渲染器、LiveView、直接 SSR、测试、热修补、WASM 拆分、原生插件
migration-edge-cases.md	破坏性 API 变更、弃用、依赖边界、行为边缘情况、预览版注意事项
ecosystem-sdk-components.md	样式化组件、基元、虚拟列表、属性、SDK 服务、持久化、计时器

首要检查项

• 修改 API 前，检查 Cargo.toml、Cargo.lock、Dioxus.toml、已启用的 Cargo 功能以及已安装的 dx 版本。
• 确定应用属于 Web、桌面端、移动端、全栈、LiveView、仅 SSR，还是自定义渲染器；同一份源代码可能会为多个目标编译。
• 将仅客户端和仅服务端依赖分别置于对应的 Cargo 功能之后。服务端函数体并不会让附近的原生代码或机密信息免于进入客户端构建。
• 优先使用统一的 dioxus crate 及其当前 prelude。低级运行时、调度器和渲染器 API 可能需要显式导入。
• 诊断原生或移动端工具链故障前，先运行 dx doctor。
• 将预览版 API 视为需主动启用的功能，并在将其用于稳定版项目之前，确认依赖项和 CLI 的具体版本。

破坏性变更与弃用

组件不再接收作用域

组件直接接收属性；Element 是静态且基于结果的；spawn 和 consume_context 等运行时辅助函数不再需要 Scope 参数。

fn Counter() -> Element {
    let mut count = use_signal(|| 0);
    rsx! {
        button { onclick: move |_| count += 1, "{count}" }
    }
}

使用 rsx! {} 渲染空内容。普通错误可以通过 ? 传播到上层的 ErrorBoundary；不要再使用已移除的 VNode::None 模式。

优先使用易读的属性和存储透镜

响应式可读属性使用 ReadSignal<T>。RSX 可以将信号、memo、存储透镜或普通值转换为它。通用存储辅助函数应接受 Readable 或 Writable 约束，因为生成的透镜类型有意不命名。

#[component]
fn Title(title: ReadSignal<String>) -> Element {
    rsx! { h1 { "{title}" } }
}

ReadOnlySignal 已弃用。对于其子项需要逐项响应式透镜、而不是通过信号读取守卫借用的集合，请使用 Store。

根据平台选择启动方式和功能

使用 dioxus::launch 或 LaunchBuilder。渲染器功能位于主 dioxus crate 中；全栈客户端和服务端构建必须分别启用 web 和 server。

[features]
web = ["dioxus/web"]
desktop = ["dioxus/desktop"]
server = ["dioxus/server"]

旧的 dioxus-lib crate 已移除。如果只需要框架库层，请使用带有 lib 功能的 dioxus。

事件取消必须同步进行

在任何 .await 之前调用 event.prevent_default()。Web 表单默认会提交，因此如果应用自行处理提交，就应取消 onsubmit。LiveView 会在服务端执行 Rust 处理函数，无法及时取消浏览器默认行为；此时请使用同步的浏览器端 JavaScript。

资源路径和选项已更改

asset! 路径相对于当前 crate 根目录，且以 / 开头。 使用 AssetOptions 及其变体构造函数；不要使用旧的 mg! 或 ImageAssetOptions::new() 形式。

let image = asset!(
    "/assets/image.png",
    AssetOptions::image().with_format(ImageFormat::Avif),
);

全栈类型面向 Dioxus

使用显式路由宏来定义稳定的 API，尤其是面向原生客户端的 API。 Dioxus 的 ServerFnError 并不是名称相同的通用 server_fn 类型， 公共依赖边界应与 Dioxus 预期的版本保持一致。

如果锁定的稳定版项目在与 0.7.5 相关的依赖更正后仍无法运行，请先运行 cargo update，再更改源代码。

响应式与异步工作

读取会建立订阅

在渲染期间读取信号会使组件订阅该信号。仅在事件处理程序中读取则不会。 备忘录、效果、期物、资源和加载器会根据各自的执行语义追踪读取；如需有意不订阅地读取，请使用 peek()。

同一运行时步骤中的信号写入会批处理。.await 会结束该步骤，从而允许待处理的 UI 绘制。写入后立即读取依赖于该信号的备忘录时，会同步重新计算。

选择合适的任务原语

• use_action 会存储最新的 Result，并在再次调用时取消过时的工作。
• spawn 会为当前组件持有一个 !Send 期物，并在组件卸载时取消它。
• spawn_forever 会将整个应用生命周期的工作附加到根节点；不得让它持有生命周期更短的信号。
• 将受 CPU 限制的工作移到原生线程或 Web Worker 中执行。

资源、加载器与 suspense

当被追踪的依赖发生变化时，use_resource 会重新启动。如果其结果错误需要实现 Clone，请使用 CapturedError 或 dioxus::Ok。use_loader 会通过 suspense 和错误边界处理加载与错误状态；为避免瀑布式加载，请在第一个 ? 之前启动彼此独立的加载器。

全栈 suspense 数据必须使用服务端期物，以便将结果序列化用于水合。将响应式读取保留在外层闭包中。

全栈速查

组合 Axum 服务端

#[cfg(feature = "server")]
dioxus::serve(|| async move {
    use dioxus::server::axum::routing::get;

    Ok(dioxus::server::router(app)
        .route("/health", get(|| async { "ok" })))
});

添加到组装后路由器中的普通 Axum 路由优先于 SSR 回退路由。对于已认证会话等请求扩展，请使用仅限服务端的提取器，确保它们永远不会进入客户端负载。

保留 HTTP 语义

• 无法识别的服务端错误会变为 HTTP 500；请使用 OrHttpError 或实现状态转换 trait 的类型化错误。
• 处理 SSR 错误的 ErrorBoundary 必须通过 FullstackContext 重新提交其 HTTP 状态。
• 首个流式数据块提交后，标头和状态将被冻结。
• 原生客户端支持服务端函数、文件、流和 WebSocket，但不支持 SSR、水合数据、SSG 或 FullstackContext。

保持水合结果确定性

水合期间，客户端会重新运行组件树。将同步的非确定性操作放入 use_server_cached，将异步的非确定性操作放入服务端期物或加载器，并将仅限浏览器的读取放入 use_effect。不要在服务端缓存闭包中放置副作用。

路由速查

派生 Routable，挂载 Router::<Route> {}，并使用类型化变体进行导航。匹配时优先选择静态路径，其次是动态字段，最后是兜底路径；如有平局，则按枚举顺序决定。如果类型化值缺失或格式错误，查询和哈希片段不会导致路由被拒绝。

#[derive(Clone, PartialEq, Routable)]
enum Route {
    #[route("/")]
    Home,
    #[route("/post/:id")]
    Post { id: u64 },
}

布局通过 Outlet::<Route> {} 渲染子项。当 URL 行为很重要时，尤其是使用浏览器、哈希、LiveView 或内存路由时，请显式配置历史记录提供程序。

资源、样式和 RSX

• 只有在 Rust 优化后仍保留 Asset 值的资源才会被打包；请从最终应用中保留导出的库资源，或将有意间接引用的静态变量标记为 #[used]。
• 在资源目录下构建子路径时，请使用格式化后的哈希 Asset，而不是其源名称。
• 属性展开按源代码中的顺序生效；后面的值优先。None 会移除动态属性。
• 未知属性和所有 Web 组件属性都要加引号。带连字符的标签会创建无类型的 Web 组件。
• 在包含多个节点的 RSX 中，将 key 放在第一个节点上。
• 对于 Tailwind 4，请在输入文件中导入 Tailwind，使用 @source 扫描 Rust 源代码，并包含 DX 生成的样式表。

CLI 和平台工作流

dx doctor
dx serve --web
dx build --raw-json-diagnostics
dx bundle --json-output

CLI 可为 Web、桌面、iOS、Android、全栈和普通 Rust 包提供服务。原生捆绑包受主机平台限制；移动端构建还依赖平台 SDK 和签名配置。使用 --log-to-file 获取完整诊断信息；当其他工具需要复现 DX 的构建参数时，使用 dx print。

要部署全栈 Web 应用，请同时发布生成的 public 目录和服务器可执行文件。生产容器应使用 IP=0.0.0.0 进行绑定；dioxus::launch 会读取 IP 和 PORT。