第4章 环境搭建：操作系统要求、依赖库安装、NDK/SDK配置、测试设备准备

帧率监控与掉帧定位工具的开发需要在特定平台上编译、链接和部署。本章围绕全栈开发环境搭建展开，涵盖操作系统选型、基础依赖库安装、Android NDK/SDK 配置以及测试设备准备。完成本章后，你可以在本地编译项目、连接真机或模拟器，并运行最初的调试验证程序。

4.1 操作系统要求

推荐操作系统及最低版本如下表所示。开发机建议使用 Ubuntu 20.04 或 Windows 10 20H2 以上，macOS 推荐 Monterey 并安装 Xcode Command Line Tools。

4.2 依赖库安装

帧率监控工具需要以下核心依赖：CMake（构建系统）、Ninja（加速构建）、Python 3（辅助脚本）、Git（版本控制）、Vulkan SDK / OpenGL（图形 API 接口）、FFmpeg libavutil（时间戳处理）、libyuv（YUV 转换）以及 perf / simpleperf（Linux 性能计数器）。

以 Ubuntu 20.04 为例，一键安装主要依赖：

sudo apt update
sudo apt install -y cmake ninja-build python3 python3-pip git \
    libvulkan-dev vulkan-tools libgl1-mesa-dev \
    libavutil-dev libswresample-dev libyuv-dev \
    linux-tools-common linux-tools-generic linux-tools-`uname -r`

macOS 使用 Homebrew：

brew install cmake ninja python git vulkan-sdk ffmpeg libyuv

Windows 使用 vcpkg 或 chocolatey：

choco install cmake ninja python3 git vulkan-sdk ffmpeg libyuv

4.3 NDK 与 SDK 配置

Android 开发环境要求：

• Android NDK：推荐 r25 或 r26（r23 以上支持 CMake 工具链）。
• Android SDK：API level 31（Android 12）或更高；建议同时安装 platform-tools（包含 adb）。
• Java JDK：OpenJDK 11 或 17（用于 Gradle/Android Studio）。

下载 NDK 并解压到 /opt/android-ndk（Linux/macOS）或 C:\Android\ndk（Windows）。然后设置全局环境变量：

# Linux / macOS (添加至 ~/.bashrc 或 ~/.zshrc)
export ANDROID_NDK_HOME=/opt/android-ndk
export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export PATH=$ANDROID_NDK_HOME:$ANDROID_SDK_ROOT/platform-tools:$PATH

# Windows (系统变量)
set ANDROID_NDK_HOME=C:\Android\ndk
set ANDROID_SDK_ROOT=%USERPROFILE%\AppData\Local\Android\Sdk
set PATH=%PATH%;%ANDROID_NDK_HOME%;%ANDROID_SDK_ROOT%\platform-tools

验证 NDK 工具链可用：

ls $ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/
# 应看到 aarch64-linux-android21-clang 等文件

mkdir test && cd test
echo "int main(){}" > main.c
$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
    -DANDROID_ABI=arm64-v8a \
    -DANDROID_PLATFORM=android-31 \
    -DCMAKE_BUILD_TYPE=Release \
    -S . -B build
cmake --build build

4.4 测试设备准备

帧率监控工具最终运行在 Android 真机 或 模拟器 上。推荐配置：

连接真机后验证：

adb devices
# 输出类似：
# List of devices attached
# 0123456789ABCDEF    device

4.5 环境验证脚本

运行以下 Bash 脚本一键检测所有环境依赖是否就绪（保存为 check_env.sh）：

#!/bin/bash
echo "=== 帧率监控开发环境检查 ==="

# 1. 操作系统
echo "[OS] $(uname -a)"

# 2. 基础工具
for cmd in cmake ninja python3 git adb; do
    which $cmd > /dev/null 2>&1 && echo "[OK] $cmd" || echo "[FAIL] $cmd not found"
done

# 3. NDK
if [ -d "$ANDROID_NDK_HOME" ]; then
    echo "[OK] ANDROID_NDK_HOME=$ANDROID_NDK_HOME"
else
    echo "[FAIL] ANDROID_NDK_HOME not set or directory missing"
fi

# 4. Vulkan SDK
vulkaninfo --summary 2>/dev/null | head -1 && echo "[OK] Vulkan" || echo "[WARN] Vulkan info missing"

# 5. adb 连接
adb get-state 2>/dev/null && echo "[OK] Device connected" || echo "[WARN] No device/emulator"

echo "=== 完成 ==="

常见错误与避坑指南

• NDK 路径问题：误将 NDK 解压到包含空格的目录（如 C:\Program Files\），导致 CMake 无法解析路径。解决方案：使用纯英文路径且无空格。
• Vulkan 加载失败：模拟器默认使用 SwiftShader 软件渲染，不支持 Vulkan。必须勾选模拟器硬件加速（Graphics: Hardware - GLES）。
• adb 未授权：真机连接后需在手机端点击“允许 USB 调试”，并勾选“始终允许这台计算机”。
• JDK 版本不匹配：Android Gradle 插件 8.0+ 要求 JDK 17。如果使用 JDK 8，编译会报错。推荐使用 OpenJDK 17。
• libyuv 缺失：某些包管理器可能不提供 libyuv 开发包。替代方案：手动克隆并编译 https://chromium.googlesource.com/libyuv/libyuv。