React Native 鸿蒙实战：给播放器接入空间音频，让声音跟着设备转起来

示例仓库：https://atomgit.com/m0_37170006/react-native-ohos-spatial-audio 社区导引：框架源码与版本发布见 https://atomgit.com/CPF-RN/ohos_react_native/tree/0.84-main CPF-RN 鸿蒙社区：https://atomgit.com/CPF-rn

空间音频支不支持怎么探测、系统开关变了怎么第一时间知道、播放器和音效怎么接——这篇文章用一个跑在 HarmonyOS 7 真机（HUAWEI Pura X View）上的 RN 工程，把这三个问题讲透，顺带交出 12 个带报错原文的踩坑记录。

1. 照着教程抄，编译都过不了

我们 RN 业务里的音频一直是最朴素的状态：能出声就行。直到把应用跑上鸿蒙，我发现自己的手机（HarmonyOS 7）和耳机都支持空间音频——系统播放器戴上耳机就有明显的方位感，而我们应用里播同样的内容，还是两个声道贴着耳朵的扁平听感。落差就在这儿：能不能让 RN 应用也用上系统的空间音频？我的第一反应是搜现成的三方库，结果在 RN 鸿蒙生态里翻了一圈，播放器库不少，暴露空间音频能力的一个都没有。

很快搜到一篇 HarmonyOS 7 空间音频实战，照着敲 setSpatializationEnabled——DevEco 里这行直接飘红：属性不存在。我先是怀疑自己抄漏了什么，又换了几种写法，全是一样的报错。到这一步我才意识到，问题可能不在写法上，而在更根本的地方。

多说两句为什么这件事对 RN 开发者格外重要：原生鸿蒙应用面对一条 API 边界，翻一翻官方文档、问问有经验的同事，通常很快有答案；而 RN 这边要多翻一座山——你先要判断问题出在 JS 侧、桥接层还是鸿蒙侧，再判断是自己的写法问题还是生态缺位。一个"属性不存在"的报错，背后可能是三种完全不同层面的原因。这也是我后来把整个排查过程完整记下来的原因：坑的定位成本在跨端框架里被放大了，记录下来对后来人才有复用价值。

把 DevEco 自带的 SDK 声明文件翻出来逐个搜（@ohos.multimedia.audio.d.ts，位于 DevEco 安装目录 sdk/default/openharmony/ets/api/ 下），结果一目了然：

# 在 SDK 的 d.ts 里全局搜索教程用到的接口
grep -rn "setSpatializationEnabled\|isHeadTrackingSupported\|setHeadTrackingEnabled" \
  "DevEco Studio/sdk/default"          # openharmony + hms 全量目录

# 结果：零命中

对照 OpenHarmony 官方文档，AudioSpatializationManager 的公开页面只有三个接口：

接口	作用	起始版本
isSpatializationEnabledForCurrentDevice(): boolean	查询当前设备空间音频是否开启	API 18
on('spatializationEnabledChangeForCurrentDevice', cb)	订阅开启状态变化	API 18
off('spatializationEnabledChangeForCurrentDevice', cb?)	取消订阅	API 18

把 SDK 的声明文件和官方文档翻完，事情反而清楚了：set 系列接口是系统应用专属，三方应用没有调用的资格——那一刻我的感受就是一句大白话：哦，原来开关不归我管。但文档同时给了另一样东西：查询和监听。设备支不支持、现在开没开、什么时候变了，这三件事三方应用全都能拿到。问题于是从”怎么帮用户开空间音频”，变成了”怎么感知它，并在不支持的时候体面地降级”。

回头想想这个设计其实合理：空间音频的开关牵扯到系统级的渲染管线和每副耳机各自的渲染配置，如果任意一个三方应用都能全局改写它，用户在别的 App 里的听感会被来回改写，体验只会更乱。把开关权留在系统、把知情权交给应用，边界划得很清楚。
本文交付三样东西：一个开源的 TurboModule 三方库（能力探测 + 事件桥 + AVPlayer 播放封装 + React Hook，仓库地址见文末）、一个能点能按的 demo，以及 12 个全部带报错原文的踩坑记录。

2. 效果：先听为敬

demo 界面一共四块：右上角的模式徽标、设备能力卡片、系统设置引导、播放器和事件日志。这张截图是它第一次完整跑起来的样子——时间是凌晨一点多，前面为了一个 TurboModule 的注册问题红屏了三次，界面亮出来那一刻我是真的高兴：原来 RN 也可以把鸿蒙的空间音频用起来。

四个区域是按"用户最想知道什么"来排的：模式徽标回答"我现在听的是什么状态"，设备卡片回答"我的设备行不行"，引导区回答"不行的话该去哪开"，播放器和日志负责验证"开了之后真的不一样"。写业务 App 的时候完全可以照这个信息优先级来摆 UI。

换设备实测：外放下能力行老老实实显示“不支持”；换 FreeLace Pro 2，还是不支持——这副本来就没有空间音频，降级判断完全正确；再连 FreeBuds Pro 5，能力行“啪”地变绿“支持”，那一刻是真的有成就感。还有个小惊喜是 FreeClip 2：我本来以为这副耳夹式的不支持，去智慧生活的设备详情页一看，它居然也有“高清空间音频”的开关——也是支持的。

最想给大家演示的是这个瞬间：App 保持在前台，去系统设置（入口在“设置→蓝牙→耳机详情页→高清空间音频”，有关闭/固定/头部跟踪三态）把开关从“关闭”切到“固定”——切回 App 的那一秒，徽标自己从灰色的“立体声”跳成了绿色的“空间音频已开启”，事件日志同步多出一条记录。全程我没有点过任何按钮，包括那个“重新探测”。戴上耳机再听那段环绕 5.1，声音真的有了方位感，我是激动得叫出声的。系统开关一动，应用这边秒级跟上——这就是事件桥的价值，上图日志里的时间线（05:45:10 开启=✗ → 05:57:44 开启=√）就是这一刻留下的铁证。

把三副耳机都试了一遍之后，最直观的感受来自那段自制的 5.1“方位巡礼”测试音：六个不同音高的纯音从前左、前右、中置、低音、后左、后右依次响起。关闭空间音频时，这六个音挤在两耳中间一条线上，像隔着墙听；切到固定模式，声音明显散开了，前后左右的方位能分辨出来，低音沉在下面，像置身在一圈音箱中间；再切到头部跟踪、转动头部，差别最惊艳——声场像是钉在了房间里，我向左转头，声音就“跑到”右耳方向，前方的音始终在前方，完全不是普通耳机那种声音跟着脑袋走的感觉。

下面这段 30 秒录屏，完整演示了播放环绕 5.1 与空间音频开关切换：徽标、能力卡片、事件日志全程实时联动。

3. 原理：一条被低估的边界，一条必须走通的链路

3.1 鸿蒙空间音频的能力分层

两天搞下来，我对鸿蒙空间音频最大的感受是：难的系统都做完了，交给开发者的是一套成熟的 API——我们要做的，只是把 RN 到系统之间的这座桥搭对。具体拆开是三层，一层比一层贴近我们的代码：

层	版本	能力	对应用的意义
Audio Vivid（菁彩三维声）	API 12 起	系统解码 + 空间渲染，AVPlayer 播放带元数据音源无感接入	播对音源格式即有效果
AudioSpatializationManager	API 18 起	查询开关状态 + 订阅变化事件；设备描述符 spatializationSupported 字段	本文的主战场：感知与降级
空间渲染效果节点	API 23+	左手坐标系自由摆声源	本文不展开（注意核对发布状态再引用）

3.2 公开 API 的边界：为什么教程复现不了

边界的事值得再讲透一点。第 1 章的 grep 已经证明 set 系列不在三方 SDK 里，而它们的真正归宿是系统设置——但这个入口在哪，本身就是个坑：我的第一反应是去「设置→声音和振动」里找，翻遍了没有；又问 AI“华为的空间音频设置在哪”，得到的答案也没指向正确位置；最后是自己去蓝牙的耳机详情页里翻，才在「高清空间音频」那一栏找到了开关（关闭/固定/头部跟踪三态）。也就是说 HarmonyOS 7 把空间音频开关和耳机绑定在一起，而不是放在全局声音设置里——做引导文案时直接把路径告诉用户，能省他们不少事。另外多说一句：这条“set 是系统 API”的边界，Flutter 侧的同学也独立踩到了（他那篇文章的坑三），两边互相印证，可以放心当结论记。

3.3 三方应用的正确姿势：感知、引导、降级

降级矩阵（本文全部真机实测）：

输出设备	设备能力	空间化效果	UI 呈现（实测）
外放（SPEAKER）	不支持	立体声	徽标灰色"立体声"
FreeLace Pro 2（普通蓝牙）	不支持	立体声	能力行红字"不支持"
FreeClip 2 / FreeBuds Pro 5	支持	固定/头部跟踪	能力行绿字"支持"，开关状态实时刷新

表格里的红绿不是 App 自己判断的：能力那一行来自系统设备描述符上的 spatializationSupported 字段（API 18+），插上什么耳机系统就给什么答案；“当前状态”那一行实时跟随系统开关，事件一推就刷新；不支持的设备，引导去系统设置的文案自动出现——三行各司其职，App 只负责如实呈现。

3.4 RNOH 的桥接链路：五个环节缺一不可

对照上面这张工程目录图，调用链路是五段：JS 侧用 TS 写 TurboModule spec（类型即契约）；codegen-harmony 扫描 spec 生成 C++ 胶水（RNOHGeneratedPackage 和模块壳）；宿主的 PackageProvider.cpp 把生成的 Package 注册进 C++ 运行时；ArkTS 侧的 Package 通过 getUITurboModuleFactoryByNameMap 提供真正的实现；最后 JSI 直通到 JS。五段里最容易被忽略的是第三段——C++ 侧必须先"认识"模块名才会把调用转发到 ArkTS，这是 0.84 的硬要求，也是踩坑第 12 条的根源。

顺带交代一句路线选择：另一条路是在应用内自己算 HRTF 做双耳渲染（好处是不挑设备、任何耳机都有方位感）。本文走的是系统能力路线——省算力、与系统播放器体验一致，两条路互补不冲突。选哪条取决于你的产品更在乎覆盖面还是一致性，本文的库不锁死这条路，感知和降级的能力两条路线都用得上。

4. 核心实现

4.1 库与工程总览

react-native-ohos-spatial-audio/
├── src/
│   ├── index.ts                    # JS 公共 API：SpatialAudio + 事件订阅
│   ├── NativeSpatialAudio.ts       # TurboModule spec（codegen 输入）
│   └── hooks/useSpatialAudio.ts    # React Hook 状态机
├── harmony/spatial_audio/          # ArkTS HAR 模块（源码方式参与宿主编译）
│   └── src/main/ets/
│       ├── SpatialAudioPackage.ets # Package 注册（0.84 新 API）
│       └── SpatialAudioModule.ets  # Audio Kit / Media Kit 实现
└── example/                        # 演示工程（壳工程搭建见 README）

库和 demo 是两层职责：库（react-native-ohos-spatial-audio）只做能力封装，不带任何 UI；example 是消费方，负责演示怎么把能力变成界面。

4.2 JS 侧 spec：类型即契约

// src/NativeSpatialAudio.ts（节选，完整见仓库）
export interface SpatialAudioCapability {
  managerAvailable: boolean;              // API 18+ 且 syscap 支持
  spatializationEnabledForCurrentDevice: boolean; // 跟随系统开关实时变化
  device: {
    name: string; type: string;
    spatializationSupported?: boolean;    // 设备描述符字段（API 18+，低版本 undefined）
  };
  anyDeviceSupportsSpatialization: boolean; // 整机能力代理判断
}

export interface Spec extends TurboModule {
  detect(): Promise<SpatialAudioCapability>;  // 一次调用拿全能力快照
  play(uri: string): Promise<void>;           // http(s):// 或 rawfile:///xxx
  pause(): Promise<void>;
  stop(): Promise<void>;
  addListener(eventName: string): Promise<void>;    // NativeEventEmitter 约定
  removeListeners(count: number): Promise<void>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('SpatialAudio');

两个设计取舍说一下：detect() 做成一次性快照，是为了一次跨端往返就把全部能力拿回来，避免 JS 侧为了拼齐状态连续调三次原生；播放源的 uri 统一支持 http(s)😕/ 和 rawfile:/// 两种前缀，网络音源和工程内置音源走同一个入口，调用方不用分支。

4.3 ArkTS 探测：一次调用拿全能力

// SpatialAudioModule.ets（节选）
private pickDevice(): audio.AudioDeviceDescriptor | null {
  // 遍历当前输出设备，优先取声明支持空间化的
  const devices = this.routingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG);
  if (!devices || devices.length === 0) { return null; }
  return devices.find(d => d.spatializationSupported === true) ?? devices[0];
}

private buildCapabilitySync(): SpatialAudioCapability {
  return {
    managerAvailable: this.spatializationManager !== null, // 低版本设备兜底
    spatializationEnabledForCurrentDevice:
      this.spatializationManager?.isSpatializationEnabledForCurrentDevice() ?? false,
    device: /* pickDevice() 转换，字段原样透传（可能 undefined） */,
    anyDeviceSupportsSpatialization: devices.some(d => d.spatializationSupported === true),
  };
}

两个实测细节值得记：spatializationSupported 字段在低版本设备上是 undefined 而不是 false，所以原样透传、让 JS 侧按三态处理（支持/不支持/未知），别在 ArkTS 侧强转 boolean；isSpatializationEnabledForCurrentDevice() 是同步接口，意味着任何事件回调里都能即时重算能力快照，这是"事件驱动更新"能做快的基础。

4.4 事件桥：三类事件一条通道

// SpatialAudioModule.ets（节选）——构造时订阅，与 RN 实例同生命周期
this.spatializationManager.on(
  'spatializationEnabledChangeForCurrentDevice',   // 注意：事件名含 Change
  (enabled: boolean) => this.emit({ kind: 'capabilityChanged', ... })
);
this.routingManager.on(
  'deviceChange',
  audio.DeviceFlag.OUTPUT_DEVICES_FLAG,            // 三参数签名
  (action: audio.DeviceChangeAction) =>           // 回调收单个对象 {type, deviceDescriptors}
    this.emit({ kind: 'capabilityChanged', ... })
);
// 播放状态随 AVPlayer stateChange 转发（见 4.5），含打断原因

private emit(payload: SpatialAudioEventPayload) {
  this.ctx.rnInstance.emitDeviceEvent('spatialAudioEvent', payload); // 单通道
}

事件桥的设计是"三类事件、一条通道"：空间化开关变化、设备插拔、播放状态，全部从 emitDeviceEvent 的同一个事件名出去，负载里用 kind 字段区分——JS 侧注册一个 listener 就够了，比三个事件名各自订阅省心，也少了三倍忘记解绑的机会。两个真机验证过的事实必须强调：事件名是 spatializationEnabledChangeForCurrentDevice，中间的 Change 一词网上资料经常少写；deviceChange 的订阅是三参数签名、回调收单个 DeviceChangeAction 对象——写成两参数的话编译期不报错，运行期就是收不到回调，这种"静默失败"最难排查。

4.5 播放封装：AVPlayer 状态机的正确姿势

// play() 核心状态机（节选）
player.on('stateChange',
  async (state: media.AVPlayerState, reason: media.StateChangeReason) => {  // 两参数！
    this.emit({ kind: 'playbackState', playback: { state: state, reason: reason } });
    switch (state) {
      case 'initialized': await player.prepare(); break;  // url/fdSrc 设置后推进
      case 'prepared':    await player.play();   break;
      case 'error':       reject(new Error('AVPlayer error')); break;
    }
  });
// 本地音源：getRawFdSync 拿文件描述符（API 26 里 getRawFd 已是 Promise 版）
const fd = ctx.resourceManager.getRawFdSync(name);
player.fdSrc = { fd: fd.fd, offset: fd.offset, length: fd.length };

音频焦点在这条路线里反而是"顺带解决"的：AVPlayer 场景下焦点由系统托管（AudioManager 的 on(‘audioInterrupt’) 已废弃，别再走那条路），被打断的表现就是 stateChange 跳到 paused、reason 等于 BACKGROUND(2)。所以库把播放状态原样转发给 JS，焦点观察就免费附送了——真机实测：播放环绕 5.1 时按 Home 键切到桌面，回来看日志，08:34:47 playing（reason=1）之后紧接一条 08:34:54 paused（reason=2），系统打断的瞬间被事件桥原样捕获：

顺带一提，这张截图还完整记录了一次 AVPlayer 的状态机流转（idle → initialized → prepared → playing → paused），和上面代码里的 switch 分支一一对应，拿来做状态机教学的配图都够格。

4.6 注册三部曲：RNOH 0.84 的正确打开方式（重点）

第一步：ArkTS Package 用新 API 注册

// SpatialAudioPackage.ets——0.84 注册方式
export class SpatialAudioPackage extends RNPackage {
  getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
    const map = new Map<string, (ctx: UITurboModuleContext) => UITurboModule>();
    map.set('SpatialAudio', (ctx: UITurboModuleContext) => new SpatialAudioModule(ctx));
    return map;
  }
}

注意：官方 0.72 时代文档教的 createTurboModulesFactory(ctx) 自 0.72.38 起废弃，0.84 运行时已不再调用——只重写它的话模块不会被发现（真机报错见踩坑第 12 条）。

第二步：codegen 生成 C++ 胶水

cd example
npx react-native codegen-harmony --ets-output-path ./harmony/entry/src/main/ets/generated
# 产物：cpp/generated/{RNOHGeneratedPackage.h, SpatialAudio.h/.cpp}
#      拷入壳工程 entry/src/main/cpp/generated/

第三步：宿主 C++ 侧注册生成的 Package

// 壳工程 entry/src/main/cpp/PackageProvider.cpp
#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
using namespace rnoh;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return { std::make_shared<RNOHGeneratedPackage>(ctx) };  // C++ 从此认识 'SpatialAudio'
}

这个坑折磨了我整整一个晚上。现在回头看，当时的注册写法照的是官方 0.72 时代的文档：ArkTS 侧 Package 重写 createTurboModulesFactory 返回工厂——后来才知道 0.84 里这个方法已经废弃，运行时根本不调用。换成新 API（getUITurboModuleFactoryByNameMap）之后更诡异：hilog 里能清楚看到 TM created: SpatialAudio，ArkTS 侧明明创建成功了，JS 侧还是红屏报 Couldn’t find Turbo Module on the ArkTs side。最后是借助 AI 工具把 har 里的 C++ 源码翻了个底朝天，才定位到 TurboModuleFactory 的查找逻辑：C++ 侧必须先"认识"这个模块名（通过 codegen 生成的 C++ Package 注册），否则不会把请求转发给 ArkTS。所以正确的注册是三步：ArkTS 新 API、codegen 生成 C++ 胶水、PackageProvider.cpp 注册，一步都不能少。这是 0.8x 与老文档差异最大的地方，也是我认为网上 RNOH TurboModule 资料里最缺的一块。

4.7 React Hook：给业务同学的好用接口

// useSpatialAudio（节选）：挂载探测一次 + 事件驱动更新 + 跨平台安全空态
useEffect(() => {
  refresh();                                    // 启动探测一次
  const off1 = SpatialAudio.on('capabilityChanged', ...);  // 事件驱动，不轮询
  const off2 = SpatialAudio.on('playbackState', ...);
  return () => { off1(); off2(); };             // 订阅与取消成对
}, []);
// 非 harmony 平台 capability 为 null，业务侧安全降级

状态之所以不用轮询，是因为它只会在用户改系统设置时变化——你轮询一千次它都纹丝不动，改一次事件立刻推过来。事件驱动又省电又实时，没有理由选轮询。对业务同学来说，这个 Hook 的接入成本基本为零：import 进来解构出 mode 和 capability，徽标的颜色、引导文案的显隐、能力行的红绿全部跟着状态走，一行原生代码都不用碰。

4.8 测试音源：为什么用自制 5.1

测试音源说两句实话：Audio Vivid 的正版素材是 UWA 联盟的会员资源，公开渠道拿不到，与其等素材不如换思路——多声道内容同样触发系统空间化，所以我用 30 行 Python 标准库合了一段 5.1"方位巡礼"：六个声道（前左、前右、中置、低音、后左、后右）依次各响两秒不同音高的纯音。给每个声道配不同音高是有讲究的——同样的音换个方位响，人耳容易"脑补"成位置错觉；不同音高加纯音的干净频谱，方位判断就没有歧义。纯音的方位感比音乐容易辨认得多，做演示和听感对比反而更合适，还零版权。生成脚本在仓库里（example/tools/make_surround_test.py），一条命令可复现。

5. 踩坑实录：12 个，全部有报错原文

下面这 12 个坑全部来自这次开发的真实报错，按环境、工程、API 分三组，每条都是"报错原文 → 根因 → 教训"的格式，方便对号入座。开发过程中我养成了一个习惯：每踩一个坑就立刻把报错原文、当时的排查动作和最终解法记进仓库的证据目录，这份清单就是从里面直接整理出来的——事后看，这个习惯救了我好几次，因为有好几个坑的表象和根因隔着好几层，不记下来第二天自己都想不起来当时是怎么定位的。

环境组（Windows）

坑 1｜react 版本对不上

npm error ERESOLVE unable to resolve dependency tree
npm error Could not resolve dependency: peer react@"^19.2.3" from react-native@0.84.1

根因：RN 0.84.1 的 peer 要求 react ^19.2.3，我写成了 19.1.0。教训：三件套版本以 RNOH 官方工程模板为准，别手猜。

坑 2｜本地库 symlink 让 Metro 断链
file:.. 本地依赖默认装成符号链接，Metro 从库源目录向上解析 react-native 时断链，报 Unable to resolve module。解法：npm install --install-links=true 拷贝式安装（库代码改动后需重跑同步）。

坑 3｜Metro 的 8081 被 Windows 拿走了

error listen EACCES: permission denied 0.0.0.0:8081

netsh interface ipv4 show excludedportrange protocol=tcp 一查，8024–8223 整段被 Hyper-V 保留了。解法（管理员）：net stop winnat → 起 Metro 占住 8081 → net start winnat。

坑 4｜java 明明有，hvigor 却说没有

hvigor ERROR: Failed :entry:default@PackageHap... spawn java ENOENT

PATH 里 java 可用但打包仍报错——是 hvigor 复用了旧环境里起的 worker 进程。解法：杀掉命令行含 hvigor 的 node 进程后重新构建。

坑 5｜构建显示成功，产物目录是空的
hvigor 增量缓存误判 UP-TO-DATE（删过 build 目录后）。解法：删 .hvigor 全量重建，别信"BUILD SUCCESSFUL"四个字，看产物时间戳。

工程组（鸿蒙侧）

坑 6｜useNormalizedOHMUrl 与源码 HAR 冲突

ERROR: Cannot import files from an external module using relative paths.

DevEco 26 新建工程默认 useNormalizedOHMUrl: true，而 RNOH 三方库都是源码 HAR + 内部相对导入。解法：工程根 build-profile 的 strictMode 里改 false。

坑 7｜源码 HAR 没注册成模块，编译器直接崩

Error: Cannot read properties of undefined (reading 'split')

表象极其诡异（ets-loader 内部崩溃），真因是库的源码目录没被 hvigor 当独立模块——被混进 entry 一起编译，内部相对导入"跨出模块"。解法：库目录补 build-profile.json5 + hvigorfile.ts（harTasks），并注册进壳工程根 build-profile 的 modules。

坑 8｜CMake 找不到 RNOH 的 C++ 源码

CMake Error: add_subdirectory given source ".../oh_modules/@rnoh/.../src/main/cpp" which is not an existing directory.

@rnoh 依赖挂在工程根时 ohpm 装在根目录，而官方 CMakeLists 模板从 entry 找。解法：依赖挂到 entry 的 oh-package（手动集成流程的标准位置）。

坑 9｜Package 构造缺参数

ERROR: Expected 1 arguments, but got 0.

new SpatialAudioPackage() 不行——RNPackage 构造需要 ctx：new SpatialAudioPackage(ctx)。

API 组（RNOH / 鸿蒙）

坑 10｜set 系列是系统 API（第 1 章详述，此处一句话回指：公开 SDK grep 零命中，教程复现不了的根源。）

坑 11｜getRawFd 变成了异步

ERROR: Property 'fd' does not exist on type 'Promise<RawFileDescriptor>'.

API 26 里 getRawFd 返回 Promise。解法：用同步版 getRawFdSync(name)。

坑 12｜只注册 ArkTS 侧，TurboModule 依然找不到（4.6 节详述的注册三部曲，此处回指 + 一句教训：C++ 侧不认识名字，ArkTS 写得再对也到不了。）

小坑合集（一句话各记一笔）：Hermes 不支持 toLocaleTimeString 带参（日志时间戳手写格式化）；外放的 DeviceType 枚举实测是 7 不是 1（按版本核对 d.ts）；蓝牙连接时 displayName 显示手机名而非耳机名（系统行为，UI 上注明即可）。

6. 结论与可直接复用的建议

最后交付清单：库（能力探测、事件桥、AVPlayer 播放封装、useSpatialAudio Hook）、可交互的 example、音源生成脚本、一份从环境搭建到真机运行的完整 README，全部开源在：https://atomgit.com/m0_37170006/react-native-ohos-spatial-audio

给要做同样事情的同学四条建议：

1. 探测做成"启动一次 + 事件驱动更新"，别轮询——状态只在系统设置变化时变，事件是唯一可靠且及时的来源。
2. 别对抗平台边界：开关权在系统手里就顺势而为，把用户引导到系统设置、App 侧实时感知，比一个永远点不动的开关体验好得多。demo 里的做法可以直接抄：能力卡片显示设备支不支持，引导文案直接写清系统设置的完整路径（设置→蓝牙→耳机详情页→高清空间音频），用户开完回来徽标自动变化——整个过程用户不需要理解任何概念。
3. 演示和验证用多声道音源就够（自制 5.1 即可），Audio Vivid 是锦上添花，别让它卡住你的进度。
4. RNOH 0.84 目前是 rc 线（0.84.4），环境表里如实标注——审稿人和接手的同事都会感谢这份诚实。

展望两句：更新的 API 里有自由摆声源的空间渲染节点，等它进入稳定版本，这个库可以往上长出"应用内定义声源位置"的能力；Audio Vivid 素材如果哪天对社区开放，加一个音源切换就能平滑升级。

环境信息与引用

项	版本/型号
DevEco Studio	26.0.0.851（HarmonyOS SDK 26.0.0 Release / API 26）
React Native	0.84.1（@react-native-oh/react-native-harmony 0.84.4，0.84-rc 线）
实测设备	HUAWEI Pura X View（VOL-AL00），HarmonyOS 7.0.0.111 SP10
实测耳机	FreeClip 2 / FreeBuds Pro 5（支持空间音频）；FreeLace Pro 2（不支持，降级验证）

引用：

• 华为开发者官网 Audio Kit 文档（空间音频管理）
• RNOH 主仓文档（gitee.com/openharmony-sig 及 AtomGit oh-react-native 组织 fork）
• HarmonyOS 7 空间音频实战（掘金）——注：其 set 类调用属系统应用 SDK，三方环境无法复现，本文第 3.2 节有实证
• 本文全部代码与素材：https://atomgit.com/m0_37170006/react-native-ohos-spatial-audio

g-TMHvsJhH-1794304750393)]

[外链图片转存中…(img-hIy2jDeI-1794304750393)]

引用：

• 华为开发者官网 Audio Kit 文档（空间音频管理）
• RNOH 主仓文档（gitee.com/openharmony-sig 及 AtomGit oh-react-native 组织 fork）
• HarmonyOS 7 空间音频实战（掘金）——注：其 set 类调用属系统应用 SDK，三方环境无法复现，本文第 3.2 节有实证
• 本文全部代码与素材：https://atomgit.com/m0_37170006/react-native-ohos-spatial-audio