3、开发环境搭建：Android Studio配置、SDK版本选择、真机调试与权限声明

Android蓝牙开发的第一步，是搭建一个稳定、可控、可复现的工程环境。蓝牙开发与普通应用开发最大的不同在于：它高度依赖硬件状态、系统服务版本和权限模型。很多初学者在写完代码后遇到 BluetoothAdapter is null 或 Permission Denial 时，往往不是业务逻辑出错，而是环境配置或权限声明不当。本章将围绕Android Studio配置、SDK版本选择、真机调试流程以及蓝牙权限声明四个核心模块展开，帮助你建立一套从工程创建到真机运行的完整闭环。

3.1 Android Studio配置：从安装到工程级调优

核心原理

Android Studio（以下简称AS）是Android官方IDE，基于IntelliJ IDEA构建。对于蓝牙开发而言，AS的配置重点不在于界面美化，而在于构建系统（Gradle）与JDK版本的匹配。蓝牙项目通常需要引入第三方库（如RxAndroidBle、FastBLE），这些库对AGP（Android Gradle Plugin）版本有最低要求。例如，RxAndroidBle 1.17.0要求AGP 7.0以上，而AGP 8.x则强制要求JDK 17。如果JDK版本不匹配，Gradle会在同步阶段抛出 Unsupported class file major version 错误。

操作流程

1. 安装AS与SDK组件：从官网下载最新稳定版（如Hedgehog或Iguana），安装时勾选Android SDK、Android SDK Platform-Tools和Performance Profiler。建议同时安装Google USB Driver（Windows平台用于真机调试）。
2. 配置JDK：AS 4.2+内置JBR（JetBrains Runtime），但为了统一团队环境，建议在Project Structure → SDK Location中指定JDK 17路径。在gradle.properties中可添加org.gradle.java.home=/path/to/jdk17强制指定。
3. Gradle与AGP版本对齐：在根目录build.gradle中声明AGP版本，例如com.android.application:8.2.2，并在gradle-wrapper.properties中指定Gradle 8.2+。版本不匹配时，AS会提示“Minimum supported Gradle version is X.X.X”。
4. 优化构建速度：在gradle.properties中启用org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8，并开启org.gradle.caching=true和org.gradle.parallel=true。对于蓝牙项目，建议关闭android.enableJetifier=true（如果不需要旧库兼容）。

案例拆解：Gradle同步失败排障

某学员在导入一个蓝牙串口示例工程时，AS提示Failed to resolve: com.github.hoijui:Java-WebSocket:1.5.0。分析过程如下：该库托管在JitPack仓库，但工程根build.gradle中未添加maven { url 'https://jitpack.io' }。解决步骤：在allprojects.repositories中添加JitPack仓库，并同步。另一个常见问题是Could not find com.android.tools.build:gradle:8.2.2，这通常是因为网络无法访问Google Maven仓库，需要配置阿里云镜像或使用代理。

3.2 SDK版本选择：minSdk、targetSdk与蓝牙API演进

核心原理

Android蓝牙API自4.0（API 14）引入经典蓝牙，5.0（API 21）引入BLE中心设备模式，6.0（API 23）引入动态权限，12（API 31）引入BLUETOOTH_SCAN等细分权限。选择SDK版本的本质是在功能覆盖与设备兼容性之间做权衡。如果minSdk设置过高（如26），会丢失大量Android 7.0及以下设备用户；如果targetSdk设置过低（如28），系统会强制启用兼容模式，导致蓝牙扫描回调无法获取ScanResult中的广播包数据。

判断方法

实战场景

假设你开发一个蓝牙心率计App，需要支持Android 6.0到14.0的设备。推荐配置：minSdk 23（避免动态权限兼容代码），targetSdk 33（满足Google Play上架要求），compileSdk 34（使用最新API编译）。在build.gradle中设置：

android {
    compileSdk 34
    defaultConfig {
        minSdk 23
        targetSdk 33
    }
}

同时，在代码中判断版本：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    // 使用BluetoothLeScanner
} else {
    // 使用startLeScan()
}

常见误区

• 误区1：targetSdk越高越好。实际上，targetSdk 34会强制启用BLUETOOTH_CONNECT权限，如果未声明会导致SecurityException。
• 误区2：忽略compileSdk与targetSdk的区别。compileSdk决定编译时可用的API，targetSdk决定运行时行为。两者可以不同，但compileSdk必须大于等于targetSdk。
• 误区3：在Android 12+设备上，仅声明BLUETOOTH权限即可。实际上，Android 12引入了BLUETOOTH_SCAN、BLUETOOTH_ADVERTISE和BLUETOOTH_CONNECT三个新权限，旧权限已废弃。

3.3 真机调试：从USB连接到日志分析

核心原理

蓝牙功能无法在模拟器上完整测试，因为模拟器不提供真实的蓝牙射频硬件。真机调试的核心是建立ADB（Android Debug Bridge）通道，通过USB或Wi-Fi将开发机与手机连接。对于蓝牙开发，还需要确保手机蓝牙已开启，并且App具有系统级调试权限（可通过adb root获取，但仅限工程机）。

操作流程

1. 开启开发者选项：在手机设置 → 关于手机中连续点击“版本号”7次，然后进入开发者选项，开启USB调试和USB安装。
2. 连接USB线：建议使用原装数据线，避免仅充电线（无数据通道）。连接后，手机弹出“允许USB调试”对话框，勾选“始终允许”。
3. 验证连接：在AS终端执行adb devices，若显示device状态而非unauthorized或offline，则连接成功。若显示offline，尝试重新插拔或执行adb kill-server后重启。
4. 配置无线调试（可选）：Android 11+支持无线调试。在开发者选项中开启无线调试，使用adb pair ip:port配对，然后adb connect ip:port连接。
5. 日志过滤：蓝牙相关日志Tag通常为BluetoothAdapter、BluetoothGatt或自定义Tag。使用命令adb logcat -s BluetoothAdapter:V BluetoothGatt:D过滤。

案例拆解：连接失败但无异常日志

某次调试中，App调用connectGatt()后，onConnectionStateChange回调返回133（GATT_ERROR）。初步分析：错误码133表示连接失败，但原因不明。进一步检查：

• 使用adb logcat -b all | grep -i bluetooth查看系统蓝牙日志，发现bt_btif: bta_dm_remname异常。
• 检查手机蓝牙是否已与其他设备配对，导致连接冲突。
• 确认目标设备（如BLE传感器）是否处于可连接状态，且广播间隔正常。

最终定位为：目标设备进入深度睡眠模式，无法响应连接请求。解决方法是先扫描设备，获取其MAC地址，再在设备唤醒后立即连接。复盘经验：蓝牙调试必须结合系统日志与硬件状态，不能只看App层回调。

3.4 权限声明：Manifest配置与动态请求

核心原理

蓝牙权限分为安装时权限和运行时权限。安装时权限在Manifest中声明，用户安装时自动授予；运行时权限需要App在运行中动态请求。Android 12（API 31）之前，蓝牙权限属于安装时权限；Android 12之后，BLUETOOTH_SCAN、BLUETOOTH_ADVERTISE和BLUETOOTH_CONNECT变为运行时权限，且需要配合ACCESS_FINE_LOCATION（用于扫描）或ACCESS_COARSE_LOCATION（Android 10+）。

Manifest配置模板

<!-- 经典蓝牙与BLE通用 -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
<!-- Android 12+ 细分权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- 定位权限（扫描必需） -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 声明硬件特性 -->
<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

动态请求代码

private void requestBluetoothPermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        requestPermissions(new String[]{
                Manifest.permission.BLUETOOTH_SCAN,
                Manifest.permission.BLUETOOTH_CONNECT,
                Manifest.permission.ACCESS_FINE_LOCATION
        }, REQUEST_BLUETOOTH_PERMISSIONS);
    } else {
        requestPermissions(new String[]{
                Manifest.permission.ACCESS_FINE_LOCATION
        }, REQUEST_BLUETOOTH_PERMISSIONS);
    }
}

常见误区与总结

• 误区1：只声明BLUETOOTH权限，导致Android 12+设备上无法扫描。必须同时声明BLUETOOTH_SCAN和ACCESS_FINE_LOCATION。
• 误区2：忘记在Manifest中添加<uses-feature>，导致Google Play过滤掉不支持蓝牙的设备。
• 误区3：动态请求权限后，未在onRequestPermissionsResult中处理拒绝逻辑。建议在拒绝后提示用户并引导至设置页。