先看问题为什么会发生

这篇只抓一个点：空间音频能力兜底。我不按概念顺序铺开，而是按项目里最容易出问题的路径来拆：先复现坏写法，再补上边界判断，最后用日志和状态验证结果。

空间音频的坑不在播放，而在不同耳机、不同输出设备之间能力不一致。入口不判断，体验就会忽好忽坏。

这里按 HarmonyOS 7.0 / API 26 的能力边界来写。重点不是把 API 名称堆出来，而是把版本、设备状态、窗口形态、失败回退和日志证据放到同一套检查里。这样以后排查问题时，不需要靠猜页面为什么变了。

版本边界和适用场景

我会先把版本边界写进一层适配代码，而不是把判断散在页面里。页面变化很快，能力边界更应该稳定。入口层先判断清楚，后面的页面、组件、服务只接收明确结果，日志也更集中。

案例一：先复现一个会出问题的写法

下面这个例子故意保留常见问题：入口直接执行，异步结果没有版本号保护，窗口变化或用户重复触发时，旧结果可能覆盖新结果。

type GuardInput = {
  apiLevel: number
  deviceReady: boolean
  windowStable: boolean
  payload: string
}

type GuardResult = {
  ok: boolean
  mode: 'full' | 'fallback' | 'blocked'
  reason: string
}

class UnsafeRunner {
  async run(input: GuardInput): Promise<GuardResult> {
    await new Promise<void>((resolve) => setTimeout(resolve, 160))

    if (input.apiLevel < 26) {
      return { ok: false, mode: 'fallback', reason: 'api level below 26' }
    }
    if (!input.deviceReady) {
      return { ok: false, mode: 'blocked', reason: 'device is not ready' }
    }
    return { ok: true, mode: 'full', reason: 'accepted' }
  }
}

这个版本的问题是，它只在执行时判断一次。页面如果发生分屏、拖拽、横竖屏切换、设备能力变化、低电量降级或者用户连续触发，旧任务仍然可能回来写状态。开发环境里可能看不出来，到真机和复杂窗口里就会变成偶发问题。

案例二：把入口判断和结果保护补上

更稳的写法是：每次触发都生成一个请求版本号；返回结果时先判断自己是不是最新任务；再根据 API 级别、设备能力和窗口稳定性决定走完整能力还是回退路径。

class FeatureGuard {
  private latestVersion = 0

  async run(input: GuardInput): Promise<GuardResult> {
    const version = ++this.latestVersion
    const prepared = this.prepare(input)

    if (prepared.mode !== 'full') {
      return prepared
    }

    await new Promise<void>((resolve) => setTimeout(resolve, 160))

    if (version !== this.latestVersion) {
      return { ok: false, mode: 'blocked', reason: 'stale result ignored' }
    }

    return { ok: true, mode: 'full', reason: 'finished by current request' }
  }

  private prepare(input: GuardInput): GuardResult {
    if (input.apiLevel < 26) {
      return { ok: false, mode: 'fallback', reason: 'HarmonyOS API level below 26' }
    }
    if (!input.deviceReady) {
      return { ok: false, mode: 'blocked', reason: 'capability is not ready' }
    }
    if (!input.windowStable) {
      return { ok: false, mode: 'fallback', reason: 'window state is changing' }
    }
    if (!input.payload.trim()) {
      return { ok: false, mode: 'blocked', reason: 'payload is empty' }
    }
    return { ok: true, mode: 'full', reason: 'guard passed' }
  }
}

这段代码的价值不在于复杂，而在于把问题收口了：入口负责判断，执行负责完成，返回负责防旧结果。以后换成 空间音频能力兜底 的真实能力调用时，也可以沿用同一套结构。

两种方案对比

我会选第三种。HarmonyOS 7.0 / API 26 的新能力越来越多，真正影响项目稳定性的不是“能不能调一次”，而是各种状态变化下能不能知道自己为什么走完整能力、为什么回退、为什么拒绝执行。

验证方式

验证不要只看页面有没有打开。建议至少压下面五个点：

• API level 低于 26 时，必须走 fallback，不允许继续完整能力路径。
• deviceReady 为 false 时，必须给出 blocked 和明确 reason。
• windowStable 为 false 时，必须走 fallback，避免拖拽或分屏中反复刷新。
• 连续触发两次时，旧请求返回不能覆盖新请求。
• 日志里必须能看到 mode、reason、requestId，便于回查。

可以加一个很轻的日志封装：

function buildFeatureLog(name: string, input: GuardInput, result: GuardResult): string {
  return [
    'feature=' + name,
    'api=' + input.apiLevel,
    'mode=' + result.mode,
    'reason=' + result.reason,
  ].join(' | ')
}

期望日志类似这样：

feature=api26-spatial-audio-fallback | api=26 | mode=fallback | reason=window state is changing

可以怎么封装复用

如果项目里多个页面都要接入类似能力，可以把判断做成一个小模块：

export class Api26FeatureAdapter {
  constructor(private readonly featureName: string) {}

  check(input: GuardInput): GuardResult {
    if (input.apiLevel < 26) {
      return { ok: false, mode: 'fallback', reason: this.featureName + ': api level below 26' }
    }
    if (!input.deviceReady || !input.windowStable) {
      return { ok: false, mode: 'fallback', reason: this.featureName + ': runtime state is not stable' }
    }
    return { ok: true, mode: 'full', reason: this.featureName + ': ready' }
  }
}

页面只负责把当前状态传进来。这样后面要适配折叠屏、平板、鸿蒙电脑、多窗口或者低电量策略时，不需要把每个页面都翻一遍。

最后给一个检查清单

• 先确认 HarmonyOS 7.0 / API 26 的版本边界，再写调用。
• 至少准备两个场景：正常路径和回退路径。
• 每个回退都要有 reason，不能只返回 false。
• 异步结果要防旧请求覆盖新请求。
• 多窗口、弱网、低电量、设备能力不足，至少挑两个压测。
• 上架前把截图、权限说明、失败提示和降级表现一起检查。

如果你也遇到 空间音频能力兜底 相关问题，可以从日志里的 mode 和 reason 开始排，一般比直接翻 UI 代码快很多。