背景说明目前正在开发一款需要与硬件交互的 App其中使用了 BLEBluetooth Low Energy低功耗蓝牙扫描功能。最开始使用 iOS 模拟器进行测试但调用蓝牙扫描接口时返回了以下错误10001 not available 当前蓝牙适配器不可用经过排查发现iOS 模拟器无法正常测试真实蓝牙功能。BLE 功能需要使用以下任意一种方式测试 iPhone 真机 HBuilderX 自定义基座而在 iPhone 上运行开发版 App需要准备以下签名材料Apple Development 开发证书证书私钥.p12私钥证书.mobileprovisionProfile 文件与 Profile 一致的 Bundle ID如果暂时没有购买 Apple Developer Program也可以使用普通 Apple ID 的免费Personal Team完成个人真机调试。⚠️ 免费 Personal Team 生成的 Profile 通常只有 7 天有效期过期后需要重新生成、签名并安装。具体操作一、 准备 Xcode 和 iPhone1. 安装 Xcode2. 登录 Apple ID打开 Xcode进入Xcode → Settings → Accounts点击左下角的登录自己的普通 Apple ID。登录成功后通常会看到你的名字 (Personal Team)Personal Team表示当前使用的是免费开发团队可以用于个人设备真机调试但不能发布到 App Store 或 TestFlight。3. 连接 iPhone使用支持数据传输的 USB 数据线连接 Mac 和 iPhone。连接时注意 保持 iPhone 解锁✅ Mac 弹出“允许配件连接”时选择“允许”✅ iPhone 弹出“要信任此电脑吗”时选择“信任” 根据提示输入 iPhone 锁屏密码用数据线连接 iPhone手机上点击“信任此电脑”。4. 在 Xcode 中查看设备打开Window → Devices and Simulators也可以使用快捷键Shift Command 2选择顶部的Devices在左侧Connected区域确认能看到自己的 iPhone。 如果 Xcode 中没有设备可以先检查 Finder 左侧“位置”中是否显示 iPhone。Finder 也没有优先排查数据线、USB 接口和信任关系。Finder 有、Xcode 没有尝试保持手机解锁重启 Xcode或检查 Xcode 与 iOS 版本是否兼容。当设备出现在Connected下时说明 iPhone 已经成功连接到 Xcode。⚠️ 注意这里应当是 Xcode 登录的 Apple ID而不是 AppID。Apple ID 与 Bundle ID 是两个不同概念。到这一步我们的iPhone就和Xcode连上了注意手机要和Xcode登录同一个appID二、 创建临时 Xcode 工程创建临时工程的目的是让 Xcode 自动生成开发证书证书私钥App IDProvisioning Profile1. 创建项目在 Xcode 欢迎页面选择Create a new Xcode project → iOS → App2. 填写项目信息可以参考以下配置Product Name: FamilyDog Organization Identifier: com.yourname Bundle Identifier: com.yourname.familydog Interface: SwiftUI Language: SwiftBundle ID 必须尽量保持唯一例如com.lina.familydog 请记住这个 Bundle ID。后续在 HBuilderX 中签名时必须填写完全相同的值包括大小写3. 配置自动签名项目创建完成后点击左侧最上方的项目图标。在TARGETS中选择当前 App。进入Signing Capabilities。勾选Automatically manage signingTeam选择你的名字 (Personal Team)配置成功后Xcode 会显示类似信息Provisioning Profile: Xcode Managed Profile Signing Certificate: Apple Development: 你的 Apple ID如果没有红色签名错误说明配置基本成功。4. 选择真机运行在 Xcode 顶部运行设备选择框中选择你的 iPhone然后点击运行按钮▶首次运行时Xcode 可能显示Preparing device for development这是在为 iPhone 准备开发环境等待完成即可。三、 开启 iPhone 开发者模式首次安装开发版 App 时iPhone 可能要求开启开发者模式。Preparing device for development打开设置 → 隐私与安全性 → 开发者模式打开开发者模式后iPhone 会提示重启。重启后解锁手机。在确认弹窗中再次点击“开启”。输入锁屏密码完成确认。 “开发者模式”通常只有在 iPhone 与 Xcode 完成配对或尝试运行开发 App 后才会出现。四、 信任开发者证书注意也许会提示此app没有被信任这也就这个提示那就需要我们去在手机上信任它。The Developer App Certificate is not trusted表示 App 已经安装到 iPhone但手机还没有信任当前 Apple Development 证书。在 iPhone 中打开设置 → 通用 → VPN与设备管理部分系统版本可能显示为设置 → 通用 → 设备管理在“开发者 App”下面找到与你 Apple ID 对应的项目例如Apple Development: 你的名字或者直接显示你的 Apple ID 邮箱。依次点击信任“Apple Development: 你的名字” → 再次确认“信任”完成后保持 iPhone 解锁并连接 Mac。回到 Xcode。关闭错误弹窗。再次点击运行按钮▶。当 iPhone 上成功打开刚刚创建的空白 App 时说明以下内容已经准备完成✅ Apple Development 证书✅ 证书私钥✅ Xcode Managed Profile✅ iPhone 真机开发环境❓ 如果“VPN与设备管理”中没有开发者证书请先确保手机能够联网然后等待几十秒再重新进入该页面。五、 导出私钥证书.p12打开 macOS 的“钥匙串访问”应用程序 → 实用工具 → 钥匙串访问也可以按下Command 空格搜索“钥匙串访问”。导出步骤左侧选择“登录”钥匙串。分类选择“我的证书”。找到类似下面的证书Apple Development: 你的名字 (团队 ID)点击证书左侧的小三角将其展开。确认下面存在一条“私钥”。按住Command同时选中证书和私钥。右键选择导出 2 个项目文件格式选择个人信息交换 (.p12)设置一个导出密码并妥善保存。可以将文件保存为familydog-development.p12 这里设置的密码后续需要填写到 HBuilderX 中请务必记住。⚠️ 如果只能导出.cer文件说明没有同时选中证书和私钥。HBuilderX 需要的是包含私钥的.p12文件。导出过程中macOS 可能会要求输入一次或两次电脑登录密码这是正常现象。六、 查找 Profile 文件Xcode 自动生成的 Profile 通常位于以下两个目录之一~/Library/Developer/Xcode/UserData/Provisioning Profiles/或者~/Library/MobileDevice/Provisioning Profiles/查找方法打开 Finder按下Command Shift G分别粘贴以上路径。找到最近生成的文件xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.mobileprovision可以按修改时间排序选择刚刚运行 Xcode 工程时生成的文件。为了方便识别可以将其复制到桌面并重命名为familydog.mobileprovision✅ 可以修改文件名但不要修改文件内容。如果两个目录都找不到可以在终端运行find $HOME/Library/Developer/Xcode/UserData/Provisioning Profiles \ $HOME/Library/MobileDevice/Provisioning Profiles \ -type f -name *.mobileprovision 2/dev/null七、 在 HBuilderX 中使用证书打开 HBuilderX选择运行 → 运行到 iOS App 基座 → 使用 Apple 证书签名填写以下内容Bundle ID: com.lina.familydog 私钥证书 P12: familydog-development.p12 私钥密码: 导出 P12 时设置的密码 Profile: familydog.mobileprovision⚠️ 重点检查HBuilderX 中填写的 Bundle ID 必须与 Xcode 工程中的 Bundle ID 完全一致com.lina.familydog包括字母大小写点号位置单词拼写如果不一致可能出现签名失败、Profile 不匹配或 App 无法安装等问题。HBuilderX 签名需要的主要材料包括材料示例Bundle IDcom.lina.familydogP12 私钥证书familydog-development.p12P12 密码导出时设置的密码Profilefamilydog.mobileprovision八、 UTS 插件与自定义基座当前项目包含 BLE UTS 插件因此需要制作自定义基座进行真机测试。推荐流程准备 P12 和 Profile → 在 HBuilderX 中配置 Bundle ID → 制作 iOS 自定义基座 → 使用证书重新签名 → 安装到 iPhone → 测试 BLE 扫描和连接iOS 模拟器通常无法测试真实 BLE 硬件扫描因此最终仍需要使用 iPhone 真机验证。九、⚠️ 免费 Personal Team 的限制普通 Apple ID 可以免费完成个人真机调试但存在以下限制⏳ Profile 通常只有 7 天有效期 最多注册少量测试设备 每台设备可安装的开发 App 数量有限 无法发布到 App Store 无法使用 TestFlight 过期后需要重新生成 Profile、重新签名并安装如果后续需要长期测试、多人安装或正式发布建议购买 Apple Developer Program。✅ 最终检查清单开始 BLE 真机测试前请确认Xcode 已登录 Apple IDXcode 中显示Personal TeamFinder 可以识别 iPhoneXcode 可以识别 iPhoneiPhone 已开启开发者模式iPhone 已信任开发者证书Xcode 临时 App 可以正常运行已导出包含私钥的.p12已找到.mobileprovisionHBuilderX Bundle ID 与 Xcode 完全一致已制作并安装 iOS 自定义基座使用 iPhone 真机测试 BLE 功能完成以上步骤后就可以在 iPhone 真机中测试 BLE 扫描、连接及硬件交互功能了。