前言

在使用 uniapp 进行跨端开发时，蓝牙（bluetooth）相关功能是物联网、设备互联类项目的常用需求。很多开发者在云端打包时能正常使用蓝牙功能，但切换到本地离线打包后，会遇到“未添加bluetooth模块”的报错提示，导致蓝牙功能无法正常调用。

本文将针对该问题，提供 Android 端 本地离线打包解决方案，步骤详细可落地，帮助开发者快速排查并解决问题。

一、问题核心原因

uniapp 的蓝牙功能依赖于底层原生 SDK 提供的模块支持：

1. 云端打包时，uniapp 会根据 manifest.json 中的配置自动引入对应的模块依赖，无需手动操作；
2. 本地离线打包时，需要开发者手动在原生工程中配置蓝牙模块的依赖（包括权限声明、SDK 引入、模块注册等），缺少任一环节都会触发“未添加bluetooth模块”的报错。

二、Android 端 本地离线打包解决方案

前提准备

1. 已完成 uniapp Android 本地离线打包环境搭建（已导入官方 Demo 工程、配置签名等）；

2. 已获取对应版本的 uniapp Android SDK（与项目 uniapp 版本保持一致）。

步骤 1：配置 manifest.json 开启蓝牙模块

首先确保项目的 manifest.json 中已开启蓝牙相关权限和模块，这是基础前提：

1. 打开项目根目录的 manifest.json 文件，切换到「App 模块配置」标签页；

2. 找到「蓝牙」模块，勾选「蓝牙（bluetooth）」（若需要低功耗蓝牙，同时勾选「低功耗蓝牙（ble）」）；
   
   注意：查看 manifest.json文件是否存在

 "modules" : {
            "Bluetooth" : {}
        },

3. 切换到「App 权限配置」标签页，勾选以下蓝牙相关权限：

  - android.permission.BLUETOOTH

  - android.permission.BLUETOOTH_ADMIN

  - android.permission.ACCESS_FINE_LOCATION（Android 6.0 及以上蓝牙扫描需要）

  - android.permission.BLUETOOTH_SCAN（Android 12 及以上）

  - android.permission.BLUETOOTH_CONNECT（Android 12 及以上）

4. 保存 manifest.json，重新生成 uniapp 资源包（「发行」->「生成本地打包 App 资源」），替换原生工程中的 assets/apps 目录下对应资源。

步骤 2：原生工程引入蓝牙模块依赖

1. 使用 Android Studio打开uniapp离线打包项目；
2. 找到工程\HBuilder-HelloUniApp\app\libs下面的Bluetooth-release.aar文件；
3. 将上面的蓝牙文件复制到HBuilder-Integrate-AS\simpleDemo\libs下
   注意：app的build.gradle下需要有以下代码

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])
    }

步骤 3：配置 AndroidManifest.xml 声明权限和模块

1. 打开 app/src/main/AndroidManifest.xml 文件；

2. 在 标签内添加蓝牙相关权限（若 manifest.json 配置未自动同步，手动补充）：

<!-- 基础蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- 蓝牙扫描所需位置权限（Android 6.0+） -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Android 12+ 新增蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- 声明蓝牙硬件特性（可选，过滤无蓝牙设备） -->
<uses-feature android:name="android.hardware.bluetooth" android:required="false" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />

<!-- 当targetSdkVersion31及以上版本时，需追加如下权限:-->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />     
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

步骤 4：dcloud_properties.xml需要添加如下代码

<feature name="Bluetooth" value="io.dcloud.feature.bluetooth.BluetoothFeature"/>

步骤 5：验证与排查

1. 清理工程（Build -> Clean Project），重新构建并运行 App；
2. 若仍报错，排查以下点：

• uniapp SDK 版本与项目版本是否一致（版本不兼容会导致模块无法识别）；
• 原生工程的 libs 目录下是否存在 uniapp-v8-release.aar（缺失则重新拷贝 SDK 中的对应文件）；
• 蓝牙功能是否在主线程外调用（uniapp 蓝牙 API 需在主线程中执行）。

附录

1. uniapp 本地离线打包官方文档：https://nativesupport.dcloud.net.cn/AppDocs/usesdk/android.html

2. uniapp 蓝牙 API 官方文档：https://uniapp.dcloud.io/api/system/bluetooth