RustDesk 构建完全指南：从依赖安装到 Docker 构建与源码结构解析

2026-09-04 14:28:26作者：尤峻淳Whitney

RustDesk 是一款用 Rust 编写的开源远程桌面软件，可自托管部署作为 TeamViewer 的替代品，开箱即用、无需复杂配置，数据完全由用户自行掌控。本文基于仓库内官方挪威语版 README（docs/README-NO.md）整理并扩展，完整覆盖构建依赖安装、Linux 各发行版编译步骤、Docker 容器化构建以及源码目录结构，帮助你从零开始成功构建 RustDesk 客户端，并理解各核心模块在代码库中的位置。

前置说明：GUI 方案与依赖概览

桌面版 RustDesk 使用 Flutter 或 Sciter（已弃用）作为 GUI 框架。本文档的构建步骤仅针对 Sciter 方案，因为它更易上手、门槛更低；Flutter 版本的构建方式可参考仓库的 CI 流程（flutter 目录包含完整的 Android/iOS/Linux/macOS/Windows 工程与构建脚本，如 flutter/build_android.sh、flutter/build_fdroid.sh）。

从源码结构看，当前仓库的 Cargo.toml 将 flutter 定义为可选 feature（Cargo.toml：flutter = ["flutter_rust_bridge"]），默认构建不带该 feature，因此 cargo run 走的是 Sciter UI 路径。两种方案的核心依赖一致，都需要通过 vcpkg 安装四个 C/C++ 库：

依赖库	用途
`libvpx`	VP8/VP9 视频编解码，远程画面传输的核心编码引擎
`libyuv`	YUV 色彩空间转换与缩放
`opus`	音频编码（远端音频传输）
`aom`	AV1 视频编码

对应关系可以直接在仓库中找到佐证：

根目录 vcpkg.json 声明了 libvpx、libyuv、opus、aom 四个核心依赖（host 与 target 双端），并配置了 ./res/vcpkg 与 ./res/vcpkg-triplets 作为 overlay ports/triplets；
Cargo.toml 中 workspace 成员包含 libs/scrap（屏幕捕获）、libs/hbb_common、libs/enigo（键鼠控制）、libs/clipboard 等本地 crate；
主程序入口 src/main.rs 中：非 Android/iOS/Flutter 平台走 ui::start(args)（Sciter UI），Flutter 平台则仅执行 common::global_init() 初始化。

另外，使用 Sciter 方案时需要自行下载对应的 Sciter 动态库并放置到构建产物目录：

Windows：sciter.dll
Linux：libsciter-gtk.so
macOS：libsciter.dylib

原始构建步骤（Windows / macOS / Linux 通用）

文档给出的三步原始流程如下：

准备 Rust 开发环境与 C++ 构建环境；
安装 vcpkg（外部依赖管理器，此处仅作为安装途径说明），并修正 VCPKG_ROOT 环境变量：
- Windows：vcpkg install libvpx:x64-windows-static libyuv:x64-windows-static opus:x64-windows-static aom:x64-windows-static
- Linux/macOS：vcpkg install libvpx libyuv opus aom
运行 cargo run 启动开发构建。

注意事项：

Windows 上需使用带 -static 后缀的 triplet（如 x64-windows-static），以保证静态链接；
VCPKG_ROOT 必须指向 vcpkg 安装根目录，否则构建脚本找不到已安装的依赖；
构建出的二进制需要能加载到 Sciter 动态库，因此运行前要把上一步下载的 .so/.dll/.dylib 放到可执行文件所在目录（Docker 方案中这一步由容器入口脚本自动完成，见下文）。

Linux 构建：各发行版依赖安装

Ubuntu 18 / Debian 10

sudo apt install -y zip g++ gcc git curl wget nasm yasm libgtk-3-dev clang libxcb-randr0-dev libxdo-dev \
        libxfixes-dev libxcb-shape0-dev libxcb-xfixes0-dev libasound2-dev libpulse-dev cmake make \
        libclang-dev ninja-build libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

openSUSE Tumbleweed

sudo zypper install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libXfixes-devel cmake alsa-lib-devel gstreamer-devel gstreamer-plugins-base-devel xdotool-devel

Fedora 28 / CentOS 8

sudo yum -y install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libxdo-devel libXfixes-devel pulseaudio-libs-devel cmake alsa-lib-devel gstreamer1-devel gstreamer1-plugins-base-devel

Arch / Manjaro

sudo pacman -Syu --needed unzip git cmake gcc curl wget yasm nasm zip make pkg-config clang gtk3 xdotool libxcb libxfixes alsa-lib pipewire

这些系统包与 Docker 构建中安装的清单完全对应，可以从根目录 Dockerfile 中验证：g++ gcc git curl nasm yasm libgtk-3-dev clang libxcb-randr0-dev libxdo-dev libxfixes-dev libxcb-shape0-dev libxcb-xfixes0-dev libasound2-dev libpulse-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev ninja-build 等，说明文档命令与 CI/容器化构建保持同一套依赖基线。

其中几类关键依赖的作用：libxcb-*-dev/libxfixes-dev 用于 X11 屏幕捕获与窗口操作（对应 libs/scrap/src/x11/ 捕获后端）；libasound2-dev/libpulse-dev 用于 Linux 音频采集（对应 Cargo.toml 中的 libpulse-simple-binding、libpulse-binding）；nasm/yasm 是汇编器，vcpkg 编译 libvpx/aom 时必需；libgtk-3-dev 是 Sciter GTK 库的前置。

安装 vcpkg

git clone https://github.com/microsoft/vcpkg
cd vcpkg
git checkout 2023.04.15
cd ..
vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$HOME/vcpkg
vcpkg/vcpkg install libvpx libyuv opus aom

注意文档锁定的是 2023.04.15 版本，Dockerfile 同样使用 --branch 2023.04.15 --depth=1 克隆并安装 libvpx libyuv opus aom，保证构建环境一致性。vcpkg 目录中 res/vcpkg/ 下为这些库定制了 portfile 与补丁（如 res/vcpkg/libvpx/ 中的 patch 集合），若使用 manifest 模式则通过根目录 vcpkg.json 自动加载 overlay。

修复 libvpx（仅 Fedora）

Fedora 上 libvpx 的 Makefile 缺少 -fPIC 标志，会导致生成共享对象/链接时出错，需要手动打补丁：

cd vcpkg/buildtrees/libvpx/src
cd *
./configure
sed -i 's/CFLAGS+=-I/CFLAGS+=-fPIC -I/g' Makefile
sed -i 's/CXXFLAGS+=-I/CXXFLAGS+=-fPIC -I/g' Makefile
make
cp libvpx.a $HOME/vcpkg/installed/x64-linux/lib/
cd

该步骤将编好的 libvpx.a 静态库回拷到 vcpkg 安装目录，后续 cargo 构建即可正常链接。其他发行版无此问题，可跳过。

完整构建流程（Linux 示例）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
git clone https://github.com/rustdesk/rustdesk
cd rustdesk
mkdir -p target/debug
wget https://raw.githubusercontent.com/c-smile/sciter-sdk/master/bin.lnx/x64/libsciter-gtk.so
mv libsciter-gtk.so target/debug
VCPKG_ROOT=$HOME/vcpkg cargo run

要点解析：

cargo run 会触发 build.rs 构建脚本与 cc crate 编译 C/C++ 源码（如 Windows 平台的 src/platform/windows.cc）；
当前仓库要求 Rust 工具链版本不低于 1.75（Cargo.toml：rust-version = "1.75"）；
libsciter-gtk.so 必须放在 target/debug/ 下，因为运行时动态库按可执行文件所在目录搜索；
release 构建可使用 cargo build --release，Cargo.toml 中 release profile 启用了 lto = true、codegen-units = 1、strip = true 等体积与性能优化选项。

使用 Docker 构建

如果不想在宿主机上安装整套依赖，可以直接使用仓库根目录提供的 Dockerfile 构建容器。该镜像基于 debian:bullseye-slim，内部已预装全部系统依赖、CMake 3.30.6、锁定版本的 vcpkg 及其四个依赖库，并预先下载好 libsciter-gtk.so 和 Rust 工具链（Dockerfile）。

第一步：克隆仓库并构建镜像：

git clone https://github.com/rustdesk/rustdesk
cd rustdesk
docker build -t "rustdesk-builder" .

第二步：每次需要构建时运行容器：

docker run --rm -it -v $PWD:/home/user/rustdesk -v rustdesk-git-cache:/home/user/.cargo/git -v rustdesk-registry-cache:/home/user/.cargo/registry -e PUID="$(id -u)" -e PGID="$(id -g)" rustdesk-builder

参数说明：

-v $PWD:/home/user/rustdesk：将仓库挂载进容器，构建产物直接落在宿主机；
两个 cargo 命名卷用于缓存依赖索引，第二次构建起显著提速（首次构建因依赖缓存需要更长时间）；
PUID/PGID 保证容器内生成文件与宿主机用户权限一致。

入口脚本 entrypoint.sh 负责实际构建，其行为值得了解：

解析命令行参数，--release 会切换到 release 构建并把 libsciter-gtk.so 拷贝到 target/release/（entrypoint.sh）；
支持 --target <triple>，容器内会自动执行 rustup target add 添加交叉编译目标；
最终统一执行 VCPKG_ROOT=/vcpkg cargo build --locked $argv（entrypoint.sh），保证依赖版本锁定。

使用限制（原文强调，务必遵守）：

可执行文件在宿主机仓库的 target/ 目录下查找并运行：
```
target/debug/rustdesk
```
或 release 版本：
```
target/release/rustdesk
```
必须从 RustDesk 仓库根目录运行上述命令，否则应用可能找不到正确的资源文件；
cargo install、cargo run 等子命令在此方案下不受支持——它们会在容器内部安装/运行程序，而不是宿主机。需要额外构建参数时直接附加在 docker run 命令末尾即可，例如构建优化版 release 版本时追加 --release。

源码文件结构

文档给出的目录结构说明是理解 RustDesk 代码库的地图，结合仓库现状逐项说明：

libs/hbb_common：视频编解码调度、配置管理、TCP/UDP 协议封装、protobuf 定义、文件传输用文件系统功能及其他工具函数，是整个项目最底层的公共库（workspace 成员，Cargo.toml）；
libs/scrap：屏幕捕获，包含 X11（libs/scrap/src/x11/）、Wayland（libs/scrap/src/wayland/）、Windows DXGI（libs/scrap/src/common/dxgi.rs）、macOS Quartz（libs/scrap/src/quartz/）、DRM 等捕获后端，以及 VPX/AOM/硬解相关实现（libs/scrap/src/common/vpx.rs、libs/scrap/src/common/aom.rs），与上文 vcpkg 依赖直接对应；
libs/enigo：跨平台键鼠控制，按平台拆分实现（libs/enigo/src/linux/、libs/enigo/src/macos/、libs/enigo/src/win/）；
libs/clipboard：Windows/Linux/macOS 的文件复制粘贴实现（libs/clipboard/src/lib.rs 及 platform 子目录）；
src/ui：已弃用的 Sciter UI（HTML/CSS/TS 混合实现，如 src/ui/index.html、src/ui/remote.rs）；
src/server：服务端各服务——音视频（src/server/video_service.rs）、输入（src/server/input_service.rs）、剪贴板（src/server/clipboard_service.rs）以及网络连接处理（src/server/connection.rs）；
src/client.rs：发起点对点连接的客户端入口逻辑；
src/rendezvous_mediator.rs：与 RustDesk 服务端（rustdesk-server）通信的中介模块，等待建立直接远程控制连接（TCP 打洞）或中继转发连接；
src/platform：平台相关代码，按操作系统拆分（src/platform/linux.rs、src/platform/macos.rs、src/platform/windows.rs 及 Windows 特权脚本等）；
flutter：Flutter 代码，覆盖桌面与移动端，按 desktop/mobile 页面组织（flutter/lib/），Dart 侧模型层在 flutter/lib/models/。

从源码结构看，入口 src/main.rs 按编译目标分流：Flutter 构建只做全局初始化，其余平台调用 core_main 解析命令行后进入 ui::start；Cargo.toml 还声明了 naming、service 两个独立二进制，分别用于设备命名与后台服务。

小结与适用前提

本文全部步骤基于当前仓库（版本 1.4.9，见 Cargo.toml）实际内容：vcpkg 锁定 2023.04.15，核心依赖为 libvpx libyuv opus aom，Rust 版本要求 >= 1.75；
Sciter 路径文档标注该 GUI 方案已弃用，长期维护的重点在 Flutter 路径，构建 Flutter 版应参考仓库 CI 与 flutter 目录下的平台脚本；
Docker 方案仅支持 cargo build 类操作，cargo run/install 不可用，且运行二进制必须在仓库根目录执行。