手把手教你实现安卓蓝牙文件传输（含Android 14权限适配与踩坑实录）

前言

最近在学习《移动软件开发》课程时，我接到了一个任务：开发一个安卓App，实现两台手机通过蓝牙互传图片。听起来很简单？我一开始也这么认为。然而，随着安卓系统的飞速迭代，曾经简单的几行代码，如今需要面对权限申请、后台限制、分区存储、版本适配等一系列“现代化”的挑战。

这篇博客，既是我的学习成果总结，也是一份详尽的“踩坑避坑”指南。希望能帮助正在或将要探索安卓蓝牙开发的你，少走一些弯路。

一、 最终成果展示

发送方：选择图片后，连接设备，显示发送成功。接收方：接收成功后，提示文件保存路径，并在系统相册中可见。

二、 核心原理与项目搭建

1. 蓝牙通信原理

安卓蓝牙通信是典型的 客户端-服务器 (C/S) 模型：

服务端(Server): 创建一个 BluetoothServerSocket，在一个唯一的 UUID 上进行监听 (listen)，然后调用 accept() 进入阻塞状态，等待客户端连接。客户端(Client): 通过服务端的MAC地址和同一个 UUID 创建 BluetoothSocket，然后调用 connect() 发起连接。数据交换: 连接成功后，双方通过 InputStream 和 OutputStream 进行数据的读写，完成文件传输。

2. 项目基础搭建

UI布局 (activity_main.xml): 界面很简单，包含几个核心功能的按钮和一个用于显示状态的 TextView。

三、 Android权限

这是整个项目中最具挑战性的部分。如果你的App还在使用旧的权限申请方式，那么在Android 12以上的设备上几乎寸步难行。

1. AndroidManifest.xml 中的权限申请

我们需要一个能兼容新旧所有版本的权限声明清单。关键在于使用 maxSdkVersion 属性。

2. 运行时权限请求

告别繁琐的 onRequestPermissionsResult ，使用 ActivityResultLauncher 可以让权限处理逻辑更清晰、更解耦。我们需要为“请求蓝牙权限”、“请求存储权限”和“打开文件选择器”分别创建Launcher。

// 在Activity中定义成员变量

private ActivityResultLauncher requestBluetoothPermissionsLauncher;

private ActivityResultLauncher requestStoragePermissionLauncher;

private ActivityResultLauncher filePickerLauncher;

// 在onCreate中初始化

private void initLaunchers() {

// 1. 蓝牙多权限请求

requestBluetoothPermissionsLauncher = registerForActivityResult(

new ActivityResultContracts.RequestMultiplePermissions(),

permissions -> { /* ... 处理权限授予结果 ... */ });

// 2. 存储单权限请求

requestStoragePermissionLauncher = registerForActivityResult(

new ActivityResultContracts.RequestPermission(),

isGranted -> {

if (isGranted) openFilePicker();

else Toast.makeText(this, "需要权限才能选文件", Toast.SHORT).show();

});

// 3. 文件选择器

filePickerLauncher = registerForActivityResult(

new ActivityResultContracts.StartActivityForResult(),

result -> { /* ... 处理选择的文件URI ... */ });

}

四、 核心代码实现

这里我们直接贴出经过所有调试和优化后的最终核心方法。

发送文件 (sendFile)

private void sendFile(BluetoothSocket socket) {

// ... 省略非核心代码 ...

try (InputStream inputStream = getContentResolver().openInputStream(selectedFileUri);

OutputStream outputStream = socket.getOutputStream()) {

byte[] buffer = new byte[8192];

int bytesRead;

while ((bytesRead = inputStream.read(buffer)) != -1) {

outputStream.write(buffer, 0, bytesRead);

}

outputStream.flush();

// [可选优化] 在这里可以加入一个Thread.sleep(100)给接收方留出反应时间

} catch (IOException e) {

// ...

}

// ...

}

接收文件 (receiveFile) - 适配分区存储与异常处理

这是整个项目的精华所在，它解决了分区存储和我们后面会提到的“假失败”问题。

private void receiveFile(BluetoothSocket socket) {

if (socket == null) return;

try (InputStream inputStream = socket.getInputStream()) {

// ... 使用MediaStore API创建文件输出流 ...

// 详细代码见上一轮回答，此处省略

// --- 核心读写循环 ---

byte[] buffer = new byte[8192];

while (inputStream.read(buffer) != -1) {

// ... fileOutputStream.write(...) ...

}

} catch (IOException e) {

// 关键：对特定“成功”异常的处理

if (e.getMessage() != null && e.getMessage().contains("bt socket closed, read return: -1")) {

// 这是成功的标志，更新UI为成功

} else {

// 这是真正的失败，更新UI为失败

}

} finally {

// ... 关闭socket ...

}

}

五、 踩坑实录：我的调试之旅

天坑一：小米(MIUI)的“权限墙”

现象：应用在其他手机上正常，在小米上安装失败，提示 INSTALL_FAILED_USER_RESTRICTED，或者选择文件时提示“没有权限”。原因：MIUI拥有独特的、更严格的权限管理机制。解法：必须手动进入 手机管家 -> 应用管理 -> 你的App -> 权限管理，要打开“文件和媒体”权限和一个隐藏的“后台弹出界面”权限。否则，系统级的权限请求对话框根本无法弹出。

天坑二：文件接收的“假失败”

现象：这是最诡异的问题。发送方显示成功，接收方的相册里也确实出现了图片，但我的App却提示“接收文件失败”。探究：通过查看Logcat，我发现每当接收失败时，总会捕获到一个特定的异常：java.io.IOException: bt socket closed, read return: -1。顿悟：read return: -1 在Java I/O中本是数据流正常结束的标志。但安卓蓝牙的底层实现，在连接被对方迅速关闭时，会将这个“正常结束”信号包装成一个IOException抛出！所以，我的程序成功接收了所有数据，却在最后一步将“成功”误判为了“失败”。解法：如上面的receiveFile代码所示，在catch块里对这个特定的异常信息进行判断。如果是它，就执行成功的逻辑；如果是其他IOException，才认为是真正的失败。

[完整的项目代码已上传至GitHub：collapsar-git/BluetoothFiletransfer: 安卓手机间通过蓝牙传输文件]