RustDesk 源码构建完全指南：Linux 依赖环境、vcpkg 编解码栈与 Docker 容器化构建

2026-09-05 21:31:55作者：庞眉杨Will

本文以 RustDesk 仓库的构建文档为主线，完整覆盖从 Sciter GUI 动态库、vcpkg 编解码依赖，到各 Linux 发行版系统依赖安装、本地 cargo run 构建以及 Docker 容器化构建的全部流程，并结合仓库中的 vcpkg.json、Dockerfile、entrypoint.sh 与 Cargo.toml 源码，深入讲解每条构建命令背后的依赖链路与工程约定，帮助你在任意 Linux 发行版上独立完成 RustDesk 的可复现构建。

RustDesk 是一个用 Rust 编写的自托管远程桌面应用，定位为 TeamViewer 的开源替代。它开箱即用、无需额外配置，用户可以完全掌控自己的数据：既可以使用官方的 rendezvous/relay 公共服务器，也可以自建服务器（hbbs/hbbr）。客户端与服务器之间的打洞（TCP hole punching）与中继协商逻辑集中在 src/rendezvous_mediator.rs 中，peer 连接的建立则在 src/client.rs。RustDesk 欢迎社区贡献，参与方式可以参考 docs/CONTRIBUTING.md。

构建前置依赖：Sciter 或 Flutter GUI

Desktop 版本的 GUI 有两种实现：Sciter 或 Flutter。官方构建文档针对的是 Sciter 路线，构建前需要自行下载对应平台的 Sciter 动态库：

平台	动态库文件
Windows	`sciter.dll`
Linux	`libsciter-gtk.so`
MacOS	`libsciter.dylib`

仓库文档提供了各平台 Sciter SDK 动态库的直接下载链接（见 docs/README.md 的 Dependencies 小节），下载后 Linux 版本需要放到构建输出目录 target/debug/（或 target/release/）下，程序运行时按路径加载该库。

另一条 GUI 技术栈是 Flutter，其完整的跨平台工程位于 flutter/ 目录，包含 Android、iOS、macOS、Windows、Linux 的平台壳代码以及 flutter/lib/main.dart 等 Dart 源码；对应 Cargo.toml 中的 flutter feature 会启用 flutter_rust_bridge。

准备 vcpkg 与编解码依赖

原生构建的第二项前置条件是 C++ 依赖管理器 vcpkg。需要安装 vcpkg 并正确设置 VCPKG_ROOT 环境变量，然后按平台安装 RustDesk 使用的四个编解码库：

# 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

这组命令对应的正是仓库根目录的 vcpkg.json 依赖声明，从该文件还能看出当前仓库实际用到的完整依赖面：

视频编码：libvpx（VP8/VP9）、aom（AV1）、libyuv（像素格式转换），均以 host/非 host 成对声明，说明部分工具链（如 ffmpeg 的构建依赖）会在构建主机侧额外编译一份；
音频编码：opus，同样成对声明；
硬编码加速：mfx-dispatch（Intel QSV）在 x86/x64 的 Android、Linux 及非 UWP Windows 上启用；ffmpeg 则按平台携带 amf（AMD）、nvcodec（NVIDIA）、qsv（Intel）feature，仅用于静态构建场景；
Android 专属：cpu-features，且 res/vcpkg-triplets/ 下提供了 arm-neon-android.cmake、arm64-android.cmake、x64-android.cmake、x86-android.cmake 四个自定义 triplet；
版本锁定：vcpkg-configuration 段将默认 registry baseline 固定到具体 commit（见 vcpkg.json），同时通过 overlay-ports 指向仓库自带的 res/vcpkg/（对 aom、ffmpeg、libvpx、libyuv、mfx-dispatch、opus 等端口打了定制补丁，例如 res/vcpkg/ffmpeg/ 中的 CMake 兼容补丁），并通过 overrides 固定 ffnvcodec 与 amd-amf 版本，保证构建可复现。

因此，文档中“vcpkg install libvpx libyuv opus aom”只是最小集；在启用 --features hwcodec、vram 等特性或做 Android 交叉构建时，vcpkg 会依据 manifest 拉取更多依赖。

各 Linux 发行版的系统依赖

构建 RustDesk 的 Linux 版本还需要一系列系统级开发库（GTK3、X11 扩展、ALSA/PulseAudio、汇编器等）。官方文档按发行版给出了完整的安装命令，以下原样保留：

Ubuntu 18（Debian 10）

sudo apt install -y 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

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

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

安装 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

注意这里把 vcpkg 固定到了 2023.04.15 这个 release tag——与 Dockerfile 中 git clone --branch 2023.04.15 的做法一致，目的是让整个依赖树与 CI/容器环境保持同一版本，避免 vcpkg 滚动更新导致二进制不兼容。

libvpx 的 Fedora 修复补丁

在 Fedora 上，vcpkg 构建的 libvpx.a 缺少 -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

该问题的根因是 Fedora 的 GCC 默认对共享目标强制 PIC，而静态库 libvpx.a 若未以 -fPIC 编译，后续链接进动态产物（Rust 的 cdylib）时会报 relocation 错误，因此补丁直接在 Makefile 的 CFLAGS/CXXFLAGS 中注入 -fPIC 后重新 make。

本地构建：从 rustup 到 cargo run

系统依赖与 vcpkg 就绪后，执行文档给出的完整构建序列：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
# 克隆本仓库后进入目录
cd rustdesk
mkdir -p target/debug
wget <文档中的 libsciter-gtk.so 下载链接>
mv libsciter-gtk.so target/debug
VCPKG_ROOT=$HOME/vcpkg cargo run

要点说明：

Cargo.toml 声明 rust-version = "1.75"、包版本 1.4.9，并通过 default-run = "rustdesk" 使裸 cargo run 直接运行 rustdesk 二进制；
构建脚本 build.rs 会编译 C/C++ 平台代码（Windows 的 src/platform/windows.cc、macOS 的 src/platform/macos.mm），并在 Android 目标下读取 VCPKG_ROOT（或 VCPKG_INSTALLED_ROOT）拼接链接搜索路径——这解释了为什么环境变量 VCPKG_ROOT 必须正确指向 vcpkg 根目录；
Cargo.toml 还定义了一系列可选编译特性：hwcodec（硬件编解码）、vram（显存零拷贝）、mediacodec（Android MediaCodec）、drm/drm-wake（Wayland DRM 捕获与唤醒）、screencapturekit（macOS 屏幕捕获）、flutter（Flutter GUI 桥接）等。默认 cargo run 只启用 use_dasp（音频重采样默认实现）等基础特性，属于最小可运行构建；

使用 Docker 构建

如果不想在宿主机上铺设依赖，仓库自带了构建容器方案，镜像定义为 Dockerfile。从该文件可以确认容器的完整环境：

基础镜像 debian:bullseye-slim，通过 apt 安装与 Ubuntu 一节完全对齐的依赖集（gcc/g++、clang、nasm/yasm、libgtk-3-dev、libxcb-* 系列、libasound2-dev、libpulse-dev 等，见 Dockerfile）；
手工编译安装 CMake 3.30.6（Dockerfile），以满足部分 C++ 端口的 CMake 版本下限；
以 2023.04.15 分支克隆 vcpkg 并预装 libvpx libyuv opus aom（Dockerfile），并设置 VCPKG_FORCE_SYSTEM_BINARIES=1 强制使用系统工具链，规避容器内权限问题；
预下载 libsciter-gtk.so 并安装 Rust 工具链（rustup），最终以非 root 用户运行，入口脚本为 entrypoint.sh。

构建步骤：

# 克隆本仓库
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

参数含义与 entrypoint.sh 的对应关系：

-v $PWD:/home/user/rustdesk：把宿主机仓库挂载到容器工作目录，构建产物直接落回宿主机的 target/ 目录；
两个 rustdesk-git-cache / rustdesk-registry-cache 卷缓存 cargo 的 git 与 registry 依赖，首次构建较慢（依赖未缓存），之后显著加速；
PUID/PGID：透传宿主机用户 ID/GID，保证挂载目录内生成的文件属主正确；
入口脚本会先 source cargo 环境（entrypoint.sh），然后解析附加参数：传 --release 时创建 target/release/ 并复制 libsciter-gtk.so 进去（entrypoint.sh）；传 --target <triple> 时会先执行 rustup target add <triple> 支持交叉编译（entrypoint.sh），最终统一执行 VCPKG_ROOT=/vcpkg cargo build --locked $argv（entrypoint.sh），--locked 确保依赖版本与 Cargo.lock 严格一致。

构建完成后，可执行文件按文档说明位于（务必在仓库根目录执行，否则程序可能找不到依赖的动态库）：

# debug 版
target/debug/rustdesk

# release 版（构建时追加 --release）
target/release/rustdesk

文档同时提醒：容器内的 cargo install、cargo run 等子命令目前不受支持，因为它们会作用于容器环境而非宿主机；所有额外构建参数都追加在 docker run 命令末尾即可。

源码文件结构速览

官方文档给出的目录结构与实际仓库一致，此处补充各目录下的实际内容作为导航：

libs/hbb_common：视频编解码封装、配置、TCP/UDP 封装、protobuf 消息、文件传输的文件系统函数等公共库。从 git submodule status 输出看，该目录以 git 子模块形式挂载，构建前需要初始化子模块；
libs/scrap：屏幕捕获库。其 src/ 下按后端拆分：dxgi/（Windows）、quartz/（macOS）、x11/、wayland/、android/ 以及 common/ 中的 aom/vpx/hwcodec/camera 等编解码模块；libs/scrap/Cargo.toml 的 feature（wayland、drm、hwcodec、vram、mediacodec）与主 Cargo.toml 的特性开关一一对应；
libs/enigo：跨平台的鼠标键盘控制库，包含 linux/、macos/、win/ 三套实现与统一的 DSL 接口；
src/ui：Sciter GUI，核心入口为 src/ui/index.html 与配套的 .tis 模板和 .css 样式文件，另有 remote、chatbox、file_transfer 等页面；
src/server：被控端服务集合，可看到 audio_service.rs（音频）、clipboard_service.rs（剪贴板）、input_service.rs（输入注入）、video_service.rs/display_service.rs（视频显示）、video_qos.rs（QoS 限速）、connection.rs（网络连接）以及 terminal_service.rs 等；
src/client.rs：peer 连接的建立与远端会话主逻辑；
src/rendezvous_mediator.rs：与 rustdesk-server（hbbs/hbbr）通信，负责等待远端重定向（TCP 打洞）或回退到中继连接；
src/platform：平台相关代码，mod.rs 之下含 linux.rs、macos.rs、windows.rs、windows/（ACL、服务注册表等 Windows 专属模块）及 macOS 特权安装脚本 privileges_scripts/。

小结

RustDesk 的构建流程围绕三条主线展开：Sciter 动态库（GUI）→ 系统开发库（GTK3/X11/音频/汇编器，按发行版差异安装）→ vcpkg manifest 化的 C++ 编解码栈（libvpx/libyuv/opus/aom，vcpkg 固定 2023.04.15）。本地路线适合快速迭代，VCPKG_ROOT=$HOME/vcpkg cargo run 一步出结果；Docker 路线则把全部依赖固化进 rustdesk-builder 镜像，借助 cargo 卷缓存与 entrypoint.sh 的 --release/--target 参数解析，实现了宿主机零依赖、产物直出 target/ 的可复现构建。两条路线共用同一套 vcpkg.json 依赖声明与 build.rs 构建脚本，特性开关（hwcodec、drm、flutter 等）可按需叠加，从而覆盖了从最小构建到全平台发布构建的完整场景。