HarmonyOS ImageReceiver 图像管线实战：Surface 接入、容量控制与及时释放

相机预览能正常显示，并不代表应用已经能稳定拿到每一帧。很多二次处理功能在运行几十秒后开始掉帧：第一次回调里读到 Image，算法耗时稍长，下一批帧继续堆进队列；旧帧没有释放，生产者很快被背压阻塞，页面看起来像“相机突然不再回调”。如果此时反复重建 Session，只会把真正的资源泄漏藏得更深。

ImageReceiver 的核心不是“把 Surface ID 传给相机”这一行代码，而是建立一个有容量、取帧策略和释放纪律的生产者/消费者通道。本文围绕预览帧二次处理，讲清楚 readLatestImage() 与 readNextImage() 的选择、回调串行化、行步长处理、页面退出顺序和队列观测方法。

1. ImageReceiver 位于哪一段数据链路

图像生产者可以是 Camera Kit 的预览输出，也可以是其他能够向 Surface 写入图像的组件。ImageReceiver 提供接收 Surface，并把到达的图像交给业务消费者。它不替业务保存所有帧，也不会自动释放已经读出的 Image。

export interface FrameSnapshot {
  sequence: number;
  width: number;
  height: number;
  rowStride: number;
  receivedAt: number;
}

export type FramePolicy = 'latest' | 'ordered';

实时识别通常关心最新画面，适合 latest；逐帧编码或严格时序分析才考虑 ordered。先定义业务语义，再选择读取接口，不能看到两个 API 就随意替换。

2. 版本基线与设备约束

本文以 Stage 模型、ArkTS、HarmonyOS SDK API 23 声明为基线，导入 @kit.ImageKit。ImageReceiver、getReceivingSurfaceId()、readLatestImage()、readNextImage() 和 release() 从 API 9 起提供，off('imageArrival') 从 API 13 起提供。

项目	本文选择	原因
接口层	ArkTS ImageReceiver	页面与 Camera ArkTS 链路易于集成
示例格式	ImageFormat.JPEG	便于说明接收、消费与释放
队列容量	4	给短时抖动留余量，又不囤积过多帧
读取策略	readLatestImage()	实时预览分析优先新鲜度
运行环境	真机	Image Kit 部分能力不支持模拟器

具体相机输出格式、分辨率与旋转能力要从 Camera Kit 会话配置取得。本文不假设任意 Surface 都能接收任意格式。

3. 创建 Receiver 时把尺寸、格式和容量一次定清

createImageReceiver(size, format, capacity) 返回接收器。尺寸必须与生产者输出匹配，容量不是无限缓存，而是“允许多少张尚未归还的图像同时存在”的边界。

import { image } from '@kit.ImageKit';

export interface ReceiverHandle {
  receiver: image.ImageReceiver;
  surfaceId: string;
}

export async function createPreviewReceiver(
  width: number,
  height: number,
  capacity: number = 4
): Promise<ReceiverHandle> {
  if (width <= 0 || height <= 0) throw new Error('invalid receiver size');
  if (capacity < 2 || capacity > 8) throw new Error('capacity out of project range');

  const receiver = image.createImageReceiver(
    { width, height },
    image.ImageFormat.JPEG,
    capacity
  );
  const surfaceId = await receiver.getReceivingSurfaceId();
  return { receiver, surfaceId };
}

这里的 2..8 是项目策略，不是平台通用限制。真实上限应结合分辨率、单帧字节数与处理时延测量。4K 图像即使只多保留几张，也可能造成明显内存压力。

4. Surface 接入之后才启动生产者

顺序应保持稳定：先创建 Receiver 并注册回调，再取得 Surface ID，随后用这个 ID 创建生产者输出并提交会话。若先启动相机再补回调，最早到达的帧可能无人消费；若页面退出时先销毁 Receiver、后停止生产者，生产者仍可能向失效 Surface 写入。

export interface PreviewProducer {
  attachSurface(surfaceId: string): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
  detachSurface(): Promise<void>;
}

async function startPipeline(
  producer: PreviewProducer,
  handle: ReceiverHandle,
  consumer: FrameConsumer
): Promise<void> {
  consumer.bind(handle.receiver);
  await producer.attachSurface(handle.surfaceId);
  await producer.start();
}

Camera Kit 项目中，attachSurface() 通常对应使用 Surface ID 创建第二路预览输出，再在 Session 配置阶段加入该输出。不要把 XComponent 展示 Surface 与帧分析 Surface 混为一个无边界对象。

5. imageArrival 回调只做“尽快取走一张”

回调被触发时，重型识别、网络请求和文件写入都不应直接堆在回调栈里。先读出最新帧，再把受控数据交给处理器；无论处理成功还是失败，都释放 Image。

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

export class FrameConsumer {
  private receiver?: image.ImageReceiver;
  private busy: boolean = false;
  private stopped: boolean = false;

  private readonly arrival = async (error?: BusinessError): Promise<void> => {
    if (error !== undefined || this.stopped || this.busy || this.receiver === undefined) return;
    this.busy = true;
    let frame: image.Image | undefined;
    try {
      frame = await this.receiver.readLatestImage();
      await this.consume(frame);
    } catch (reason) {
      console.error(`consume frame failed: ${JSON.stringify(reason)}`);
    } finally {
      if (frame !== undefined) await frame.release();
      this.busy = false;
    }
  };

  bind(receiver: image.ImageReceiver): void {
    this.receiver = receiver;
    receiver.on('imageArrival', this.arrival);
  }

  private async consume(frame: image.Image): Promise<void> {
    console.info(`frame=${frame.size.width}x${frame.size.height}`);
  }
}

busy 把消费者限制为单任务，避免多个异步回调并发读取同一队列。实时场景宁可跳过中间通知，也不要同时积累多个算法任务。

6. readLatestImage 与 readNextImage 的取舍

两个接口的差别直接决定延迟模型：

接口	读取语义	适合场景	主要风险
readLatestImage()	取当前最新图像，旧积压可被跳过	实时扫码、姿态提示、取景分析	不保证逐帧处理
readNextImage()	按队列顺序取下一张	帧序列导出、顺序编码	消费慢时延迟持续增长

async function takeFrame(
  receiver: image.ImageReceiver,
  policy: FramePolicy
): Promise<image.Image> {
  if (policy === 'ordered') return receiver.readNextImage();
  return receiver.readLatestImage();
}

算法只需要每秒取少量样本时，latest 更符合用户看到的画面。必须保留每一帧的业务，应先确认处理吞吐不低于生产速率，并建立独立编码或持久化管线。

7. Image 的 release 不是可选清理

读出的 Image 占用队列中的底层缓冲。只有调用 release()，该槽位才能被后续图像复用。把释放放在“识别成功后”是不够的，任何异常、提前返回和取消分支都必须经过 finally。

import { image } from '@kit.ImageKit';

async function useOneFrame<T>(
  frame: image.Image,
  action: (value: image.Image) => Promise<T>
): Promise<T> {
  try {
    return await action(frame);
  } finally {
    await frame.release();
  }
}

同一张 Image 不要释放两次，也不要在释放后继续访问 size、getComponent() 或缓冲。最简单的所有权规则是：谁从 Receiver 读出，谁负责释放。

8. 读取分量时必须尊重 rowStride

YUV 或其他平面图像的一行缓冲长度可能大于可见宽度，这通常来自内存对齐。若算法直接按 width * height 连续切片，容易出现斜纹、错行或花屏。应读取 Component.rowStride，逐行复制有效区域。

import { image } from '@kit.ImageKit';

async function describeLuma(frame: image.Image): Promise<FrameSnapshot> {
  const y = await frame.getComponent(image.ComponentType.YUV_Y);
  return {
    sequence: 0,
    width: frame.size.width,
    height: frame.size.height,
    rowStride: y.rowStride,
    receivedAt: Date.now()
  };
}

不同格式能否读取某一分量要以接口和实际输出为准。处理前还要核对 pixelStride、旋转角度和前置镜头镜像需求，不能只按二维宽高解释底层缓冲。

9. 队列容量要用吞吐量而不是感觉估计

假设生产者 30 fps，每帧间隔约 33 ms；算法平均 90 ms 才完成一次，即使容量从 4 提到 12，也只是把故障从“立即阻塞”变成“稍后积压”。根因是消费吞吐不足。

export class FrameLoadMeter {
  private arrivals: number = 0;
  private consumed: number = 0;
  private totalCostMs: number = 0;

  markArrival(): void { this.arrivals += 1; }

  markConsumed(costMs: number): void {
    this.consumed += 1;
    this.totalCostMs += costMs;
  }

  snapshot(): string {
    const avg = this.consumed === 0 ? 0 : this.totalCostMs / this.consumed;
    return `arrivals=${this.arrivals}, consumed=${this.consumed}, avgMs=${avg.toFixed(1)}`;
  }
}

实时分析可以降低采样频率、缩小分辨率、减少算法工作或只取最新帧。容量只承担短时抖动，不承担长期速率差。

10. 责任边界决定谁能关闭管线

生产者只知道 Surface；Receiver 管理有界图像队列；消费者拥有读出的单张 Image；页面协调启动与停止，但不直接操作图像缓冲。把这些职责拆开后，关闭顺序才能在一个协调器里完成。

export class PreviewPipeline {
  constructor(
    private readonly producer: PreviewProducer,
    private readonly receiver: image.ImageReceiver,
    private readonly consumer: FrameConsumer
  ) {}

  async close(): Promise<void> {
    await this.producer.stop();
    await this.producer.detachSurface();
    await this.consumer.stop();
    await this.receiver.release();
  }
}

先停生产者可阻止新帧进入；再移除输出和回调；等在途消费结束后释放 Receiver。consumer.stop() 的实现需要关闭新任务并等待当前任务收尾。

11. stop 必须等待在途图像归还

如果关闭时 busy=true，立即释放 Receiver 可能和正在进行的 readLatestImage() 交叉。消费者应停止接收新通知，并等待当前帧的 finally 完成。

async stop(): Promise<void> {
  this.stopped = true;
  if (this.receiver !== undefined) {
    this.receiver.off('imageArrival', this.arrival);
  }
  while (this.busy) {
    await new Promise<void>((resolve) => setTimeout(resolve, 10));
  }
  this.receiver = undefined;
}

轮询只用于说明关闭语义；生产项目可用 Promise 信号实现更明确的等待。关键是不要让页面销毁、回调取帧和 Receiver 释放同时竞争。

12. 旋转、镜像与裁剪属于图像解释层

相机传感器方向、设备屏幕旋转和前置镜头镜像共同决定最终画面。Receiver 只交付原始图像，不知道业务希望如何展示。推荐从 Camera Kit 的预览输出获取旋转信息，再由图像解释层统一转换。

export interface FrameTransform {
  rotation: 0 | 90 | 180 | 270;
  mirrorHorizontal: boolean;
  cropToVisibleWidth: boolean;
}

function shouldCrop(width: number, rowStride: number): boolean {
  return rowStride > width;
}

图像算法若需要原始坐标，应在变换前保存坐标映射。UI 上看起来方向正确，不代表算法输入的坐标系也正确。

13. 故障现象要按队列方向排查

现象	先查什么	修正动作
数秒后不再回调	每张 Image 是否都释放	把释放移入 finally
画面越来越滞后	是否误用 readNextImage()	实时业务改取最新帧
图像出现斜纹	rowStride 是否大于宽度	按行复制有效数据
退出页面偶发崩溃	释放顺序是否与回调竞争	先停生产者，再等消费结束
内存随时长上涨	容量、图像与算法中间结果	限制中间对象并记录峰值
前置画面方向错误	旋转与镜像是否分别处理	使用预览旋转信息并做水平镜像

从生产者到队列再到消费者逐段查，比反复重建相机会话更容易找到根因。

14. 真机压测关注新鲜度、回落与关闭

场景：30 fps 预览持续运行 10 分钟
观察：回调持续；消费耗时稳定；内存进入平台后不继续爬升

场景：让算法故意睡眠 150 ms
观察：latest 策略保持画面新鲜；队列不会无限增长

场景：连续进入退出页面 50 次
观察：每次都按顺序关闭；没有旧回调访问新页面

场景：前后摄像头切换并旋转设备
观察：尺寸、旋转、镜像与坐标映射同步更新

日志至少记录 arrivals、consumed、平均处理耗时和关闭次数。不要逐帧打印大块缓冲内容，日志本身也可能拖慢消费。

15. 接入验收清单与官方资料

[ ] Receiver 尺寸和格式与生产者输出一致
[ ] capacity 依据单帧内存与处理时延设定
[ ] 回调先取帧，不执行长网络或文件操作
[ ] 实时业务使用 readLatestImage，顺序业务才用 readNextImage
[ ] 每张 Image 在 finally 中释放且只释放一次
[ ] 分量解析尊重 rowStride、pixelStride 和方向信息
[ ] 关闭时先停生产者，再移除回调并等待在途任务
[ ] Receiver 最后释放，释放后不再访问 Surface ID
[ ] 真机覆盖慢算法、页面反复进出和设备旋转

资料来源：

• 华为开发者文档：相机预览帧数据获取
• 华为开发者文档：Image Kit 简介
• 本机 D:/harmonyos/SDK/23/ets/api/@ohos.multimedia.image.d.ts，用于核对 ImageReceiver、Image 与 Component 的 API 23 声明。

稳定图像管线的判断标准不是“能收到第一帧”，而是生产者持续写入、消费者按业务语义取帧、队列始终有界、每张图像都能归还，并且页面退出时没有并发访问。把 Image 当成必须显式归还的缓冲槽，而不是普通 ArkTS 对象，绝大多数运行一段时间后卡死的问题都会在设计阶段被挡住。