RustDesk 从源码到可执行文件：基于 RustDesk 官方 README 的完整编译构建指南

2026-09-04 16:53:34作者：谭伦延

本文以 RustDesk 仓库的法语版 README（docs/README-FR.md）为主体，系统梳理这款 Rust 编写、可自托管的远程桌面软件的完整构建链路：从依赖安装、vcpkg 媒体库配置、各发行版 Linux 构建步骤、Fedora 上的 libvpx 修补，到 Docker 容器化编译，并结合当前仓库的 Cargo.toml、Dockerfile、entrypoint.sh 与 vcpkg.json 给出源码级的实现佐证。读完本文，你可以独立完成 RustDesk 在 Windows、Linux、macOS 上的原生编译，以及通过 Docker 在宿主机上安全地构建 release 可执行文件。

项目定位与依赖概览

RustDesk 是一个"开箱即用"的远程桌面解决方案：无需任何配置即可直接工作，同时允许使用者完全掌控自己的数据——你可以使用官方的 rendezvous/relay 服务器、自建服务器，或者自行实现 rendezvous/relay 服务端。这一特性直接对应仓库中的网络核心模块 src/rendezvous_mediator.rs，它负责与 RustDesk Server 通信，并等待远端的直连（TCP hole punching）或中继连接。

与通用远程桌面不同，RustDesk 的构建链路有两类关键依赖，这也是整篇文章展开的主线：

GUI 动态库 Sciter：桌面版本使用 Sciter 渲染图形界面（当前仓库的 README.md 同时说明 Flutter 已成为主力 GUI、Sciter 已标记为 deprecated，但官方构建教程仍以 Sciter 版本为主线，因为它更简单、对新手更友好）。Sciter 动态库需要使用者自行下载，并放到编译产物旁边，否则链接与运行都会失败。
vcpkg 管理的 C/C++ 媒体库：libvpx（VP8/VP9 编解码）、libyuv（YUV 色彩空间转换）、opus（音频编码）、aom（AV1 编码）。这四者正是 libs/scrap 截屏编码管线的底层依赖，例如 libs/scrap/src/common/vpx.rs 与 libs/scrap/src/common/aom.rs 通过 FFI 绑定（见 libs/scrap/src/bindings/vpx_ffi.h）调用这些库完成帧编码。

从当前仓库根目录的 vcpkg.json 可以看到完整的依赖声明：它通过 overlay-ports 指向本地补丁目录 res/vcpkg（其中包含 aom、ffmpeg、libvpx、libyuv、mfx-dispatch、opus 各库的 portfile 与补丁），通过 overlay-triplets 指向 res/vcpkg-triplets 中为 Android 各架构定制的 triplet。对于静态构建的 Windows/Linux x86_64 平台，还会额外引入 ffmpeg（含 amf/nvcodec/qsv 硬件编码特性）与 mfx-dispatch。

原始构建步骤（Raw Steps to Build）

官方给出的三步式最小构建流程如下：

准备 Rust 开发环境与 C++ 编译环境；
安装 vcpkg，并正确设置环境变量 VCPKG_ROOT；
执行 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

注意 Windows 使用 x64-windows-static triplet——即以静态库形式链接，避免最终产物对 vcpkg 目录产生运行时依赖；而 Linux/macOS 使用默认 triplet。

结合当前仓库源码可以进一步验证这套构建配置的细节：

Cargo.toml 声明 rust-version = "1.75"，即最低 Rust 工具链要求为 1.75（Docker 镜像内通过 rustup 安装最新工具链）；包版本当前为 1.4.9；
同一文件中的 [features] 定义了多个可选编译开关，如 hwcodec（硬件编解码）、vram（显存直通）、drm（DRM/KMS 捕获）、flutter（启用 flutter_rust_bridge）等，默认 feature 为 use_dasp。需要硬件加速或 DRM 捕获时，可在 cargo run/cargo build 后追加 --features hwcodec 等参数；
[profile.release] 启用了 lto = true、codegen-units = 1、panic = 'abort'、strip = true 与 rpath = true——也就是说 --release 构建默认就会做全量 LTO 与符号剥离，产物更小但编译时间显著更长。

Linux 上的完整构建流程

README 按发行版给出了系统级依赖清单。以下命令逐条继承自原文档，可直接复制执行。

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

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

这些包可以按职责分为四组理解：

工具链：g++/gcc、clang、cmake、make、pkg-config——vcpkg 构建 C 库与 Rust 构建过程都需要；
汇编器：nasm、yasm——libvpx、aom 等汇编优化代码的汇编依赖；
X11/GTK 开发库：libgtk-3-dev、libxcb-*、libxdo-dev、libxfixes-dev——分别支撑 GTK 窗口、scrap 的 X11 捕获后端（libs/scrap/src/x11/）以及 enigo 的键盘鼠标控制；
音频：libasound2-dev/alsa-lib/pulseaudio-libs-devel/pipewire——服务端音频捕获（src/server/audio_service.rs）在 Linux 上依赖 ALSA/PulseAudio。

安装 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 钉在 2023.04.15 这个 tag 上，以保证可重复构建。这与 Dockerfile 第 42–44 行完全一致——镜像中同样以 --branch 2023.04.15 --depth=1 克隆 vcpkg 并执行 vcpkg install libvpx libyuv opus aom，同时设置了 VCPKG_FORCE_SYSTEM_BINARIES=1（复用系统上的 cmake/ninja 等工具，加速构建）。

修复 libvpx（仅 Fedora）

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 上，libvpx 的 ./configure 生成的 Makefile 没有加入 -fPIC（位置无关代码）标志，而后续动态链接静态库时会因此报错。两条 sed 命令在 CFLAGS+=-I 与 CXXFLAGS+=-I 前强制插入 -fPIC，重新 make 出带 PIC 的 libvpx.a 并覆盖到 vcpkg 的 installed/x64-linux/lib/ 安装目录。这是一个典型的"vcpkg 端口构建失败后手工补救"案例：不动 vcpkg 本身，只修补产物。

执行构建

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
cargo run

这条链路的每一步都有仓库内依据：

下载 libsciter-gtk.so 并放入 target/debug/：因为二进制会与该动态库同目录加载，Cargo.toml 中 sciter-rs 依赖（非移动端才引入）负责在运行时加载它；
cargo run 默认构建 debug profile（[profile.dev] 设置了 debug = 1，保留较完整调试信息以加快增量编译）。

此外，若希望跳过 libxdo 的硬依赖（例如 Wayland-only 环境），当前仓库已内置补丁：Cargo.toml 末尾的 [patch.crates-io] 将 libxdo-sys 重定向到本地桩实现 libs/libxdo-sys-stub，使构建可以在未安装 libxdo 的系统上进行。

使用 Docker 构建

Docker 方案把整套构建环境（系统包、CMake、钉版 vcpkg、Sciter 库、Rust 工具链）固化进镜像，宿主机只需要 Docker。

首先克隆仓库并构建镜像：

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

首次编译在依赖缓存就绪前会更慢，之后的构建会明显加快。若需要向编译命令传递额外参数，直接追加在命令末尾即可；例如构建优化的 release 版本就在命令后追加 --release。产物位于宿主机的 target 目录：

target/debug/rustdesk

或 release 版本：

target/release/rustdesk

请务必在 RustDesk 仓库根目录下运行这些命令，否则应用找不到所需资源。同时注意：cargo install、cargo run 等子命令在此方案下不被支持，因为那会在容器内部安装或执行程序，而不是在宿主机上。

对照仓库文件可以精确还原 Docker 方案的工作机制：

Dockerfile：基于 debian:bullseye-slim，安装 g++/gcc/nasm/yasm/GTK/XCB/PulseAudio/GStreamer 等系统包；从源码编译安装 CMake 3.30.6；克隆并 bootstrap 钉版 2023.04.15 的 vcpkg，安装 libvpx/libyuv/opus/aom；创建非 root 用户 user（家目录 /home/user），并把 libsciter-gtk.so 下载到其家目录；最后以 root 身份复制 entrypoint.sh 并设置 ENTRYPOINT；
entrypoint.sh：这是 docker run 传参机制的核心。脚本先 cd $HOME/rustdesk 并 source cargo 环境，然后逐个解析传入的参数：
- 遇到 --release：创建 target/release/，把家目录里的 libsciter-gtk.so 复制进去（若不存在），并置位 release=1；
- 遇到 --target：自动执行 rustup target add <目标三元组>，为交叉编译铺路；
- 其余参数被忽略解析但仍原样保留在 $argv 中；
- 未指定 --release 时，把 Sciter 库复制到 target/debug/；
- 最终以 VCPKG_ROOT=/vcpkg cargo build --locked $argv 收尾——即"容器内只做 cargo build，产物通过 -v $PWD:/home/user/rustdesk 卷落到宿主机"，这正好解释了为什么 --release 等参数要追加在 docker run 命令末尾、以及为什么 run/install 子命令不被支持；
-v rustdesk-git-cache 与 -v rustdesk-registry-cache：分别缓存 ~/.cargo/git 与 ~/.cargo/registry。RustDesk 大量依赖来自 git（Cargo.toml 中 parity-tokio-ipc、magnum-opus、kcp-sys、flutter_rust_bridge、enigo/clipboard 等），这两个命名卷让第二次及以后的构建免去重新拉取 crate 的开销；
-e PUID/-e PGID：把宿主机当前用户的 UID/GID 传入容器，避免容器内 user 生成的 target/ 文件在宿主机上出现属主错乱。

项目结构速览

法语版 README 给出的模块地图如下（已按仓库根目录相对路径规范化，并对照当前仓库实际结构补充说明）：

libs/hbb_common：视频编解码、配置、tcp/udp 封装、protobuf、文件传输的 fs 函数及通用工具函数。注意当前仓库中该目录是一个 git 子模块（见 .gitmodules，指向 https://github.com/rustdesk/hbb_common），克隆时需 git clone --recurse-submodules 或事后 git submodule update --init --recursive；
libs/scrap：截屏。其 src/common/ 下按后端组织：x11.rs、wayland.rs、quartz.rs（macOS）、dxgi.rs（Windows），并配套 vpx.rs/aom.rs/hwcodec.rs/mediacodec.rs/drm_reader.rs 等编解码与捕获实现，还有可独立运行的 libs/scrap/examples/benchmark.rs 等示例；
libs/enigo：跨平台键鼠控制，src/ 下分 linux/、macos/、win/ 三套实现，另附 dsl.rs 等示例；
src/ui：Sciter 图形界面（含 src/ui/index.html、src/ui/cm.html、src/ui/remote.rs 等）。当前仓库主 README 已将其标注为 deprecated，Flutter UI 代码位于 flutter 目录；
src/server：音频/剪贴板/输入/视频服务与网络连接，包括 src/server/video_service.rs、src/server/audio_service.rs、src/server/input_service.rs、src/server/clipboard_service.rs 与 src/server/connection.rs；
src/client.rs：发起对等（peer）连接；
src/rendezvous_mediator.rs：与 RustDesk Server 通信，等待远端直连（TCP hole punching）或中继连接；
src/platform：平台相关代码（windows.rs、linux.rs、macos.rs 等）。

合规使用提醒

原文档末尾附带明确的滥用警告：RustDesk 开发者不认可、不支持任何不道德或非法用途；未授权访问、越权控制或侵犯隐私等滥用行为严格违反使用准则，作者对应用的任何滥用不承担责任。将 RustDesk 用于自托管远程桌面时，请确保连接双方均获得授权。

小结

沿着 docs/README-FR.md 的脉络可以完整走通 RustDesk 的构建：装好系统包与钉版 vcpkg（libvpx libyuv opus aom）→ 处理平台特殊问题（Fedora 的 -fPIC 修补）→ 放置 Sciter 动态库 → cargo run 或 --release 构建；Docker 方案则把以上全部固化到 Dockerfile + entrypoint.sh 中，通过卷挂载与 cargo 缓存卷实现"容器编译、宿主机出产物"。所有关键配置——依赖声明（vcpkg.json）、feature 开关与 release 优化（Cargo.toml）、子模块关系（.gitmodules）——都可以在仓库内直接查证，便于按本文步骤复现或排查构建问题。