从零构建Scrcpy Android Server端Meson与Gradle深度协作指南在Android投屏工具Scrcpy的生态中大多数用户都习惯于直接使用预编译的Server端APK。但当你需要修改投屏协议、优化视频编码参数或添加自定义功能时从源码完整编译Server端就成为必备技能。本文将揭示Scrcpy构建系统中Meson与Gradle的精妙协作机制带你突破预编译限制掌握从源码到产出的完整工具链。1. 编译环境深度配置1.1 工具链版本锁定Scrcpy对构建工具版本有严格要求版本不匹配会导致各种隐性问题。推荐使用以下组合# Android SDK sdkmanager platforms;android-29 build-tools;30.0.3 # NDK (Side by side模式) sdkmanager ndk;21.4.7075529 --install # Meson pip install meson0.61.5 # Ninja brew install ninja # macOS sudo apt install ninja-build # Ubuntu关键组件版本对照表组件最低版本推荐版本版本检测命令Android SDKAPI 28API 29sdkmanager --listNDK21.021.4.7075529ndk-build --versionMeson0.58.00.61.5meson --versionGradle6.1.17.0.2gradle --version提示建议在项目根目录创建.tool-versions文件使用asdf等版本管理工具锁定环境android-sdk 29.0.3 ndk 21.4.7075529 meson 0.61.51.2 环境变量关键配置在~/.bashrc或~/.zshrc中添加export ANDROID_HOME$HOME/Android/Sdk export NDK_HOME$ANDROID_HOME/ndk/21.4.7075529 export PATH$NDK_HOME:$ANDROID_HOME/platform-tools:$PATH验证环境有效性# 检查adb连接 adb devices # 验证NDK ndk-build --version # 确认Meson meson setup --help | grep cross-file2. 构建系统解密Meson与Gradle的协作2.1 构建流程全景图Scrcpy的构建过程呈现典型的双阶段特征Meson主导阶段解析根目录meson.build检查prebuilt_server选项调用build-wrapper.shGradle构建阶段执行server/build.gradle生成APK文件通过wrapper脚本重命名产物graph TD A[Meson主构建] --|prebuilt_server| B[调用build-wrapper.sh] B -- C[执行gradlew assemble] C -- D[生成server-debug.apk] D -- E[重命名为scrcpy-server]2.2 关键构建文件解析server/meson.build核心逻辑prebuilt_server get_option(prebuilt_server) if prebuilt_server # 源码编译路径 custom_target(scrcpy-server, command: [ find_program(./scripts/build-wrapper.sh), meson.current_source_dir(), OUTPUT, get_option(buildtype) ], output: scrcpy-server, install_dir: share/scrcpy) else # 预编译文件路径 custom_target(scrcpy-server-prebuilt, input: prebuilt_server, command: [cp, INPUT, OUTPUT], output: scrcpy-server, install_dir: share/scrcpy) endifbuild-wrapper.sh的智能处理#!/bin/bash PROJECT_ROOT$1 OUTPUT$2 BUILDTYPE$3 GRADLE_CMD./gradlew [ -f ../gradlew ] GRADLE_CMD../gradlew if [[ $BUILDTYPE debug ]]; then $GRADLE_CMD -p $PROJECT_ROOT assembleDebug cp $PROJECT_ROOT/build/outputs/apk/debug/server-debug.apk $OUTPUT else $GRADLE_CMD -p $PROJECT_ROOT assembleRelease cp $PROJECT_ROOT/build/outputs/apk/release/server-release-unsigned.apk $OUTPUT fi3. 实战禁用预编译的全流程3.1 修改install_release.sh原始脚本会下载预编译Server我们需要移除这部分逻辑#!/usr/bin/env bash set -e BUILDDIRbuild-auto - PREBUILT_SERVER_URLhttps://github.com/Genymobile/scrcpy/releases/download/v1.24/scrcpy-server-v1.24 - PREBUILT_SERVER_SHA256ae74a81ea79c0dc7250e586627c278c0a9a8c5de46c9fb5c38c167fb1a36f056 - 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 $BUILDDIR --buildtyperelease --strip -Db_ltotrue \ - -Dprebuilt_serverscrcpy-server -Dprebuilt_server cd $BUILDDIR ninja echo [scrcpy] Installing (sudo)... sudo ninja install3.2 处理常见编译错误错误1NDK路径未找到FAILURE: Build failed with an exception. * What went wrong: A problem occurred configuring project :server. NDK not configured.解决方案# 在server/local.properties中添加 ndk.dir/path/to/ndk sdk.dir/path/to/sdk错误2Java版本不兼容Unsupported Java. Your build is currently configured to use Java 17...解决方法# 在server/gradle.properties中设置 android.jdkVersion11错误3Meson版本冲突Project specifies meson_version: 0.48 but found 0.47.升级Mesonpip install --upgrade meson4. 高级定制修改Server端功能4.1 修改视频编码参数在server/src/main/java/com/genymobile/scrcpy/ScreenEncoder.java中// 调整关键帧间隔 private static final int KEY_FRAME_RATE 5; // 原值10 // 修改码率控制 mediaFormat.setInteger(MediaFormat.KEY_BIT_RATE, 8_000_000); // 原值4_000_0004.2 添加自定义控制协议在server/src/main/java/com/genymobile/scrcpy/ControlMessage.java中添加新消息类型public static final int TYPE_CUSTOM_COMMAND 0x20;在Client端同步修改对应枚举// app/src/control_msg.h enum control_msg_type { ... CONTROL_MSG_TYPE_CUSTOM_COMMAND 0x20, };4.3 构建产物验证编译完成后验证产物信息# 检查APK基本信息 aapt dump badging build/server/outputs/apk/release/server-release-unsigned.apk # 提取so文件验证 unzip -l build/server/outputs/apk/release/server-release-unsigned.apk | grep .so # 与预编译版本对比 diff (unzip -v1 prebuilt/scrcpy-server) (unzip -v1 build/server/outputs/apk/release/server-release-unsigned.apk)5. 持续集成方案5.1 GitHub Actions配置示例name: Android Server Build on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up JDK 11 uses: actions/setup-javav3 with: java-version: 11 distribution: temurin - name: Install Android SDK uses: android-actions/setup-androidv2 - name: Install Build Tools run: | sdkmanager platforms;android-29 build-tools;30.0.3 sdkmanager ndk;21.4.7075529 - name: Build Server run: | cd server echo ndk.dir$ANDROID_HOME/ndk/21.4.7075529 local.properties ./gradlew assembleRelease - name: Archive Artifacts uses: actions/upload-artifactv3 with: name: scrcpy-server path: server/build/outputs/apk/release/server-release-unsigned.apk5.2 本地Docker构建环境FROM ubuntu:20.04 RUN apt-get update \ DEBIAN_FRONTENDnoninteractive apt-get install -y \ git wget unzip python3-pip ninja-build \ android-sdk android-ndk RUN pip3 install meson0.61.5 ENV ANDROID_HOME /usr/lib/android-sdk ENV NDK_HOME /usr/lib/android-ndk ENV PATH $ANDROID_HOME/cmdline-tools/latest/bin:$NDK_HOME:$PATH WORKDIR /scrcpy COPY . . CMD [bash, -c, meson build --buildtyperelease -Dprebuilt_server ninja -C build]构建命令docker build -t scrcpy-builder . docker run -v $(pwd)/output:/scrcpy/build scrcpy-builder6. 性能优化技巧6.1 加速增量编译在server/gradle.properties中添加org.gradle.paralleltrue org.gradle.cachingtrue org.gradle.daemontrue6.2 选择性依赖更新# 仅更新指定模块 ./gradlew :server:dependencies --update-dependency com.android.tools.build:gradle6.3 构建缓存配置# 设置Gradle缓存目录 export GRADLE_USER_HOME$HOME/.gradle-scrcpy # 清理缓存 ./gradlew cleanBuildCache7. 疑难问题解决方案7.1 符号表缺失问题当需要调试Native代码时需要保留调试符号# server/build.gradle android { buildTypes { release { - minifyEnabled true minifyEnabled false shrinkResources false ndk { debugSymbolLevel FULL } } } }7.2 多ABI支持处理默认Scrcpy只编译armeabi-v7a如需支持其他架构// server/build.gradle android { defaultConfig { ndk { abiFilters armeabi-v7a, arm64-v8a, x86, x86_64 } } }对应的Meson配置调整# 在交叉编译文件中指定ABI [properties] android_abi arm64-v8a7.3 版本号管理保持Client和Server版本同步# 根目录meson.build project(scrcpy, c, version: run_command( python3, -c, import re; print(re.search(rversionName\s\(.?)\, open(server/build.gradle).read()).group(1)), check: true ).stdout().strip(), ... )8. 安全加固建议8.1 签名配置创建签名密钥keytool -genkeypair -v \ -keystore scrcpy.jks \ -keyalg RSA -keysize 4096 \ -validity 10000 \ -alias scrcpy配置签名信息// server/build.gradle android { signingConfigs { release { storeFile file(../scrcpy.jks) storePassword System.getenv(STORE_PASSWORD) keyAlias scrcpy keyPassword System.getenv(KEY_PASSWORD) } } buildTypes { release { signingConfig signingConfigs.release } } }8.2 资源混淆// server/build.gradle buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile(proguard-android.txt), proguard-rules.pro } }在proguard-rules.pro中添加-keep class com.genymobile.scrcpy.** { *; }9. 扩展阅读9.1 关键源码文件文件路径核心功能server/src/main/scrcpy-server.cNative入口点server/src/main/java/.../Server.javaAndroid服务主逻辑app/src/video/decoder.c客户端视频解码实现app/src/control_msg.c控制协议序列化/反序列化9.2 调试技巧日志过滤adb logcat -s scrcpy性能分析# 采样CPU使用率 adb shell am profile start com.genymobile.scrcpy /sdcard/scrcpy.prof # 停止采样后拉取文件 adb pull /sdcard/scrcpy.prof内存分析adb shell dumpsys meminfo com.genymobile.scrcpy10. 结语构建系统的设计哲学Scrcpy的构建系统展现了现代跨平台项目的典型设计思路用Meson作为顶层构建协调器针对不同平台采用原生构建工具如Android的Gradle。这种架构既保持了跨平台的一致性又充分发挥了各平台工具链的优势。
告别预编译：手把手教你从源码编译Scrcpy的Android Server端（含Meson配置详解）
发布时间：2026/5/20 14:12:33
从零构建Scrcpy Android Server端Meson与Gradle深度协作指南在Android投屏工具Scrcpy的生态中大多数用户都习惯于直接使用预编译的Server端APK。但当你需要修改投屏协议、优化视频编码参数或添加自定义功能时从源码完整编译Server端就成为必备技能。本文将揭示Scrcpy构建系统中Meson与Gradle的精妙协作机制带你突破预编译限制掌握从源码到产出的完整工具链。1. 编译环境深度配置1.1 工具链版本锁定Scrcpy对构建工具版本有严格要求版本不匹配会导致各种隐性问题。推荐使用以下组合# Android SDK sdkmanager platforms;android-29 build-tools;30.0.3 # NDK (Side by side模式) sdkmanager ndk;21.4.7075529 --install # Meson pip install meson0.61.5 # Ninja brew install ninja # macOS sudo apt install ninja-build # Ubuntu关键组件版本对照表组件最低版本推荐版本版本检测命令Android SDKAPI 28API 29sdkmanager --listNDK21.021.4.7075529ndk-build --versionMeson0.58.00.61.5meson --versionGradle6.1.17.0.2gradle --version提示建议在项目根目录创建.tool-versions文件使用asdf等版本管理工具锁定环境android-sdk 29.0.3 ndk 21.4.7075529 meson 0.61.51.2 环境变量关键配置在~/.bashrc或~/.zshrc中添加export ANDROID_HOME$HOME/Android/Sdk export NDK_HOME$ANDROID_HOME/ndk/21.4.7075529 export PATH$NDK_HOME:$ANDROID_HOME/platform-tools:$PATH验证环境有效性# 检查adb连接 adb devices # 验证NDK ndk-build --version # 确认Meson meson setup --help | grep cross-file2. 构建系统解密Meson与Gradle的协作2.1 构建流程全景图Scrcpy的构建过程呈现典型的双阶段特征Meson主导阶段解析根目录meson.build检查prebuilt_server选项调用build-wrapper.shGradle构建阶段执行server/build.gradle生成APK文件通过wrapper脚本重命名产物graph TD A[Meson主构建] --|prebuilt_server| B[调用build-wrapper.sh] B -- C[执行gradlew assemble] C -- D[生成server-debug.apk] D -- E[重命名为scrcpy-server]2.2 关键构建文件解析server/meson.build核心逻辑prebuilt_server get_option(prebuilt_server) if prebuilt_server # 源码编译路径 custom_target(scrcpy-server, command: [ find_program(./scripts/build-wrapper.sh), meson.current_source_dir(), OUTPUT, get_option(buildtype) ], output: scrcpy-server, install_dir: share/scrcpy) else # 预编译文件路径 custom_target(scrcpy-server-prebuilt, input: prebuilt_server, command: [cp, INPUT, OUTPUT], output: scrcpy-server, install_dir: share/scrcpy) endifbuild-wrapper.sh的智能处理#!/bin/bash PROJECT_ROOT$1 OUTPUT$2 BUILDTYPE$3 GRADLE_CMD./gradlew [ -f ../gradlew ] GRADLE_CMD../gradlew if [[ $BUILDTYPE debug ]]; then $GRADLE_CMD -p $PROJECT_ROOT assembleDebug cp $PROJECT_ROOT/build/outputs/apk/debug/server-debug.apk $OUTPUT else $GRADLE_CMD -p $PROJECT_ROOT assembleRelease cp $PROJECT_ROOT/build/outputs/apk/release/server-release-unsigned.apk $OUTPUT fi3. 实战禁用预编译的全流程3.1 修改install_release.sh原始脚本会下载预编译Server我们需要移除这部分逻辑#!/usr/bin/env bash set -e BUILDDIRbuild-auto - PREBUILT_SERVER_URLhttps://github.com/Genymobile/scrcpy/releases/download/v1.24/scrcpy-server-v1.24 - PREBUILT_SERVER_SHA256ae74a81ea79c0dc7250e586627c278c0a9a8c5de46c9fb5c38c167fb1a36f056 - 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 $BUILDDIR --buildtyperelease --strip -Db_ltotrue \ - -Dprebuilt_serverscrcpy-server -Dprebuilt_server cd $BUILDDIR ninja echo [scrcpy] Installing (sudo)... sudo ninja install3.2 处理常见编译错误错误1NDK路径未找到FAILURE: Build failed with an exception. * What went wrong: A problem occurred configuring project :server. NDK not configured.解决方案# 在server/local.properties中添加 ndk.dir/path/to/ndk sdk.dir/path/to/sdk错误2Java版本不兼容Unsupported Java. Your build is currently configured to use Java 17...解决方法# 在server/gradle.properties中设置 android.jdkVersion11错误3Meson版本冲突Project specifies meson_version: 0.48 but found 0.47.升级Mesonpip install --upgrade meson4. 高级定制修改Server端功能4.1 修改视频编码参数在server/src/main/java/com/genymobile/scrcpy/ScreenEncoder.java中// 调整关键帧间隔 private static final int KEY_FRAME_RATE 5; // 原值10 // 修改码率控制 mediaFormat.setInteger(MediaFormat.KEY_BIT_RATE, 8_000_000); // 原值4_000_0004.2 添加自定义控制协议在server/src/main/java/com/genymobile/scrcpy/ControlMessage.java中添加新消息类型public static final int TYPE_CUSTOM_COMMAND 0x20;在Client端同步修改对应枚举// app/src/control_msg.h enum control_msg_type { ... CONTROL_MSG_TYPE_CUSTOM_COMMAND 0x20, };4.3 构建产物验证编译完成后验证产物信息# 检查APK基本信息 aapt dump badging build/server/outputs/apk/release/server-release-unsigned.apk # 提取so文件验证 unzip -l build/server/outputs/apk/release/server-release-unsigned.apk | grep .so # 与预编译版本对比 diff (unzip -v1 prebuilt/scrcpy-server) (unzip -v1 build/server/outputs/apk/release/server-release-unsigned.apk)5. 持续集成方案5.1 GitHub Actions配置示例name: Android Server Build on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up JDK 11 uses: actions/setup-javav3 with: java-version: 11 distribution: temurin - name: Install Android SDK uses: android-actions/setup-androidv2 - name: Install Build Tools run: | sdkmanager platforms;android-29 build-tools;30.0.3 sdkmanager ndk;21.4.7075529 - name: Build Server run: | cd server echo ndk.dir$ANDROID_HOME/ndk/21.4.7075529 local.properties ./gradlew assembleRelease - name: Archive Artifacts uses: actions/upload-artifactv3 with: name: scrcpy-server path: server/build/outputs/apk/release/server-release-unsigned.apk5.2 本地Docker构建环境FROM ubuntu:20.04 RUN apt-get update \ DEBIAN_FRONTENDnoninteractive apt-get install -y \ git wget unzip python3-pip ninja-build \ android-sdk android-ndk RUN pip3 install meson0.61.5 ENV ANDROID_HOME /usr/lib/android-sdk ENV NDK_HOME /usr/lib/android-ndk ENV PATH $ANDROID_HOME/cmdline-tools/latest/bin:$NDK_HOME:$PATH WORKDIR /scrcpy COPY . . CMD [bash, -c, meson build --buildtyperelease -Dprebuilt_server ninja -C build]构建命令docker build -t scrcpy-builder . docker run -v $(pwd)/output:/scrcpy/build scrcpy-builder6. 性能优化技巧6.1 加速增量编译在server/gradle.properties中添加org.gradle.paralleltrue org.gradle.cachingtrue org.gradle.daemontrue6.2 选择性依赖更新# 仅更新指定模块 ./gradlew :server:dependencies --update-dependency com.android.tools.build:gradle6.3 构建缓存配置# 设置Gradle缓存目录 export GRADLE_USER_HOME$HOME/.gradle-scrcpy # 清理缓存 ./gradlew cleanBuildCache7. 疑难问题解决方案7.1 符号表缺失问题当需要调试Native代码时需要保留调试符号# server/build.gradle android { buildTypes { release { - minifyEnabled true minifyEnabled false shrinkResources false ndk { debugSymbolLevel FULL } } } }7.2 多ABI支持处理默认Scrcpy只编译armeabi-v7a如需支持其他架构// server/build.gradle android { defaultConfig { ndk { abiFilters armeabi-v7a, arm64-v8a, x86, x86_64 } } }对应的Meson配置调整# 在交叉编译文件中指定ABI [properties] android_abi arm64-v8a7.3 版本号管理保持Client和Server版本同步# 根目录meson.build project(scrcpy, c, version: run_command( python3, -c, import re; print(re.search(rversionName\s\(.?)\, open(server/build.gradle).read()).group(1)), check: true ).stdout().strip(), ... )8. 安全加固建议8.1 签名配置创建签名密钥keytool -genkeypair -v \ -keystore scrcpy.jks \ -keyalg RSA -keysize 4096 \ -validity 10000 \ -alias scrcpy配置签名信息// server/build.gradle android { signingConfigs { release { storeFile file(../scrcpy.jks) storePassword System.getenv(STORE_PASSWORD) keyAlias scrcpy keyPassword System.getenv(KEY_PASSWORD) } } buildTypes { release { signingConfig signingConfigs.release } } }8.2 资源混淆// server/build.gradle buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile(proguard-android.txt), proguard-rules.pro } }在proguard-rules.pro中添加-keep class com.genymobile.scrcpy.** { *; }9. 扩展阅读9.1 关键源码文件文件路径核心功能server/src/main/scrcpy-server.cNative入口点server/src/main/java/.../Server.javaAndroid服务主逻辑app/src/video/decoder.c客户端视频解码实现app/src/control_msg.c控制协议序列化/反序列化9.2 调试技巧日志过滤adb logcat -s scrcpy性能分析# 采样CPU使用率 adb shell am profile start com.genymobile.scrcpy /sdcard/scrcpy.prof # 停止采样后拉取文件 adb pull /sdcard/scrcpy.prof内存分析adb shell dumpsys meminfo com.genymobile.scrcpy10. 结语构建系统的设计哲学Scrcpy的构建系统展现了现代跨平台项目的典型设计思路用Meson作为顶层构建协调器针对不同平台采用原生构建工具如Android的Gradle。这种架构既保持了跨平台的一致性又充分发挥了各平台工具链的优势。
