【Dioxus】Windows 环境下 Rust + Dioxus 安装配置笔记

一、环境信息

项目	版本 / 说明
操作系统	Windows 10 / 11
Rust	1.98.0
Cargo	1.98.0
终端	CMD / PowerShell
目标平台	桌面（Desktop）/ Web

---

二、Rust 安装（已完成 ✅）

安装方式

• 使用 rustup-init.exe 安装
• 安装过程中选择 选项 1，通过 Visual Studio Community 安装 C++ 编译工具链（MSVC）

验证安装

rustc -V   # 应显示 rustc 1.98.0
cargo -V   # 应显示 cargo 1.98.0

当前状态

• ✅ Rust 1.98.0
• ✅ Cargo 1.98.0
• ✅ MSVC 编译工具链已就绪

💡 如果提示缺少链接器，请确保已通过 Visual Studio Installer 安装 "使用C++的桌面开发" 工作负载。

---

三、Dioxus 安装配置

3.1 核心环境安装

步骤 1：添加 WebAssembly 编译目标

rustup target add wasm32-unknown-unknown

用于开发 Web 应用，桌面应用也建议添加。

步骤 2：安装 cargo-binstall（加速工具）

cargo install cargo-binstall

cargo-binstall 可下载预编译二进制文件，避免从源码编译，大幅提升安装速度。

步骤 3：安装 Dioxus CLI（dx）

推荐优先级从高到低：

方式	命令	说明
方式一（推荐）	cargo binstall dioxus-cli	下载预编译二进制，速度最快
方式二（备选）	下载官方 Release 中的 dx.exe	放入 %USERPROFILE%\.cargo\bin\ 目录
方式三（源码编译）	cargo install dioxus-cli	耗时约 5-10 分钟，需要多个依赖项

步骤 4：验证安装

dx --version

步骤 5：环境检查

dx doctor

该命令用于检查并提示是否缺少跨平台开发所需的工具链或依赖项。

3.2 解决 GitHub 访问异常的影响

由于中国大陆地区无法直连 GitHub，在编程环境中会面临网络受限问题。针对不同场景，处理方案如下：

场景一：Cargo 依赖下载加速（配置国内镜像源）

在 %USERPROFILE%\.cargo\config.toml 中添加以下内容：

[source.crates-io]
replace-with = 'tuna'

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

此配置可显著加速编译依赖的下载速度。其他可选镜像源：

镜像源	配置方式
中科大（USTC）	sparse+https://mirrors.ustc.edu.cn/crates.io-index/
清华（Tuna）	sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/
上海交大（SJTU）	sparse+https://mirrors.sjtug.sjtu.edu.cn/crates.io-index/

场景二：Git 拉取项目模板加速

dx new 默认从 GitHub 拉取代码模板，可手动采用以下方式加速：

• 方式一 ：使用 GitHub 加速镜像，将 github.com 替换为 kkgithub.com 或 ghproxy.com 进行 git clone
• 方式二：直接从浏览器下载模板 ZIP 包

场景三：解决默认静态资源加载缓慢

Dioxus 默认首页引用了 Google 字体（fonts.googleapis.com），该域名在国内不可达，导致页面初始化可能长时间停滞。

解决方案：

1. 复制 dev.index.html 至项目根目录，重命名为 index.html
2. 删除其中对 Google Fonts 的 @import 指令
3. 改为本地引入字体文件

---

四、Windows 平台特定依赖：WebView2

Windows 桌面应用依赖于 WebView2 库，该库通常已随新版 Windows 和 Edge 浏览器一起安装。

情况	操作
已安装 Edge	✅ 无需额外操作，Dioxus 即可正常运行
未安装 WebView2	通过 Microsoft 官方下载安装 WebView2 Runtime

Microsoft 提供的三种安装选项

选项	说明	推荐度
选项 1	小型的"常青"引导程序，自动从微软 CDN 拉取最新版	⭐ 推荐
选项 2	小型安装程序，从微软 CDN 获取 WebView2	可选
选项 3	静态链接版本，打包到最终二进制中（适合离线用户）	特殊场景

---

五、创建并运行第一个项目

# 1. 创建项目
dx new my_app

# 2. 进入项目目录
cd my_app

# 3. 桌面平台运行
dx serve --platform desktop

# 4. Web 平台运行（可选）
dx serve --platform web

---

六、开发策略与 Web 起步路径

Dioxus 支持一套代码构建 Web、桌面和移动端应用，通过 Web 平台起步验证业务逻辑是低成本且高效的路径。

6.1 架构定位

阶段	说明
Web 阶段	dx serve 启动本地开发服务器，应用编译为 WASM 在浏览器中运行，天然支持手机访问，适合验证核心逻辑
桌面阶段	将 dioxus 依赖的 feature 切换为 desktop 即可迁移为原生桌面应用，打包体积极小（约 15MB），且支持直接调用系统 API

6.2 Web 起步功能规划

功能模块	实现方案
通讯录与文字聊天	利用 use_coroutine 处理异步消息，配合 Router 进行页面导航；Web 平台可利用 use_eval 调用浏览器原生 API 或 WebSocket 实现实时通讯
聊天式流程处理	可借鉴 dioxus-ai 库的 use_chat hook 架构，构建流式输出的交互界面
计划表（任务管理）	利用 Dioxus 0.7 版本新增的 stores 原始类型，实现嵌套响应式状态管理（例如支持对标记为"已完成"的局部任务树进行精准更新）
文档展示	PDF 渲染 ：推荐使用 az-file-viewer 组件库，已封装好支持 PDF、DOCX、Markdown 格式的 Dioxus 组件；底层实现 ：可使用 Rust 的 pdfium-render 库与 Dioxus 结合构建查看器

---

七、开发工具与进阶建议

7.1 CLI 常用命令

命令	说明
dx new <项目名>	创建新项目
dx serve	运行并启用热重载
dx serve --platform desktop	桌面平台运行
dx serve --platform web	Web 平台运行
dx bundle	打包发布
dx doctor	环境诊断

7.2 状态管理

建议优先使用 Dioxus 0.7 引入的 Signals 和 Stores 机制进行细粒度响应式更新，性能优于传统方式。

机制	适用场景
use_signal	简单局部状态
Stores	复杂嵌套状态管理，支持局部精准更新
use_coroutine	异步消息处理

7.3 新特性辅助

若项目需要前后端分离或服务端渲染，可关注 Dioxus 0.7 的 Fullstack 模块，它支持：

• WebSocket 实时通信
• 流式 API
• 服务端渲染（SSR）

---

八、常见问题与解决方案

问题	解决方案
提示缺少链接器	确保已通过 Visual Studio Installer 安装 "使用C++的桌面开发" 工作负载
WebView2 未安装	下载安装 WebView2 Runtime
下载速度慢	配置国内镜像源（见 3.2 节）
dx serve 报错	运行 rustup update 更新 Rust 工具链
OpenSSL 相关报错	确保已安装文档中列出的相关依赖（Windows 下通常不常见）
页面加载停滞（Google Fonts）	按 3.2 节方法移除 Google Fonts 引用
dx new 拉取模板超时	使用加速镜像或手动下载模板 ZIP 包

---

九、安装进度追踪

步骤	任务	状态
1	安装 Rust + MSVC 工具链	✅ 已完成
2	添加 WASM 目标	✅ 已完成
3	安装 cargo-binstall	✅ 已完成
4	安装 Dioxus CLI	✅ 已完成
5	验证 dx 命令	✅ 已完成
6	配置 Cargo 国内镜像源	✅ 已完成
7	检查 WebView2 环境	✅ 已确认
8	创建第一个项目	⬜ 待执行

---

十、参考链接

资源	链接
Rust 官网	https://www.rust-lang.org/
Dioxus 官网	https://dioxuslabs.com/
Dioxus GitHub	https://github.com/DioxusLabs/dioxus
WebView2 下载	https://developer.microsoft.com/en-us/microsoft-edge/webview2/
Dioxus 安装脚本	https://dioxus.dev/install.sh
清华 Cargo 镜像	https://mirrors.tuna.tsinghua.edu.cn/help/crates.io/