scrcpy 在 macOS 上的安装与运行实践：静态构建、包管理器与源码级实现细节

scrcpy 是"显示并控制 Android 设备"的开源工具，本文基于仓库文档 doc/macos.md 系统讲解在 macOS 上获取、安装和运行 scrcpy 的完整路径：官方静态构建产物（含各架构的 SHA-256 校验值）、Homebrew 与 MacPorts 两种包管理器方案、运行前提与基本命令；并结合 release/build_macos.sh、meson_options.txt 及客户端源码中的 __APPLE__ 分支，剖析 macOS 版产物是如何构建出来的、以及客户端针对 macOS 平台做了哪些特殊处理。读完后你将能够独立完成 macOS 下 scrcpy 的安装、校验与运行，并理解官方发布包的内部结构与平台适配原理。

一、从官方静态构建安装（Release 静态包）

doc/macos.md 给出的首选安装方式是下载官方 release 中的静态构建（static build），并按当前 Mac 的 CPU 架构选择对应压缩包：

架构	发布产物	SHA-256
aarch64（Apple Silicon：M 系列芯片）	scrcpy-macos-aarch64-v3.3.4.tar.gz	8fef43520405dd523c74e1530ac68febcc5a405ea89712c874936675da8513dd
x86_64（Intel 芯片）	scrcpy-macos-x86_64-v3.3.4.tar.gz	cf9b3453a33279b6009dfb256b1a84c374bd4c30a71edd74bacab28d72a5d929

从仓库根目录的发布目录选择与本机架构匹配的压缩包，下载后解压即可：

# 以 Apple Silicon 为例
tar -xzf scrcpy-macos-aarch64-v3.3.4.tar.gz
cd scrcpy-macos-aarch64-v3.3.4

原文档特别注明：macOS 的静态构建目前仍处于实验性（experimental）阶段，这是选用时的一个重要前提。建议下载后用 shasum -a 256 或 sha256sum 核对上表中的 SHA-256 值，仓库的发布流程本身就包含校验环节（见 release/generate_checksums.sh 与 release/verify-release.sh）。

发布包里到底有什么？

静态包的内容可以通过仓库的构建脚本完整还原。release/build_macos.sh 的构建流程是：

1. 通过 app/deps/adb_macos.sh 获取 Android platform-tools（当前锁定版本 36.0.0，仅提取其中的 adb 可执行文件）；
2. 以"原生平台 + 静态链接"方式编译全部依赖：app/deps/sdl.sh macos native static、app/deps/dav1d.sh macos native static、app/deps/ffmpeg.sh macos native static、app/deps/libusb.sh macos native static；
3. 使用 Meson 构建 scrcpy 本体，关键参数为 -Dstatic=true、-Dportable=true、--buildtype=release、--strip、-Db_lto=true（这两个开关在 meson_options.txt 中定义：static 表示静态依赖，portable 表示使用与可执行文件同目录下的 scrcpy-server）；
4. 把产物归集到 dist 目录：scrcpy 可执行文件、icon.png、man 手册页 app/scrcpy.1，以及解压进来的 adb。

随后 release/package_client.sh 将 dist 目录与独立构建的 scrcpy-server 一起打包为 scrcpy-macos-<arch>-<版本>.tar.gz。因此解压后的发布目录是自包含的：scrcpy（静态链接了 SDL2、FFmpeg、dav1d、libusb 的可执行文件）、配套的 scrcpy-server（会推送到手机运行）以及 adb——这就是"静态构建实验性"的含义：你甚至不需要单独安装 adb。

二、从包管理器安装

除官方静态包外，doc/macos.md 提供了两条包管理器路径。

2.1 Homebrew

scrcpy 已收录于 Homebrew：

brew install scrcpy

Homebrew 安装的 scrcpy 依赖系统中 PATH 可访问的 adb。若尚未安装，可按文档补齐：

brew install --cask android-platform-tools

2.2 MacPorts

MacPorts 会同时把 adb 一并配好：

sudo port install scrcpy

2.3 手动构建

两种包管理器之外，文档还指向手动构建与安装的方式，对应仓库中的 doc/develop.md（从源码构建，需 Meson/Ninja 等工具链），以及上文第一节的 release/build_macos.sh（官方发布构建脚本）。

三、运行前的设备前提

doc/macos.md 提示运行前需确认设备满足 README.md 中 "Prerequisites" 一节的要求，即：

• Android 设备至少 API 21（Android 5.0）；
• 音频转发（audio forwarding）需要 API 30+（Android 11 及以上），低版本设备上 --record-audio 等音频能力不可用；
• 设备上已开启 USB 调试（USB debugging）；
• 部分机型（尤其是小米）出现 Injecting input events requires the caller ... to have the INJECT_EVENTS permission 报错时，需要额外开启 "USB debugging (Security Settings)" 选项并重启设备，否则键盘/鼠标控制会失败。

这些前提是设备端的，与 macOS 客户端的安装方式无关，无论使用静态包还是包管理器安装的 scrcpy，均须满足。

四、运行 scrcpy

安装完成后，在终端执行：

scrcpy

也可以带参数运行。doc/macos.md 给出的示例是"关闭音频转发并录制到 file.mkv"：

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

命令行参数文档的查阅途径有三处，均随仓库/安装产物提供：

• man scrcpy —— 对应 man 手册页 app/scrcpy.1；
• scrcpy --help —— 由 app/src/cli.c 实现的帮助输出；
• 仓库 README.md 中的说明（"Must-know tips" 部分给出常用建议，例如用 scrcpy -m1024 降低分辨率以提升性能、Alt+f 切换全屏等）。

五、macOS 平台适配：源码级实现细节

scrcpy 客户端是跨平台的 C 程序，macOS 与 Linux/Windows 的差异主要集中在一批 __APPLE__ 条件编译分支中，这些正是官方静态包能在 Mac 上正确运行（或需要实验性标注）的原因。

5.1 SDL 相对鼠标模式的 macOS 规避逻辑

在 app/src/mouse_capture.c 的 sc_mouse_capture_set_active() 中，存在一段 #ifdef __APPLE__ 的专门处理：启用鼠标捕获（relative mouse mode，用于"鼠标移动直接映射为手机端光标"）之前，先读取全局鼠标坐标与窗口位置，若鼠标当前不在 scrcpy 窗口内，就先把指针 warp 回窗口中心，再调用 SDL_SetRelativeMouseMode(true)。注释明确说明这是针对 SDL 在 macOS 上的一个缺陷的 workaround——否则窗口外进入相对模式会导致坐标异常。这段代码解释了为什么 scrcpy 的鼠标捕获行为在 macOS 上被单独照顾。

5.2 持续窗口缩放的 macOS/Windows 规避逻辑

app/src/screen.c 中，#if defined(__APPLE__) || defined(_WIN32) 会定义 CONTINUOUS_RESIZING_WORKAROUND：在这两个平台上拖动窗口边缘缩放时会阻塞 SDL 事件循环，SDL_WINDOWEVENT_RESIZED 事件不会触发，因此 scrcpy 改用一个事件监视器（event_watcher）在事件泵中捕获 SDL_WINDOWEVENT_RESIZED 并手动处理尺寸变化。这保证了在 macOS 上连续拖拽调整窗口大小时，画面能同步重排而不是卡住。

5.3 平台相关的小差异

此外，app/src/sys/unix/file.c 在 __APPLE__ 分支中调整了文件读写实现，app/src/util/net.h 对 _WIN32 || __APPLE__ 定义了平台相关的网络常量——这些属于系统 API 层面的适配，无需用户干预。

5.4 构建层面的 macOS 特性

回到构建侧，release/build_macos.sh 的 -Dstatic=true 与 -Dportable=true 决定了静态包的运行模型：所有第三方依赖（SDL2、FFmpeg、dav1d 解码器、libusb）被静态链接进单一可执行文件，scrcpy-server 则作为独立文件放在同目录、由客户端在连接设备时自动推送——用户不需要任何系统级库，这也解释了为什么官方提示静态构建"仍是实验性的"（跨版本 macOS 的兼容矩阵维护成本较高）。

六、小结

场景	推荐方式	关键命令/产物
不想装任何依赖，且设备为 Apple Silicon	官方静态包 aarch64	scrcpy-macos-aarch64-v3.3.4.tar.gz（SHA-256 见上表）
不想装任何依赖，且设备为 Intel	官方静态包 x86_64	scrcpy-macos-x86_64-v3.3.4.tar.gz
已有 Homebrew 生态	Homebrew	brew install scrcpy（必要时 brew install --cask android-platform-tools）
已有 MacPorts 生态	MacPorts（自动配好 adb）	sudo port install scrcpy
需要定制构建	手动构建	见 doc/develop.md 与 release/build_macos.sh

无论采用哪种安装方式，运行入口都是终端中的 scrcpy（或带参数，如 scrcpy --no-audio --record=file.mkv），参数详情通过 man scrcpy / scrcpy --help 查询。设备端须满足 API 21+、开启 USB 调试（音频转发需 API 30+）。理解 release/build_macos.sh 的构建链与 app/src/mouse_capture.c、app/src/screen.c 中的 __APPLE__ 分支后，你可以清楚地知道 macOS 版 scrcpy 的发布包由何而来、平台差异在哪里被消化，从而更从容地处理安装校验、参数配置与故障排查。