RustDesk 构建指南：Linux 系统依赖、vcpkg 编解码器与 Docker 编译流程

本文基于 RustDesk 仓库的官方 README（德语版 docs/README-DE.md）系统整理其桌面端从零编译的完整路径：如何按发行版安装系统依赖、如何用 vcpkg 准备 libvpx/libyuv/opus/aom 编解码库、如何用 Docker 容器隔离构建环境，以及编译产物的目录结构与运行方式。读完后你将能够在本机或 Docker 环境中独立构建出可运行的 RustDesk 二进制文件，并理解其源码各核心模块的分工。

项目概述：自托管的 Rust 远程桌面客户端

RustDesk 是一款用 Rust 编写的远程桌面软件，开箱即用、无需特殊配置，用户完全掌控自己的数据；可以自建 Rendezvous/Relay（会合/中继）服务器实现自托管部署。项目对滥用场景有明确的免责声明：开发者不支持任何非伦理或非法使用（如未授权访问、控制或侵犯隐私），作者对应用的滥用行为不承担责任（见 docs/README-DE.md）。

从 Cargo.toml 可以看到当前仓库的构建基线：

• 包名 rustdesk，版本 1.4.9；
• 最低 Rust 版本 rust-version = "1.75"；
• default-run = "rustdesk"，即 cargo run 默认执行 rustdesk 二进制；
• 除主程序外还定义了 naming（src/naming.rs）和 service（src/service.rs）两个辅助二进制，用于被控端服务安装场景。

构建依赖总览

GUI 渲染层：Sciter 动态库（或 Flutter）

桌面版 GUI 使用 Sciter 或 Flutter 实现，官方编译教程以 Sciter 为准。Sciter 动态库需要开发者自行下载并放到构建产物目录中，各平台对应文件为：

平台	Sciter 动态库
Windows	sciter.dll（x64）
Linux	libsciter-gtk.so（x64）
macOS	libsciter.dylib

Docker 构建流程中也印证了这一点：Dockerfile 在镜像中直接下载 libsciter-gtk.so 到 /home/user/，随后由 entrypoint.sh 拷贝进 target/debug 或 target/release（见下文）。

系统级与 C++ 编解码依赖

构建涉及两类依赖：

1. Rust 工具链与 C++ 构建环境：cargo、g++/clang、cmake、nasm/yasm（汇编工具，编解码库编译需要）、GTK3 与 X11 开发库、gstreamer 等；
2. vcpkg 管理的 C/C++ 第三方库。

vcpkg.json 是项目对 vcpkg 依赖的权威声明，其中与编译教程直接相关的核心四项为 libvpx（VP8/VP9）、libyuv（色彩空间转换）、opus（音频编码）、aom（AV1）。此外该清单还按平台条件引入了 ffmpeg（含 amf/nvcodec/qsv 硬件编解码特性）、mfx-dispatch（Intel 媒体 SDK 分发层）、libjpeg-turbo，以及 Windows ARM64 平台下的 libsodium。清单通过 overlay-ports 指向 res/vcpkg/（内含 aom、ffmpeg、libvpx、libyuv、mfx-dispatch、opus 六个自定义端口及其补丁），通过 overlay-triplets 指向 res/vcpkg-triplets/（提供 arm-neon-android、arm64-android、x64-android、x86-android 四个 Android 三元组），并锁定了一个 builtin registry baseline 以保证依赖版本可复现。

快速编译三步走

README 给出的最精简路径如下（适用于已准备好环境的情况）：

1. 准备 Rust 开发环境（rustup/cargo）和 C++ 构建环境；
2. 安装 vcpkg 项目 对应的本地仓库（下文给出具体步骤），并设置系统环境变量 VCPKG_ROOT；
3. 执行 cargo run 完成编译并启动。

vcpkg 安装命令按平台区分：

# 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

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

这些依赖与 Dockerfile 中基于 Debian bullseye 镜像安装的软件包高度一致（g++/gcc/nasm/yasm/libgtk-3-dev/clang/libxcb-*-dev/libxdo-dev/libasound2-dev/libpulse-dev/libgstreamer* 等），可以认为该 Docker 镜像就是 Ubuntu 依赖清单的容器化版本。

安装 vcpkg 并固定版本

Linux 下按 README 的完整流程安装 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

这里 git checkout 2023.04.15 把 vcpkg 固定到特定发布版本，是为了保证端口构建行为与 vcpkg.json 中锁定的 baseline（9e593bb...）配套可复现。Docker 镜像同样遵循这一约定：Dockerfile 中 git clone --branch 2023.04.15 --depth=1 并执行 vcpkg install libvpx libyuv opus aom，且镜像内设置了环境变量 VCPKG_FORCE_SYSTEM_BINARIES=1，让 vcpkg 使用系统自带的编译器与构建工具而非内置版本。

Fedora 的 libvpx 修复（-fPIC 补丁）

在 Fedora 上通过 vcpkg 构建 libvpx 静态库时可能缺少位置无关代码标志，README 给出如下手工修复步骤：

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 的构建 Makefile 中为 CFLAGS/CXXFLAGS 统一注入 -fPIC，重新编译后把生成的 libvpx.a 覆盖到 vcpkg 的 x64-linux 安装目录，使后续 cargo build 链接时可用。

本机编译并运行

完整命令序列：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
git clone --recurse-submodules 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

要点说明：

• --recurse-submodules 必不可少：libs/hbb_common 是一个 git 子模块（见 .gitmodules），指向独立的 rustdesk/hbb_common 仓库，缺失将导致 hbb_common = { path = "libs/hbb_common" } 这一依赖解析失败；
• Sciter 的 libsciter-gtk.so 必须放在 target/debug/（或 target/release/）下，运行时二进制与资源按工作目录定位；
• VCPKG_ROOT 指向 vcpkg 安装目录，供 build.rs 定位编解码库；
• 入口行为可从 src/main.rs 得到印证：非移动平台的 main() 先调用 core_main::core_main() 解析参数并初始化核心，再调用 ui::start(args) 启动 Sciter GUI；而 android/ios 或开启 flutter 特征时走 Flutter 入口，只做会合服务器与 NAT 类型测试。

可选编译特征（Cargo features）

Cargo.toml 中还定义了一系列影响最终二进制能力的编译开关，按需追加到 cargo build 即可：

特征	作用
flutter	编译 Flutter（移动/新界面）版本
hwcodec	启用 scrap 的硬件编解码路径
vram	启用 scrap 的显存直接读取
mediacodec	启用 Android MediaCodec 采集
drm / drm-wake	启用 DRM 采集；drm-wake 额外编译"唤醒闲置显示输出"的注入逻辑
inline	Sciter 内联模式（Windows 下跳过 DPI 感知设置）
linux-pkg-config	通过 pkg-config 定位 opus 等库
unix-file-copy-paste	启用 X11 文件拖放复制
screencapturekit	macOS ScreenCaptureKit 采集

例如编译一个启用硬件编解码的 Release 版本：cargo build --release --features hwcodec。

Docker 编译：容器化构建环境

对希望避免污染本机环境的开发者，README 提供了完整的 Docker 流程。

构建镜像

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

该镜像基于 debian:bullseye-slim，一次性装好系统依赖、CMake 3.30.6、固定版本的 vcpkg 及其四件套编解码库、Rust 工具链与 Sciter 动态库（见 Dockerfile）。

执行编译

每次需要编译时执行：

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

• 当前仓库目录挂载到容器内 /home/user/rustdesk，编译产物直接落回宿主机；
• 两个命名卷 rustdesk-git-cache、rustdesk-registry-cache 分别缓存 cargo 的 git 依赖与 crates 依赖，首次编译较慢，之后显著提速；
• PUID/PGID 传入宿主机用户/组 ID，保证产物文件权限归属正确；
• 需要在 cargo build 后追加的参数可直接放在命令末尾，例如追加 --release 编译优化版本。

容器内入口脚本的行为

entrypoint.sh 是容器真正执行编译的地方，其行为值得了解：

1. 进入 $HOME/rustdesk 并 source ~/.cargo/env 加载 Rust 环境；
2. 扫描参数：遇到 --release 时设置 release=1；遇到 --target 时自动 rustup target add 对应目标平台；其余参数原样透传；
3. 若为 debug 构建则 mkdir -p target/debug 并把 libsciter-gtk.so 拷入（release 构建同理拷入 target/release/），保证 Sciter 库就位；
4. 最终执行 VCPKG_ROOT=/vcpkg cargo build --locked $argv——注意容器内是 cargo build 而非 cargo run。

因此 README 特别提醒：cargo install、cargo run 等其他 Cargo 子命令暂不支持，因为它们会在容器内部启动或安装程序，而不是作用在你的宿主机上。

运行产物

编译完成后在宿主机仓库根目录下运行：

# debug 版本
target/debug/rustdesk

# release 版本
target/release/rustdesk

务必在仓库根目录执行，否则程序可能无法定位所需的资源文件（Sciter 页面、图标等）。

源码目录结构

README 对仓库目录结构的说明是快速建立全局认知的好切入点，结合仓库实际内容核对如下：

• libs/hbb_common：视频编解码封装、配置读写、TCP/UDP 封装、协议缓冲、文件传输所需的 fs 功能等公共基础库。注意它是 git 子模块（独立仓库），本地克隆时必须 --recurse-submodules；
• libs/scrap：跨平台屏幕采集与编解码，内部按平台拆分为 common/（codec、convert、wayland、x11、linux 等）、quartz/（macOS）、dxgi/（Windows）、wayland/、x11/ 等模块，并提供 screenshot、record-screen 等示例；
• libs/enigo：平台相关的鼠标/键盘输入模拟，含 linux/、macos/、win/ 实现与 DSL 示例；
• libs/clipboard：Windows/Linux/macOS 的文件复制粘贴实现，含 Windows wf_cliprdr.c 与跨平台 context_send.rs 等；
• src/ui：Sciter GUI 页面与脚本（index.tis、remote.tis、file_transfer.tis 等对应的 .tis/.html/.css 文件）；
• src/server：被控端服务，包括 video_service.rs、audio_service.rs、input_service.rs、clipboard_service.rs、display_service.rs 及连接处理；
• src/client.rs：发起 Peer 连接（主控端）的入口逻辑，辅以 src/client/ 下的 io_loop.rs、screenshot.rs、file_trait.rs；
• src/rendezvous_mediator.rs：与 rustdesk-server（会合服务器）通信，等待直连（TCP 打洞）成功或转入中继转发；
• src/platform：平台特定代码（linux.rs、macos.rs、windows.rs、windows.cc 等）；
• flutter：移动端与新界面使用的 Flutter 客户端代码（lib/ 下按 mobile/、desktop/、web/ 等组织）。

此外 res/vcpkg/ 与 res/vcpkg-triplets/ 存放 vcpkg 自定义端口补丁与 Android 三元组，res/ 下还有 DEBIAN/RPM/MSI/Flatpak 等打包脚本，供构建出安装包。

小结

编译 RustDesk 的关键在于三条主线：按发行版装好系统依赖（GTK3/X11/gstreamer 等）、用固定版本的 vcpkg 备好 libvpx/libyuv/opus/aom 编解码库并把 VCPKG_ROOT 指向它、把 Sciter 动态库放进 target/debug（或 target/release）。环境准备成本高但可容器化——docker build + docker run 配合挂载卷与 cargo 缓存卷即可在宿主机上持续、快速地产出可运行二进制。理解 entrypoint.sh 的参数处理与 cargo build --locked 行为，能帮你正确扩展 --release、--target 等构建选项。