RustDesk 编译实战指南：vcpkg 依赖安装、Docker 容器化构建与源码结构解析

本篇指南围绕 RustDesk 仓库的官方构建文档（docs/README-PTBR.md，该文档是仓库 README 的葡语版本，构建流程与其他语言版 README 一致）展开，覆盖从零编译 RustDesk 的完整流程：各 Linux 发行版的系统依赖安装、vcpkg 编解码库准备、Sciter/Flutter 双 GUI 体系说明、Docker 容器化构建，以及仓库源码结构。读完本文，你能够独立在裸机或容器中完成 RustDesk 的可执行文件构建，并理解 VCPKG_ROOT 等构建变量在源码构建脚本中是如何被消费的。

适用范围与前置条件

按构建文档说明，桌面版使用 Flutter 或 Sciter（已标记为 discontinued/不推荐）作为图形界面。文档中给出的快速上手路径以 Sciter 为准，因为它更简单、更易起步；Flutter 版本的编译方式参见仓库 CI 配置。

准备开发环境需要做三件事：

1. 准备好 Rust 开发环境（rustup）和 C++ 编译工具链（gcc/g++、clang 等）；
2. 安装 vcpkg（以源码仓库形式安装即可）并正确设置环境变量 VCPKG_ROOT；
3. 按平台安装编解码依赖：
   • 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
4. Sciter 版还需要自行下载对应平台的 Sciter 动态库：Windows 为 sciter.dll、Linux 为 libsciter-gtk.so、macOS 为 libsciter.dylib（来自 c-smile/sciter-sdk 发布资源）。

一个值得注意的版本前提：当前仓库 Cargo.toml 声明的 rust-version 为 1.75，包版本为 1.4.9，即建议至少使用 Rust 1.75 及以上工具链来编译本仓库代码。

vcpkg 依赖声明与源码的对应关系

文档只要求安装 libvpx libyuv opus aom 四个库，但仓库根目录的 vcpkg.json 实际上声明了更完整的依赖集合，其中包含：

• libvpx、libyuv、opus、aom（均声明 host: true 与 host: false 两份，分别用于构建宿主与目标平台）；
• libjpeg-turbo（静态截图/图像编码路径使用）；
• mfx-dispatch（Intel QSV 硬件编解码，限定 windows | (x86/x64 linux) 平台）；
• ffmpeg（限定静态构建平台，并在 Windows/Linux 下启用 amf、nvcodec、qsv 等硬件编码 feature）；
• 通过 overlay-ports 指向仓库内 res/vcpkg 目录下的定制端口（仓库自带 aom/ffmpeg/libvpx/libyuv/opus/mfx-dispatch 的补丁与 portfile），并通过 overlay-triplets 指向 res/vcpkg-triplets，baseline 则把依赖版本固定在一个提交上，保证可复现构建。

VCPKG_ROOT 在哪里被消费？ 这正是文档反复强调设置该变量的原因。从源码结构看：

• 屏幕捕获库的构建脚本 libs/scrap/build.rs 中的 find_package() 函数定义了三级查找策略：若处于 Linux 且启用了 linux-pkg-config feature，优先走 pkg-config（可用 NO_PKG_CONFIG_<lib>=1 关闭）；否则读取 VCPKG_ROOT 环境变量，从 $VCPKG_ROOT/installed/<triplet>/lib 输出 cargo:rustc-link-search 与静态库链接指令，并用 bindgen 基于 vcpkg 头文件生成 FFI 绑定；两者都失败时，仅 macOS aarch64 允许回退 Homebrew（源码中直接 panic!("Couldn't find VCPKG_ROOT, also can't fallback to homebrew because it's only for macos aarch64.")）。
• 顶层 build.rs 在为 Android 目标编译时，同样依赖 VCPKG_ROOT（或 VCPKG_INSTALLED_ROOT）来定位交叉编译产物目录并链接 NDK 兼容库。

因此“正确设置 VCPKG_ROOT”不是可选建议，而是构建脚本解析编解码库链接路径的硬依赖。

安装系统级依赖（按发行版）

以下是构建文档给出的各发行版依赖安装命令，与 Dockerfile 中实际安装的系统包高度一致（gcc/g++、git、nasm、yasm、libgtk-3-dev、clang、libxcb-*-dev、libxdo-dev、libxfixes-dev、libasound2-dev、libpulse-dev、cmake、make、libgstreamer1.0-dev 等），可互为印证。

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

这些依赖分别服务于：屏幕捕获（xcb/Xfixes）、输入模拟（libxdo）、音频采集（ALSA/PulseAudio）、GTK 窗口（Sciter 依赖 libgtk-3）、GStreamer 管线（macOS 之外的音频重定向等场景）。

安装 vcpkg

构建文档固定了 vcpkg 的 checkout 版本（与 Dockerfile 中 --branch 2023.04.15 --depth=1 保持一致）：

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.json 中 baseline 固定的提交与仓库内 res/vcpkg overlay 端口（例如 aom 补丁、libvpx 的 UWP 支持补丁）是按同一时期的 vcpkg 行为编写的，随意升级 vcpkg 可能破坏 overlay 端口的构建。

修复 Fedora 上 libvpx 的 -fPIC 问题

在 Fedora 上编译时，vcpkg 为 libvpx 生成的 Makefile 默认不带 -fPIC，会导致静态库无法链接进最终二进制。构建文档给出如下修复流程（进入 vcpkg 构建目录，手动重编并拷回已安装目录）：

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

该问题的本质与 libs/scrap/build.rs 的链接方式直接相关：Rust 侧以 cargo:rustc-link-lib=static=... 方式链接 vcpkg 产出的静态库，静态库中的目标文件必须开启位置无关代码（PIC）才能被链入动态链接的最终可执行文件；Fedora 的工具链对缺省 PIC 行为的处理与其他发行版不同，因而出现该差异。

编译 RustDesk（Sciter GUI）

完整的裸机编译流程（构建文档“Compilar”一节）：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
git clone --recurse-submodules https://gitcode.com/GitHub_Trending/ru/rustdesk
cd rustdesk
mkdir -p target/debug
# 下载 Linux x64 版 Sciter 动态库（Windows/macOS 请按平台替换文件名）
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 不可省略，仓库依赖 git 子模块；
• libsciter-gtk.so 必须放在可执行文件同目录（target/debug），运行时按相对路径加载——这一点在 Docker 构建入口脚本 entrypoint.sh 中被自动化处理（test -f target/debug/libsciter-gtk.so || cp ...）；
• 需要 release 优化版本时，在命令后追加 --release，产物位于 target/release/rustdesk。

从 Cargo.toml 的 features 定义可以看到更多可定制的构建维度，例如 flutter（启用 Flutter GUI 的 flutter_rust_bridge 依赖）、hwcodec（硬件编解码，透传 scrap/hwcodec）、drm/drm-wake（DRM 屏幕捕获及其“显示唤醒”子开关）、linux-pkg-config（Linux 下改用 pkg-config 而非 vcpkg 查找依赖）等。release profile 启用了 lto、codegen-units = 1、panic = 'abort' 与 strip，即正式构建产物经过体积与性能优化。

使用 Docker 编译

Docker 方式把上述全部环境（bullseye 基础镜像 + 系统依赖 + vcpkg 2023.04.15 + Sciter 库 + rustup）封装进构建容器，宿主机只需保留 Docker。

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

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

Dockerfile 的关键步骤：基于 debian:bullseye-slim 安装与上文 Ubuntu 段落相同的系统依赖，从 CMake 3.30.6 源码安装 CMake，克隆 vcpkg 的 2023.04.15 分支并 install libvpx libyuv opus aom（设置 VCPKG_FORCE_SYSTEM_BINARIES=1），下载 libsciter-gtk.so，安装 rustup，并以非特权用户运行。

之后每次编译执行：

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

• 首次编译会拉取并缓存所有依赖，耗时较长；两个命名卷 rustdesk-git-cache / rustdesk-registry-cache 让后续构建复用 crate 缓存，显著提速；
• 需要附加 cargo 参数时直接追加在命令末尾，例如 --release 编译优化版本；
• 最终产物仍生成在宿主机的 target 目录：debug 版运行 target/debug/rustdesk，release 版运行 target/release/rustdesk。

入口脚本 entrypoint.sh 解释了参数是如何被处理的：它逐参扫描 --release（置位 release 并把 Sciter 库拷入 target/release）与 --target <triple>（调用 rustup target add 注册交叉编译目标），其余参数原样透传，最终统一执行：

VCPKG_ROOT=/vcpkg cargo build --locked $argv

这带来两个实用约束，构建文档也特别提示：

1. 必须从仓库根目录运行可执行文件，否则应用可能找不到所需资源；
2. 该容器化方法不支持 cargo install、cargo run 等子命令语义——entrypoint 固定调用 cargo build，即只把程序“构建”出来放到宿主机的 target 目录，而非在容器内安装或运行。

源码结构

构建文档最后给出了仓库核心目录的职责划分，结合 Cargo.toml 中 workspace members 的定义（libs/scrap、libs/hbb_common、libs/enigo、libs/clipboard、libs/virtual_display、libs/portable、libs/remote_printer）可以更清楚地理解模块边界：

• libs/hbb_common：视频编解码封装、配置、TCP/UDP 网络封装层、protobuf、文件传输用的文件系统函数及其他通用工具；
• libs/scrap：屏幕捕获。其内部按平台拆分（src/common/ 下有 x11、wayland、quartz、dxgi、mediacodec、drm 等捕获后端，src/bindings/ 存放 aom/vpx/yuv 的 FFI 头文件，由 libs/scrap/build.rs 用 bindgen 生成 Rust 绑定）；
• libs/enigo：各平台键盘/鼠标控制（linux/macos/win 三套实现 + 统一 DSL 接口）；
• libs/clipboard：Windows、Linux、macOS 的文件与文本剪贴板实现（含 Windows 的 wf_cliprdr.c CliprDr 协议）；
• src/ui：旧版 Sciter 界面代码（tis/html/css，文档已注明该方向不推荐，新版 GUI 在 flutter 目录）；
• src/server：音频、剪贴板、输入、视频等服务以及网络连接处理（audio_service.rs、input_service.rs、video_service.rs、connection.rs 等）；
• src/client.rs：发起直接连接（peer connection）；
• src/rendezvous_mediator.rs：与自建 rendezvous/relay 服务器通信，等待直接连接（TCP 打洞）或中继连接；
• src/platform：各平台特化代码（Linux 权限提升、macOS 特权脚本、Windows 服务与安装器等）；
• flutter：桌面与移动端的 Flutter 客户端代码（Dart 层 + 各平台壳工程）。

另外，Cargo.toml 还通过 [patch.crates-io] 将 libxdo-sys 替换为仓库内的 libs/libxdo-sys-stub，使系统在未安装 libxdo（例如纯 Wayland 环境）时也能完成构建与运行——这与上文 Arch 段落依赖列表中出现 xdotool 但 Wayland 用户可缺省的场景相呼应。

构建排障小结

综合构建文档与源码，常见问题可归纳为：

现象	可能原因与处理
构建脚本 panic 提示找不到 VCPKG_ROOT	未设置或 shell 未 export；设置 VCPKG_ROOT 指向 vcpkg 根目录后重试（见 libs/scrap/build.rs）
Fedora 上 libvpx 链接报 undefined symbol / 无法生成最终二进制	静态库缺 -fPIC，按上文 sed 修复流程重编 libvpx.a 并拷回 installed/x64-linux/lib
cargo build 报链接错误指向 aom/libvpx/opus	检查 vcpkg install 的 triplet 是否与 VCPKG_ROOT/installed 下实际产物一致；Docker 方式可整体规避
运行 target/debug/rustdesk 提示缺少 Sciter 库	将 libsciter-gtk.so 放到可执行文件同目录，并从仓库根目录启动
Docker 中 cargo run/cargo install 不生效	entrypoint 只执行 cargo build，参数透传规则见 entrypoint.sh

按以上步骤，你可以在 Ubuntu、openSUSE、Fedora、Arch 等主流发行版（或直接用 Docker）上完成 RustDesk 的完整构建，并通过 --release 获得经过 LTO 优化的发行级二进制。