怎么读这一卷

主线位置：三条主线的总览。本页把更新主线、首屏主线和调用主线各画一遍，标出每一步落在哪个函数上、哪一页讲它；再讲这三条线为什么会分布在两份编译产物里：同一份代码按 feature 编成 wasm 客户端和服务端二进制，debug_assertions 又让 debug 和 release 走不同的代码。「一次点击」和「一次页面请求」用完整的例子把前两条线各走一遍。

flowchart TB
  start[从这里开始] --> q{读这一卷为了什么}
  q -->|会用| use1[01 全景]
  use1 --> use2["03 的 scope 与 hooks"]
  use2 --> use3["04 响应式"]
  use3 --> use4["06 的水合与 server function"]
  q -->|读懂实现| all[00 到 11 按顺序]

锁定版本

源码链接一律指向 tag：https://github.com/DioxusLabs/dioxus/blob/v0.7.10/packages/...。git diff --stat v0.7.9 v0.7.10 的结果是 6 个文件：

 Cargo.lock                        | 114 +++++++++++++++++++-------------------
 Cargo.toml                        | 104 +++++++++++++++++-----------------
 packages/cli/src/build/builder.rs |   4 +-
 packages/cli/src/build/link.rs    |   4 +-
 packages/cli/src/build/request.rs |  12 +++-
 packages/cli/src/serve/runner.rs  |   2 +-
 6 files changed, 128 insertions(+), 112 deletions(-)

根 Cargo.toml 和 Cargo.lock 的改动只有版本号，另外 4 个文件都在 CLI 里。所以本卷讲的运行时代码就是本站在跑的代码。

本站的 dx 是 0.7.9，本卷实验用同一个 dx 编 0.7.10 的库。dx 会打一行 ERROR，但照常编完：

  0.57s ERROR 🚫dx and dioxus versions are incompatible!
                  • dx version: 0.7.9
                  • dioxus versions: [0.7.10]

这是 CLI 启动时的版本检查，只要工作区里 dioxus 的最低版本高于 dx、或最高版本低于 dx，就用 tracing::error! 打这一行，不中断构建。

三条主线

全卷沿三条线展开，每页开头都会标出本页在哪条主线上。

更新主线：一次点击

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

flowchart TB
  clickev["click 冒泡到根"] --> handler["闭包找 dioxus-id"]
  handler --> he["handle_event"]
  he --> userfn["count += 1"]
  userfn --> drop1["写锁释放 通知订阅者"]
  drop1 --> dirty["mark_dirty"]
  dirty --> msg["发 Immediate"]
  msg --> ri["render_immediate"]
  ri --> diffn["run_scope 和 diff"]
  diffn --> muts["SetText 指令"]
  muts --> flush["flush_edits 交给 JS"]
  flush --> eff["下一轮跑 effect"]

第 1 步的「委托」只对冒泡事件成立；第 9 步没有等 requestAnimationFrame，web 主循环里等空闲时间、等动画帧的两行代码是注释掉的，render_immediate 之后立刻 flush_edits。逐步的实验见一次点击。

首屏主线：一次页面请求

flowchart TB
  req["GET 落到 fallback"] --> rh["render_handler"]
  rh --> pool["render_to"]
  pool --> pin["spawn_pinned"]
  pin --> vdom["新建 VirtualDom"]
  vdom --> rip["rebuild_in_place"]
  rip --> sus["等 suspense"]
  sus --> html["带水合标记的 HTML"]
  html --> data["写水合数据"]
  data --> wasm["浏览器加载 wasm"]
  wasm --> reb["不发指令的 rebuild"]
  reb --> rehy["rehydrate 认领节点"]

逐步的实验（curl 拿到的 HTML 每一块是什么）见一次页面请求。

调用主线：一次 server function

#[post("/api/double")]
async fn double(n: i32) -> Result<i32, ServerFnError> {
  Ok(n * 2)
}

flowchart TB
  mac["post 属性宏"] --> srv["cfg server 这一半"]
  mac --> cli["cfg not server 这一半"]
  srv --> inv["inventory 登记"]
  inv --> reg["启动时挂路由"]
  cli --> creq["ClientRequest::new"]
  creq --> fetch["编码参数 发请求"]
  fetch --> reg
  reg --> runfn["解码 执行 编码"]
  runfn --> dec["客户端解码成 Result"]

一份代码，编两次

三条主线横跨两份产物：更新主线大部分在浏览器的 wasm 里，首屏主线的前半段在服务端二进制里，调用主线两边各一半。它们来自同一个 crate、同一份 src/，区别全在编译时打开的 feature 上。

dx 怎么编

实验 crate 的 Cargo.toml 是 dioxus 模板的写法：

[dependencies]
dioxus = { version = "=0.7.10", features = ["router", "fullstack"] }

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

dx build --platform web --fullstack --verbose 的开头几行：

  0.57s DEBUG Found feature web for renderer web
  0.58s DEBUG Target Info:
                • features: ["web"]
                • triple: wasm32-unknown-unknown
                • bundle format: Web
...
  0.58s DEBUG Found feature server for renderer server
  0.58s DEBUG Target Info:
                • features: ["server"]
                • triple: aarch64-apple-darwin
                • bundle format: Server

dx 在用户 crate 的 [features] 里找「打开 dioxus/web 的那个 feature」和「打开 dioxus/server 的那个」，各起一次 cargo：客户端 --target wasm32-unknown-unknown --features web，服务端用本机 triple、--features server。两次都带 --no-default-features，再把默认集里不是渲染器的 feature 加回去。产物是 dx/<包名>/debug/web/server（服务端二进制）和它旁边的 public/（wasm、JS 胶水、index.html），服务端从 public/ 取静态文件。

feature 怎么往下传

dioxus 门面 crate 的 [features] 表 里，和这两次编译有关的是三个：

?/ 的意思是「这个依赖已经被别的 feature 打开时，才顺带打开它的某个 feature」。所以 fullstack 自己不决定是客户端还是服务端：客户端那次 fullstack + web，dioxus-web 带上 hydrate（它的 hydrate 又拉进带 web feature 的 dioxus-fullstack-core），web 主循环里 should_hydrate 为真，首屏走水合；服务端那次 fullstack + server，dioxus-server 依赖 dioxus-fullstack-core 时写死了 features = ["server"]。默认集（launch、devtools、logger、lib）里没有任何渲染器。

门面 crate 的 src/lib.rs 按同样的 feature 决定导出什么：server 打开时才有 dioxus::server 和 dioxus::serve，fullstack 打开时 prelude 里才有 post、get、server、use_server_future、ServerFnError。它的 crate 文档还列着一个 hot-reload feature，Cargo.toml 里并没有这个 feature。

dioxus::launch(app) 在运行时选平台：LaunchBuilder::new 按 native、desktop、mobile、web、server、liveview 的顺序看哪个 feature 开着，launch 再分派：server 走 dioxus_server::launch_cfg（建 tokio 运行时、起 axum），web 走 dioxus_web::launch::launch。同一行 dioxus::launch(app)，客户端那次编进去的是 web 的启动代码，服务端那次是 axum 的。

cfg 在哪里分叉

分叉发生在三个层次，作用的对象不一样：

第二种最容易出问题。宏生成的 #[cfg(feature = "server")] 判断的是用户 crate 自己有没有一个叫 server 的 feature 并且打开了，和 dioxus 的 server feature 无关。用户 crate 不声明 server 时，rustc 的 check-cfg 会认为这是一个不存在的 cfg 值；宏在函数上加了 #[deny(unexpected_cfgs, reason = ...)]（宏代码），把这个警告升级成错误，并把怎么改写进了 reason。把依赖写成 dioxus = { version = "=0.7.10", features = ["fullstack", "server"] }、不写 [features]，cargo check 的输出（去掉了颜色，reason 里的两段 toml 示例省略）：

error: unexpected `cfg` condition value: `server`
 --> src/main.rs:3:1
  |
3 | #[post("/api/double")]
  | ^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: no expected values for `feature`
  = note: using a cfg inside a attribute macro will use the cfgs from the destination crate and not the ones from the defining crate
  = help: try referring to `post` crate for guidance on how handle this unexpected cfg
  = note: see <https://doc.rust-lang.org/nightly/rustc/check-cfg/cargo-specifics.html> for more information about checking conditional configuration
  = note: 
          ==========================================================================================
            Using Dioxus Server Functions requires a `server` feature flag in your `Cargo.toml`.
            Please add the following to your `Cargo.toml`:
...
error: could not compile `intro-nofeat` (bin "intro-nofeat") due to 1 previous error

声明了 server = ["dioxus/server"]、但构建时没打开它，就不报错了，后果却更隐蔽。同一个 crate，依赖里仍然写死 dioxus/server，main 里 dioxus::launch(app)：dioxus 的 server 开着，所以起的是 axum 服务端；用户 crate 的 server 没开，所以 double 编成了客户端那一半，没有登记。分别用 cargo build 和 cargo build --features server 编，起服务后 curl -X POST -d '{"n":21}' /api/double：

# cargo build
HTTP/1.1 405 Method Not Allowed
allow: GET,HEAD

# cargo build --features server
INFO dioxus_server::server: Registering: POST /api/double
HTTP/1.1 200 OK
content-type: application/json

42

第一种情况服务端日志里没有 Registering 这一行，POST 落到了只认 GET 的 fallback 上。dx 构建时按 [features] 里的名字开 feature，不会出现这种半开的状态；用 cargo 直接编服务端时要记得 --features server。

两份产物里各有什么

在 double 的函数体里加一行 println!("MARKER_IN_SERVER_FN_BODY n={n}")，组件的 rsx 里加一段文本 MARKER_IN_RSX，dx build 之后在两份产物里找这些字符串（grep -c -a，数的是匹配的「行」，非 0 就是存在）：

server                           MARKER_IN_SERVER_FN_BODY   1
server                           MARKER_IN_RSX              1
server                           /api/double                1
public/wasm/intro-fs_bg.wasm     MARKER_IN_SERVER_FN_BODY   0
public/wasm/intro-fs_bg.wasm     MARKER_IN_RSX              1
public/wasm/intro-fs_bg.wasm     /api/double                1

组件两边都有：服务端要渲染它，客户端要水合、更新它。server function 的路径两边都有：服务端用来挂路由，客户端用来发请求。函数体只在服务端：数据库连接、密钥这类只该在服务端出现的代码，写在 server function 里就不会进 wasm；写在组件里、或者写在没被 cfg 包住的普通函数里，就会两边都编。release 构建（--release）的两份产物结果相同。

debug 构建多出来的东西

debug_assertions 在 debug profile 下打开、release 下关闭。dioxus 有两类这样的代码：库里自己的 #[cfg(debug_assertions)]，以及宏生成到用户 crate 里的（rsx! 生成的代码里就有，看的是用户 crate 的 profile）。和本卷有关的：

同一个应用分别 dx build 和 dx build --release，curl 首页拿到的水合脚本：

<!-- debug -->
<script>window.initial_dioxus_hydration_data="hIEY9vb2hRihGGIYTxhrAg==";window.initial_dioxus_hydration_debug_types=["core::option::Option<dioxus_core::render_error::CapturedError>","unknown","unknown","unknown","unknown","unknown","core::result::Result<i32, dioxus_fullstack_core::error::ServerFnError>"];window.initial_dioxus_hydration_debug_locations=["~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/dioxus-server-0.7.10/src/ssr.rs:556:29","unknown","unknown","unknown","unknown","unknown","src/main.rs:11:17"];</script>

<!-- release -->
<script>window.initial_dioxus_hydration_data="hIEY9vb2hRihGGIYTxhrAg==";</script>

数据本身两边一样。debug 多出来的两个数组按槽位对齐：第 0 个槽位是根 suspense 边界的错误（Option<CapturedError>），最后一个是 src/main.rs 第 11 行那个 use_server_future 的 Result<i32, ServerFnError>。调用位置是编译机上的绝对路径，这些信息只在 debug 构建的页面里出现。热重载那一行也可以在 wasm 里找到：debug 的 intro-fs_bg.wasm 里有 _dioxus 这个字符串，release 的没有。两份 wasm 的大小是 52 376 105 和 2 485 919 字节，服务端二进制是 27 934 296 和 6 449 176 字节。

本卷展示输出时都会说明是 debug 还是 release；两者行为不同时两种都跑。

阅读路线

• 只想会用：读 01 全景；03 里的 Scope 与 hooks 和 Suspense 与错误边界；04 响应式；06 里的水合和 server function；遇到报错再查 09 常见坑。
• 想读懂实现：按顺序读。03 是全卷的重点；02 讲清楚 rsx! 产出的 Template 之后，03 的 diff 和 Mutations 才好读。
• 只关心服务端：01 的一次页面请求、06 SSR 与 fullstack、10 在本站中，配合 axum 卷。
• 想自己写一个：读完 02 和 03，直接去 11 动手。

前置知识

• React 式的组件、props 和 hooks。dioxus 的 FAQ 写着「we borrowed hooks from React」。
• async/await。web 上的 future 由 VirtualDom 自己的任务表 poll，服务端渲染跑在 tokio 的本地线程上，见 tokio 卷。
• axum 的 Router、handler、fallback、中间件，见 axum 卷：dioxus::server::router 返回的就是一个 axum::Router。
• serde：server function 的参数和返回值、水合数据都经过 serde，见 serde 卷。

小结

• 全卷对着 dioxus 0.7.10 写；本站用 0.7.9，两个 tag 之间只改了 CLI 的 4 个文件和版本号，运行时代码相同。
• 更新主线：根上的委托监听器 → wasm 闭包找 data-dioxus-id → handle_event → signal 写锁释放 → mark_dirty → SchedulerMsg::Immediate → render_immediate → run_scope + diff → WriteMutations → flush_edits → effect。
• 首屏主线：axum fallback → SsrRendererPool::render_to → 本地线程上每请求一个 VirtualDom → 等 suspense → dioxus_ssr 带水合标记 → 水合数据 → 客户端 rebuild + rehydrate。
• 调用主线：#[post] 生成两半，服务端 inventory 登记、启动时挂路由，客户端编码发请求、解码成 Result<T, ServerFnError>。
• dx 编两次：wasm 带用户的 web feature，服务端带 server，都带 --no-default-features。server function 的两半由宏生成到用户 crate 里的 #[cfg(feature = "server")] 切开，所以用户 crate 必须声明并打开自己的 server feature。
• debug 构建多了热重载、水合调试信息和一些检查，release 里这些代码不存在；两者行为不同时本卷两种都跑。