scrcpy 在 Linux 上的安装与运行:官方发行包、包管理器、脚本编译与运行实践

本文基于 scrcpy 仓库的官方文档 doc/linux.md,系统讲解在 Linux 上获取并运行 scrcpy 的三条主要路径——官方静态发行包、发行版包管理器、以及 install_release.sh 一键编译安装——并结合 install_release.sh、meson_options.txt 与 release/build_linux.sh 等仓库文件,剖析各安装方式背后的构建机制与运行原理,帮助你完成从安装、启动到进阶配置的全流程实践。

运行前提:设备与环境要求

在安装之前,需要确认设备与主机环境满足 README 中列出的前置条件:

• Android 设备至少需要 API 21(Android 5.0);
• 音频转发功能要求 API 30(Android 11)及以上,详见 doc/audio.md;
• 必须在设备上开启 USB 调试。

部分设备(尤其是小米)在注入输入事件时可能遇到如下报错:

Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.

出现该错误时,需要在开发者选项中额外开启「USB debugging (Security Settings)」(注意它与「USB debugging」是两个不同选项)才能用键盘鼠标控制设备,且设置后需要重启设备一次。另外,USB 调试并非运行 OTG 模式 的必要条件,OTG 模式可以不依赖 USB 调试直接运行。

安装方式一:官方静态发行包

从官方发布的最新版本(v3.3.4)下载 Linux x86_64 静态构建包 scrcpy-linux-x86_64-v3.3.4.tar.gz 并解压即可使用,官方发布的校验值为:

SHA-256: 0305d98c06178c67e12427bbf340d0d58c9e2a39bf9ffbbf8f54d7ef95a5

解压后得到的产物包含 scrcpy 可执行文件、scrcpy-server 预构建服务端,以及图标与 man 页等配套文件——这一打包结构可以直接从发布脚本 release/build_linux.sh 中得到印证:脚本最后将 scrcpy、icon.png、scrcpy.1 和 adb 工具统一拷贝到 dist/ 目录形成发行包。

注意:官方文档明确标注,scrcpy 的 Linux 静态构建目前仍属实验性质(experimental)。 如果静态包在你的系统上遇到问题,建议改用包管理器或自行编译的方式。

安装方式二:发行版包管理器

scrcpy 已被多个发行版与包管理器收录,文档中给出的对应安装方式为:

发行版/管理器	安装命令	备注
Debian/Ubuntu	apt install scrcpy	官方文档标注为过时版本(obsolete version)
Arch Linux	pacman -S scrcpy
Fedora	dnf copr enable zeno/scrcpy && dnf install scrcpy	依赖 COPR 仓库
Gentoo	emerge scrcpy
Snap	snap install scrcpy	官方文档标注为过时版本(obsolete version)

需要特别留意的是,官方文档特意划掉了 Debian/Ubuntu 的 apt 安装与 Snap 安装两项,并标注为 obsolete version——即这些渠道收录的版本可能明显滞后于当前发布版本。如果版本功能(如音频转发、新参数)不满足需求,应优先考虑脚本编译安装或官方发行包。

安装方式三:install_release.sh 一键编译安装

这是官方推荐的「获取最新发布版本」的简化流程。它的特点是:客户端在本地编译,服务端直接使用官方预构建二进制,兼顾了速度与可更新性。

第一步:安装依赖包

以 Debian/Ubuntu 为例,需要先安装编译所需的依赖:

# for Debian/Ubuntu
sudo apt install ffmpeg libsdl2-2.0-0 adb wget \
                 gcc git pkg-config meson ninja-build libsdl2-dev \
                 libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev \
                 libswresample-dev libusb-1.0-0 libusb-1.0-0-dev

这些依赖恰好对应了 scrcpy 客户端的底层需求:FFmpeg 用于解码视频/音频流,SDL2 提供窗口、输入与音频播放,libusb 支撑 OTG/HID 功能,adb 用于与设备通信。

第二步:克隆仓库并执行安装脚本

git clone https://github.com/Genymobile/scrcpy
cd scrcpy
./install_release.sh

新版本发布时,更新仓库并重新执行即可:

git pull
./install_release.sh

第三步:理解脚本在做什么

阅读 install_release.sh 的源码可以看到整个流程被压缩为 4 个阶段:

#!/usr/bin/env bash
set -e

BUILDDIR=build-auto
PREBUILT_SERVER_URL=https://github.com/Genymobile/scrcpy/releases/download/v3.3.4/scrcpy-server-v3.3.4
PREBUILT_SERVER_SHA256=8588238c9a5a00aa542906b6ec7e6d5541d9ffb9b5d0f6e1bc0e365e2303079e

echo "[scrcpy] Downloading prebuilt server..."
wget "$PREBUILT_SERVER_URL" -O scrcpy-server
echo "[scrcpy] Verifying prebuilt server..."
echo "$PREBUILT_SERVER_SHA256  scrcpy-server" | sha256sum --check

echo "[scrcpy] Building client..."
rm -rf "$BUILDDIR"
meson setup "$BUILDDIR" --buildtype=release --strip -Db_lto=true \
    -Dprebuilt_server=scrcpy-server
cd "$BUILDDIR"
ninja

echo "[scrcpy] Installing (sudo)..."
sudo ninja install

关键点逐个说明:

1. 下载并校验预构建服务端:从官方发布页下载 scrcpy-server-v3.3.4,并用 sha256sum --check 校验完整性(脚本中硬编码了 SHA-256 值)。这正是官方文档所提醒的限制来源——该简化流程只适用于已发布版本,因为它依赖下载预构建的 server 二进制,因此无法用于测试 dev 开发分支。

2. Meson 配置客户端构建:使用 --buildtype=release --strip -Db_lto=true 进行带 LTO 的 release 构建,并通过 -Dprebuilt_server=scrcpy-server 将上一步下载的 server 交给构建系统。这个选项在 meson_options.txt 中有定义:

   option('prebuilt_server', type: 'string', description: 'Path of the prebuilt server')
   

   其余相关选项还包括:portable(安装后从 scrcpy 可执行文件所在目录查找 scrcpy-server,而非系统路径)、static(使用静态依赖)、compile_app/compile_server(分别控制是否构建客户端/服务端)、server_debugger、v4l2 与 usb(控制 V4L2 sink 与 HID/OTG 功能是否启用)。

3. 安装:sudo ninja install 将编译产物安装到系统目录。

卸载

官方文档给出的卸载命令为:

sudo ninja -Cbuild-auto uninstall

即回到脚本创建的 build-auto 构建目录,由 ninja 执行 install 的逆操作。

手动编译:完整构建客户端与服务端

install_release.sh 只是「简化流程」。如果要从源码完整构建(例如构建 dev 分支,或需要静态自包含发行包),仓库提供了两条参考路径:

依赖脚本。 app/deps/ 目录包含一组用于下载并构建各依赖的 shell 脚本,其目录结构约定在 app/deps/README 中说明:*.sh 是下载并构建依赖的脚本,work/sources/ 存放源码包,work/build/ 按「版本/架构」组织构建目录,work/install/ 按架构组织安装目录。其中 app/deps/ffmpeg.sh 展示了依赖构建的典型做法:下载指定版本源码(如 FFmpeg 7.1.1)、校验 SHA-256、以静态、无网络、关闭非必要组件(如 --disable-everything 再按需启用)的方式编译。

发布构建流程。 release/build_linux.sh 展示了官方如何构建 Linux 发行包:依次构建 adb_linux.sh、sdl.sh、dav1d.sh(AV1 解码)、ffmpeg.sh、libusb.sh 五个静态依赖,然后以如下参数配置 meson:

meson setup "$LINUX_BUILD_DIR" \
    --pkg-config-path="$DEPS_INSTALL_DIR/lib/pkgconfig" \
    -Dc_args="-I$DEPS_INSTALL_DIR/include" \
    -Dc_link_args="-L$DEPS_INSTALL_DIR/lib" \
    --buildtype=release \
    --strip \
    -Db_lto=true \
    -Dcompile_server=false \
    -Dportable=true \
    -Dstatic=true

从这套参数可以看出官方 Linux 静态包的本质:依赖全部静态链接(-Dstatic=true),客户端与服务端解耦(-Dcompile_server=false,server 单独预构建),且 scrcpy-server 与 scrcpy 可执行文件放在同一目录(-Dportable=true)——这也解释了为什么官方文档称 Linux 静态构建仍属实验性质:构建链更复杂,维护成本更高。

运行 scrcpy

安装完成后,确保设备满足前文所述前置条件,然后在终端直接运行:

scrcpy

也可以带参数运行。官方文档给出的示例是「禁用音频并录屏到 file.mkv」:

scrcpy --no-audio --record=file.mkv

--no-audio 关闭音频转发(对 API 30 以下的设备这是必选场景),--record 将编码流在客户端侧封装(mux)为 MKV 文件保存。

运行效果如上图所示:scrcpy 在 Linux 桌面上打开一个窗口,实时镜像 Android 设备屏幕,窗口标题显示设备名,并可通过鼠标键盘反向控制设备。

命令行参数文档的三个入口

官方文档指出,命令行参数的完整说明可以从以下途径获取:

• man scrcpy —— 本地 man 页,对应仓库中的 app/scrcpy.1;
• scrcpy --help —— 可执行文件自带帮助;
• 仓库 README 中的说明。

运行背后发生了什么

从 doc/develop.md 描述的架构可以推断出启动流程:客户端(scrcpy 二进制)负责把服务端(scrcpy-server)推送到设备并在设备上启动它,随后双方通过视频、音频、控制三类独立 socket 通信——任何一类都可以禁用,因此实际存在 1~3 条 socket。若视频开启,服务端通过 Android 的 MediaCodec 对屏幕做硬件编码(默认 H.264)并随每个包附加 12 字节帧头发送;若音频开启,则发送 OPUS 流。客户端接收后解码并尽快渲染(除非使用 --video-buffer=delay 等缓冲参数)以最小化延迟。而客户端捕获的键盘、鼠标事件则通过控制 socket 发往服务端,由服务端注入设备——这正是前文提到的「Xiaomi 需要额外开启 Security Settings」的权限来源。

小结

• 追求开箱即用:使用包管理器(Arch、Fedora COPR、Gentoo 等),但注意 Debian/Ubuntu 的 apt 与 Snap 渠道版本已被官方标注为过时;
• 追求最新且省事:使用 ./install_release.sh,本地编译客户端 + 官方预构建服务端,仅限已发布版本;
• 需要静态自包含或开发分支构建:参考 app/deps/ 依赖脚本与 release/build_linux.sh 的完整构建流程;
• 运行前务必核对 README 中的 API 级别与 USB 调试要求,遇到问题先 man scrcpy 与 scrcpy --help 查阅参数。

各安装方式的关键取舍——预构建 server 的版本绑定、meson 选项(prebuilt_server/portable/static)、静态依赖构建链——在 install_release.sh 与 meson_options.txt 中均有直接依据,可进一步深入阅读。