HarmonyOS开发中的媒体最佳实践：媒体架构设计、性能优化、内存管理、兼容性适配、媒体开发规范

核心要点：系统梳理 HarmonyOS 媒体开发的最佳实践体系，从架构设计到性能优化，从内存管理到兼容性适配，建立一套可落地的媒体开发规范，让你的媒体应用既快又稳。

一、背景与动机

做了这么多媒体开发，你一定遇到过这些问题：播放视频时内存占用越来越高、切换歌曲时有明显的卡顿、不同设备上表现不一致、代码越写越乱难以维护……

这些问题不是靠"多写几行代码"就能解决的，而是需要从架构层面、规范层面去系统性地应对。就像盖房子一样——如果地基没打好，上面盖得再漂亮也不牢固。媒体开发也是如此，好的架构设计和开发规范，是高质量媒体应用的基石。

这篇文章，我会把在 HarmonyOS 媒体开发中积累的最佳实践系统性地整理出来，涵盖架构设计、性能优化、内存管理、兼容性适配和开发规范五个维度。这些经验不是纸上谈兵，而是踩过无数坑之后总结出来的实战指南。

二、核心原理

2.1 媒体开发最佳实践体系

2.2 媒体架构设计原则

2.3 性能优化核心指标

三、代码实战

3.1 媒体架构设计：分层架构实现

一个好的媒体架构应该是分层的、解耦的、可测试的。下面展示一个完整的分层架构实现。

// MediaArchitecture.ets
// 媒体分层架构设计实现

import { media } from '@kit.MediaKit';
import { avSession } from '@kit.AvsessionKit';
import { BusinessError } from '@kit.BasicServicesKit';

// ======== 第一层：数据层（Data Layer） ========

// 媒体数据仓库
export class MediaRepository {
  // 获取媒体文件列表
  async getMediaList(type: 'audio' | 'video' | 'image'): Promise<MediaItem[]> {
    // 实际开发中从数据库或文件系统读取
    const mockData: MediaItem[] = [
      { id: '1', title: '歌曲1', artist: '艺术家1', uri: 'file:///music/song1.mp3', duration: 240000, type: 'audio' },
      { id: '2', title: '歌曲2', artist: '艺术家2', uri: 'file:///music/song2.mp3', duration: 180000, type: 'audio' },
      { id: '3', title: '视频1', artist: '', uri: 'file:///video/demo.mp4', duration: 3600000, type: 'video' }
    ];
    return mockData.filter(item => item.type === type);
  }

  // 获取媒体文件详情
  async getMediaDetail(id: string): Promise<MediaItem | null> {
    // 实际开发中从数据库读取
    return null;
  }

  // 保存播放记录
  async savePlayHistory(item: MediaItem, position: number) {
    // 持久化播放记录
    console.info(`[数据层] 保存播放记录: ${item.title}, 位置: ${position}ms`);
  }

  // 获取播放记录
  async getPlayHistory(id: string): Promise<number> {
    // 读取上次播放位置
    return 0;
  }
}

// 媒体数据模型
export interface MediaItem {
  id: string;
  title: string;
  artist: string;
  uri: string;
  duration: number;
  type: 'audio' | 'video' | 'image';
}

// ======== 第二层：业务层（Domain Layer） ========

// 播放状态
export enum PlayState {
  IDLE = 'idle',
  LOADING = 'loading',
  PLAYING = 'playing',
  PAUSED = 'paused',
  STOPPED = 'stopped',
  ERROR = 'error'
}

// 播放器状态
export interface PlayerState {
  playState: PlayState;
  currentItem: MediaItem | null;
  currentPosition: number;
  duration: number;
  speed: number;
  volume: number;
  errorMessage: string;
}

// 播放器业务管理器
export class PlayerManager {
  // 播放器实例
  private player: media.AVPlayer | null = null;
  // 数据仓库
  private repository: MediaRepository;
  // 当前状态
  private state: PlayerState = {
    playState: PlayState.IDLE,
    currentItem: null,
    currentPosition: 0,
    duration: 0,
    speed: 1.0,
    volume: 50,
    errorMessage: ''
  };
  // 状态监听器列表
  private listeners: Array<(state: PlayerState) => void> = [];
  // 播放列表
  private playlist: MediaItem[] = [];
  // 当前播放索引
  private currentIndex: number = -1;

  constructor(repository: MediaRepository) {
    this.repository = repository;
  }

  // 初始化播放器
  async init() {
    try {
      this.player = await media.createAVPlayer();

      // 状态变更回调
      this.player.on('stateChange', (state: string) => {
        this.handleStateChange(state);
      });

      // 进度回调
      this.player.on('timeUpdate', (time: number) => {
        this.state.currentPosition = time;
        this.notifyListeners();
      });

      // 错误回调
      this.player.on('error', (err: BusinessError) => {
        this.state.playState = PlayState.ERROR;
        this.state.errorMessage = `${err.code}: ${err.message}`;
        this.notifyListeners();
      });

      console.info('[业务层] 播放器初始化完成');
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[业务层] 播放器初始化失败: ${err.code} - ${err.message}`);
    }
  }

  // 加载播放列表
  async loadPlaylist(type: 'audio' | 'video' | 'image') {
    this.playlist = await this.repository.getMediaList(type);
    if (this.playlist.length > 0) {
      this.currentIndex = 0;
      await this.playAtIndex(0);
    }
  }

  // 播放指定索引
  async playAtIndex(index: number) {
    if (index < 0 || index >= this.playlist.length) return;

    const item = this.playlist[index];
    this.state.currentItem = item;
    this.state.playState = PlayState.LOADING;
    this.notifyListeners();

    try {
      // 恢复上次播放位置
      const lastPosition = await this.repository.getPlayHistory(item.id);
      this.player!.url = item.uri;
      // 如果有历史位置，跳转到上次位置
      if (lastPosition > 0) {
        setTimeout(() => {
          this.player?.seek(lastPosition);
        }, 500);
      }
      await this.player!.play();
      this.currentIndex = index;
    } catch (error) {
      const err = error as BusinessError;
      this.state.playState = PlayState.ERROR;
      this.state.errorMessage = err.message;
      this.notifyListeners();
    }
  }

  // 播放
  async play() {
    if (!this.player) return;
    try {
      await this.player.play();
    } catch (error) {
      this.handleError(error);
    }
  }

  // 暂停
  async pause() {
    if (!this.player) return;
    try {
      await this.player.pause();
      // 暂停时保存播放位置
      if (this.state.currentItem) {
        this.repository.savePlayHistory(this.state.currentItem, this.state.currentPosition);
      }
    } catch (error) {
      this.handleError(error);
    }
  }

  // 下一首
  async next() {
    if (this.currentIndex < this.playlist.length - 1) {
      await this.playAtIndex(this.currentIndex + 1);
    }
  }

  // 上一首
  async previous() {
    if (this.currentIndex > 0) {
      await this.playAtIndex(this.currentIndex - 1);
    }
  }

  // 跳转
  async seek(positionMs: number) {
    if (!this.player) return;
    try {
      await this.player.seek(positionMs);
    } catch (error) {
      this.handleError(error);
    }
  }

  // 设置速度
  async setSpeed(speed: number) {
    if (!this.player) return;
    try {
      await this.player.setSpeed(speed);
      this.state.speed = speed;
      this.notifyListeners();
    } catch (error) {
      this.handleError(error);
    }
  }

  // 释放资源
  async release() {
    // 保存当前播放位置
    if (this.state.currentItem) {
      this.repository.savePlayHistory(this.state.currentItem, this.state.currentPosition);
    }
    this.player?.release();
    this.player = null;
    this.state.playState = PlayState.IDLE;
    this.notifyListeners();
  }

  // 注册状态监听
  addListener(listener: (state: PlayerState) => void) {
    this.listeners.push(listener);
  }

  // 移除状态监听
  removeListener(listener: (state: PlayerState) => void) {
    this.listeners = this.listeners.filter(l => l !== listener);
  }

  // 获取当前状态
  getState(): PlayerState {
    return { ...this.state };
  }

  // 处理播放器状态变更
  private handleStateChange(state: string) {
    switch (state) {
      case 'playing':
        this.state.playState = PlayState.PLAYING;
        break;
      case 'paused':
        this.state.playState = PlayState.PAUSED;
        break;
      case 'stopped':
      case 'idle':
        this.state.playState = PlayState.STOPPED;
        break;
    }
    this.notifyListeners();
  }

  // 通知所有监听器
  private notifyListeners() {
    const currentState = this.getState();
    this.listeners.forEach(listener => {
      try {
        listener(currentState);
      } catch (error) {
        console.error('[业务层] 监听器回调异常');
      }
    });
  }

  // 统一错误处理
  private handleError(error: Error) {
    const err = error as BusinessError;
    this.state.playState = PlayState.ERROR;
    this.state.errorMessage = `${err.code}: ${err.message}`;
    this.notifyListeners();
    console.error(`[业务层] 播放错误: ${err.code} - ${err.message}`);
  }
}

// ======== 第三层：UI 层（Presentation Layer） ========

@Entry
@Component
struct MediaArchitecturePage {
  // 业务管理器
  private playerManager: PlayerManager = new PlayerManager(new MediaRepository());
  // 播放状态
  @State playState: PlayState = PlayState.IDLE;
  @State currentTitle: string = '未播放';
  @State currentArtist: string = '';
  @State currentPosition: number = 0;
  @State duration: number = 0;

  aboutToAppear() {
    // 初始化播放器
    this.playerManager.init();
    // 注册状态监听
    this.playerManager.addListener((state: PlayerState) => {
      this.playState = state.playState;
      this.currentTitle = state.currentItem?.title || '未播放';
      this.currentArtist = state.currentItem?.artist || '';
      this.currentPosition = state.currentPosition;
      this.duration = state.duration;
    });
  }

  aboutToDisappear() {
    this.playerManager.release();
  }

  build() {
    Column() {
      // 播放信息
      Column() {
        Text(this.currentTitle)
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
        Text(this.currentArtist)
          .fontSize(14)
          .fontColor('#999999')
          .margin({ top: 4 })
      }
      .margin({ bottom: 20 })

      // 进度条
      Row() {
        Text(this.formatTime(this.currentPosition))
          .fontSize(12)
          .fontColor('#999999')
        Slider({
          value: this.currentPosition,
          min: 0,
          max: this.duration || 1
        })
          .layoutWeight(1)
          .onChange((value: number) => {
            this.playerManager.seek(value);
          })
        Text(this.formatTime(this.duration))
          .fontSize(12)
          .fontColor('#999999')
      }
      .width('100%')
      .margin({ bottom: 20 })

      // 控制按钮
      Row() {
        Button('上一首')
          .onClick(() => this.playerManager.previous())
          .backgroundColor('#606266')
          .fontColor(Color.White)

        Button(this.playState === PlayState.PLAYING ? '暂停' : '播放')
          .onClick(() => {
            if (this.playState === PlayState.PLAYING) {
              this.playerManager.pause();
            } else {
              this.playerManager.play();
            }
          })
          .backgroundColor('#4A90D9')
          .fontColor(Color.White)
          .margin({ left: 12, right: 12 })

        Button('下一首')
          .onClick(() => this.playerManager.next())
          .backgroundColor('#606266')
          .fontColor(Color.White)
      }
      .margin({ bottom: 20 })

      // 加载播放列表
      Button('加载音乐列表')
        .width('100%')
        .height(44)
        .backgroundColor('#67C23A')
        .fontColor(Color.White)
        .onClick(() => this.playerManager.loadPlaylist('audio'))
    }
    .width('100%')
    .height('100%')
    .padding(16)
  }

  private formatTime(ms: number): string {
    const seconds = Math.floor(ms / 1000);
    const min = Math.floor(seconds / 60);
    const sec = seconds % 60;
    return `${min.toString().padStart(2, '0')}:${sec.toString().padStart(2, '0')}`;
  }
}

3.2 性能优化与内存管理

媒体应用是内存大户，性能优化和内存管理直接决定了用户体验。下面展示一套完整的优化方案。

// MediaPerformance.ets
// 媒体性能优化与内存管理

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

// ======== 性能优化工具类 ========

export class MediaPerformanceOptimizer {
  // 缓冲策略配置
  private bufferConfig: BufferConfig = {
    // 预缓冲时长（毫秒）
    preBufferDuration: 3000,
    // 最大缓冲时长
    maxBufferDuration: 30000,
    // 缓冲水位线（低）
    lowWaterMark: 1000,
    // 缓冲水位线（高）
    highWaterMark: 5000
  };

  // 配置播放器缓冲策略
  applyBufferStrategy(player: media.AVPlayer) {
    try {
      player.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => {
        switch (infoType) {
          case media.BufferingInfoType.BUFFERING_START:
            console.info('[性能优化] 开始缓冲');
            break;
          case media.BufferingInfoType.BUFFERING_END:
            console.info('[性能优化] 缓冲结束');
            break;
          case media.BufferingInfoType.BUFFERING_PERCENT:
            console.info(`[性能优化] 缓冲进度: ${value}%`);
            break;
          case media.BufferingInfoType.CACHED_DURATION:
            console.info(`[性能优化] 已缓存: ${value}ms`);
            // 根据缓存时长调整播放策略
            if (value < this.bufferConfig.lowWaterMark) {
              console.warn('[性能优化] 缓存不足，建议降低画质');
            }
            break;
        }
      });
    } catch (error) {
      console.error('[性能优化] 缓冲策略配置失败');
    }
  }

  // 获取缓冲配置
  getBufferConfig(): BufferConfig {
    return { ...this.bufferConfig };
  }

  // 根据网络状况动态调整缓冲策略
  adjustBufferForNetwork(networkType: string) {
    switch (networkType) {
      case 'wifi':
        this.bufferConfig.preBufferDuration = 3000;
        this.bufferConfig.maxBufferDuration = 30000;
        break;
      case 'cellular':
        this.bufferConfig.preBufferDuration = 5000;
        this.bufferConfig.maxBufferDuration = 60000;
        break;
      case 'none':
        this.bufferConfig.preBufferDuration = 0;
        this.bufferConfig.maxBufferDuration = 0;
        break;
    }
    console.info(`[性能优化] 缓冲策略已调整: ${networkType}`);
  }
}

// 缓冲策略配置
interface BufferConfig {
  preBufferDuration: number;
  maxBufferDuration: number;
  lowWaterMark: number;
  highWaterMark: number;
}

// ======== 内存管理工具类 ========

export class MediaMemoryManager {
  // 图片缓存（LRU）
  private imageCache: Map<string, image.PixelMap> = new Map();
  // 最大缓存数量
  private readonly MAX_CACHE_SIZE = 20;
  // 当前内存使用量（估算）
  private estimatedMemoryMB: number = 0;
  // 内存警告阈值
  private readonly MEMORY_WARNING_MB = 200;

  // 获取或创建图片（带缓存）
  async getOrCreateImage(key: string, creator: () => Promise<image.PixelMap>): Promise<image.PixelMap> {
    // 命中缓存
    if (this.imageCache.has(key)) {
      const cached = this.imageCache.get(key)!;
      // LRU：移到末尾
      this.imageCache.delete(key);
      this.imageCache.set(key, cached);
      return cached;
    }

    // 未命中，创建新的
    const pixelMap = await creator();

    // 检查缓存大小
    if (this.imageCache.size >= this.MAX_CACHE_SIZE) {
      // 淘汰最早的
      const firstKey = this.imageCache.keys().next().value;
      if (firstKey) {
        const oldImage = this.imageCache.get(firstKey);
        oldImage?.release();
        this.imageCache.delete(firstKey);
      }
    }

    this.imageCache.set(key, pixelMap);
    return pixelMap;
  }

  // 释放指定图片
  releaseImage(key: string) {
    const pixelMap = this.imageCache.get(key);
    if (pixelMap) {
      pixelMap.release();
      this.imageCache.delete(key);
    }
  }

  // 清空所有缓存
  clearAllCache() {
    this.imageCache.forEach((pixelMap) => {
      pixelMap.release();
    });
    this.imageCache.clear();
    this.estimatedMemoryMB = 0;
    console.info('[内存管理] 图片缓存已清空');
  }

  // 获取缓存大小
  getCacheSize(): number {
    return this.imageCache.size;
  }

  // 估算内存使用量
  estimateMemoryUsage(): number {
    return this.estimatedMemoryMB;
  }

  // 检查是否接近内存警告
  isMemoryWarning(): boolean {
    return this.estimatedMemoryMB >= this.MEMORY_WARNING_MB;
  }

  // 紧急释放内存
  emergencyRelease() {
    console.warn('[内存管理] 触发紧急内存释放');
    // 保留最近5张，释放其余
    const keys = Array.from(this.imageCache.keys());
    const keepCount = 5;
    for (let i = 0; i < keys.length - keepCount; i++) {
      this.releaseImage(keys[i]);
    }
  }
}

// ======== 性能监控 ========

export class MediaPerformanceMonitor {
  // FPS 计数
  private frameCount: number = 0;
  private lastFpsTime: number = Date.now();
  private currentFps: number = 0;
  // 卡顿检测
  private lastFrameTime: number = Date.now();
  private jankCount: number = 0;
  // 卡顿阈值（毫秒）
  private readonly JANK_THRESHOLD = 50;

  // 记录帧
  recordFrame() {
    const now = Date.now();
    this.frameCount++;

    // 检测卡顿
    const frameDelta = now - this.lastFrameTime;
    if (frameDelta > this.JANK_THRESHOLD) {
      this.jankCount++;
      console.warn(`[性能监控] 检测到卡顿: ${frameDelta}ms`);
    }
    this.lastFrameTime = now;

    // 每秒计算一次 FPS
    if (now - this.lastFpsTime >= 1000) {
      this.currentFps = this.frameCount;
      this.frameCount = 0;
      this.lastFpsTime = now;
    }
  }

  // 获取当前 FPS
  getFps(): number {
    return this.currentFps;
  }

  // 获取卡顿次数
  getJankCount(): number {
    return this.jankCount;
  }

  // 重置统计
  reset() {
    this.frameCount = 0;
    this.jankCount = 0;
    this.lastFpsTime = Date.now();
    this.lastFrameTime = Date.now();
  }

  // 生成性能报告
  getReport(): string {
    return `FPS: ${this.currentFps}, 卡顿次数: ${this.jankCount}`;
  }
}

// ======== UI 集成 ========

@Entry
@Component
struct MediaPerformancePage {
  private optimizer: MediaPerformanceOptimizer = new MediaPerformanceOptimizer();
  private memoryManager: MediaMemoryManager = new MediaMemoryManager();
  private monitor: MediaPerformanceMonitor = new MediaPerformanceMonitor();

  @State fpsValue: number = 0;
  @State jankCount: number = 0;
  @State cacheSize: number = 0;
  @State memoryWarning: boolean = false;

  // 定时刷新性能数据
  private refreshTimer: number = -1;

  aboutToAppear() {
    this.refreshTimer = setInterval(() => {
      this.fpsValue = this.monitor.getFps();
      this.jankCount = this.monitor.getJankCount();
      this.cacheSize = this.memoryManager.getCacheSize();
      this.memoryWarning = this.memoryManager.isMemoryWarning();
    }, 1000) as unknown as number;
  }

  aboutToDisappear() {
    if (this.refreshTimer !== -1) {
      clearInterval(this.refreshTimer);
    }
    this.memoryManager.clearAllCache();
  }

  build() {
    Scroll() {
      Column() {
        Text('媒体性能监控')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 16 })

        // 性能指标卡片
        Row() {
          // FPS
          Column() {
            Text(`${this.fpsValue}`)
              .fontSize(28)
              .fontWeight(FontWeight.Bold)
              .fontColor(this.fpsValue >= 30 ? '#67C23A' : '#F56C6C')
            Text('FPS')
              .fontSize(12)
              .fontColor('#999999')
              .margin({ top: 4 })
          }
          .layoutWeight(1)
          .padding(12)
          .borderRadius(8)
          .backgroundColor('#F5F7FA')

          // 卡顿
          Column() {
            Text(`${this.jankCount}`)
              .fontSize(28)
              .fontWeight(FontWeight.Bold)
              .fontColor(this.jankCount === 0 ? '#67C23A' : '#E6A23C')
            Text('卡顿次数')
              .fontSize(12)
              .fontColor('#999999')
              .margin({ top: 4 })
          }
          .layoutWeight(1)
          .padding(12)
          .borderRadius(8)
          .backgroundColor('#F5F7FA')
          .margin({ left: 8 })

          // 缓存
          Column() {
            Text(`${this.cacheSize}`)
              .fontSize(28)
              .fontWeight(FontWeight.Bold)
              .fontColor('#4A90D9')
            Text('缓存数')
              .fontSize(12)
              .fontColor('#999999')
              .margin({ top: 4 })
          }
          .layoutWeight(1)
          .padding(12)
          .borderRadius(8)
          .backgroundColor('#F5F7FA')
          .margin({ left: 8 })
        }
        .width('100%')
        .margin({ bottom: 16 })

        // 内存警告
        if (this.memoryWarning) {
          Row() {
            Text('⚠ 内存使用接近上限，建议释放缓存')
              .fontSize(14)
              .fontColor('#F56C6C')
          }
          .width('100%')
          .padding(12)
          .borderRadius(8)
          .backgroundColor('#FEF0F0')
          .margin({ bottom: 16 })
        }

        // 操作按钮
        Button('清空图片缓存')
          .width('100%')
          .height(44)
          .backgroundColor('#E6A23C')
          .fontColor(Color.White)
          .margin({ bottom: 8 })
          .onClick(() => this.memoryManager.clearAllCache())

        Button('紧急释放内存')
          .width('100%')
          .height(44)
          .backgroundColor('#F56C6C')
          .fontColor(Color.White)
          .margin({ bottom: 8 })
          .onClick(() => this.memoryManager.emergencyRelease())

        Button('重置性能统计')
          .width('100%')
          .height(44)
          .backgroundColor('#4A90D9')
          .fontColor(Color.White)
          .onClick(() => this.monitor.reset())
      }
      .padding(16)
    }
    .width('100%')
    .height('100%')
  }
}

3.3 兼容性适配与开发规范

不同设备、不同 API 版本、不同媒体格式，兼容性适配是媒体开发中绕不开的话题。同时，良好的开发规范能让你少踩很多坑。

// MediaCompatibility.ets
// 兼容性适配与开发规范

import { deviceInfo } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';
import { BusinessError } from '@kit.BasicServicesKit';

// ======== 兼容性检测工具 ========

export class MediaCompatibilityChecker {
  // 设备能力缓存
  private deviceCapabilities: Map<string, boolean> = new Map();

  // 检测设备是否支持指定编解码格式
  async isCodecSupported(mimeType: string, isEncoder: boolean): Promise<boolean> {
    const cacheKey = `${mimeType}_${isEncoder ? 'enc' : 'dec'}`;
    
    // 命中缓存
    if (this.deviceCapabilities.has(cacheKey)) {
      return this.deviceCapabilities.get(cacheKey)!;
    }

    try {
      const result = media.isCodecSupported(mimeType, isEncoder);
      this.deviceCapabilities.set(cacheKey, result);
      return result;
    } catch (error) {
      console.warn(`[兼容性] 编解码检测失败: ${mimeType}`);
      this.deviceCapabilities.set(cacheKey, false);
      return false;
    }
  }

  // 获取推荐的媒体格式
  async getRecommendedFormat(): Promise<MediaFormatRecommendation> {
    const recommendation: MediaFormatRecommendation = {
      videoCodec: 'H264',
      audioCodec: 'AAC',
      container: 'MP4',
      maxResolution: '1080p',
      maxBitrate: 8000000,
      reason: ''
    };

    // 检测 H.265 支持
    const h265Supported = await this.isCodecSupported('video/hevc', false);
    if (h265Supported) {
      recommendation.videoCodec = 'H265';
      recommendation.reason = '设备支持 H.265，同等画质下带宽节省约 40%';
    } else {
      recommendation.reason = '设备不支持 H.265，降级使用 H.264';
    }

    // 根据设备类型调整分辨率
    const deviceType = deviceInfo.deviceType;
    if (deviceType === 'tv' || deviceType === 'tablet') {
      recommendation.maxResolution = '4K';
      recommendation.maxBitrate = 20000000;
    } else if (deviceType === 'wearable') {
      recommendation.maxResolution = '720p';
      recommendation.maxBitrate = 2000000;
    }

    return recommendation;
  }

  // 检测 API 版本兼容性
  checkApiCompatibility(requiredApiVersion: number): CompatibilityResult {
    const currentApiVersion = deviceInfo.sdkApiVersion;
    
    if (currentApiVersion >= requiredApiVersion) {
      return {
        compatible: true,
        message: `当前 API ${currentApiVersion} 满足要求 (≥ ${requiredApiVersion})`
      };
    }

    return {
      compatible: false,
      message: `当前 API ${currentApiVersion} 不满足要求 (需要 ≥ ${requiredApiVersion})，请提供降级方案`
    };
  }

  // 获取降级方案
  getFallbackChain(primaryFormat: string): string[] {
    const fallbackMap: Record<string, string[]> = {
      'H265': ['H264', 'VP8'],
      'H264': ['VP8', 'MPEG4'],
      'AAC': ['MP3', 'VORBIS'],
      'FLAC': ['AAC', 'MP3'],
      '4K': ['1080p', '720p', '480p'],
      '1080p': ['720p', '480p'],
    };
    return fallbackMap[primaryFormat] || [];
  }
}

// 格式推荐结果
interface MediaFormatRecommendation {
  videoCodec: string;
  audioCodec: string;
  container: string;
  maxResolution: string;
  maxBitrate: number;
  reason: string;
}

// 兼容性检测结果
interface CompatibilityResult {
  compatible: boolean;
  message: string;
}

// ======== 开发规范工具 ========

export class MediaDevStandards {
  // 标准化错误处理
  static handleMediaError(error: Error, context: string): MediaErrorInfo {
    const err = error as BusinessError;
    const errorInfo: MediaErrorInfo = {
      code: err.code || -1,
      message: err.message || '未知错误',
      context: context,
      timestamp: Date.now(),
      severity: 'error',
      suggestion: ''
    };

    // 根据错误码给出建议
    errorInfo.suggestion = MediaDevStandards.getErrorSuggestion(err.code);
    
    // 根据错误类型判断严重程度
    if (err.code && err.code >= 5400101 && err.code <= 5400105) {
      errorInfo.severity = 'fatal';  // 播放器内部错误
    } else if (err.code && err.code >= 5400106 && err.code <= 5400110) {
      errorInfo.severity = 'warning';  // 资源类错误
    }

    // 标准化日志输出
    console.error(`[媒体错误] ${context} | Code: ${errorInfo.code} | Message: ${errorInfo.message} | Suggestion: ${errorInfo.suggestion}`);

    return errorInfo;
  }

  // 错误码对应的建议
  private static getErrorSuggestion(code: number | undefined): string {
    if (!code) return '请检查输入参数是否正确';
    
    const suggestionMap: Record<number, string> = {
      5400101: '播放器内部错误，请尝试重新创建播放器',
      5400102: '资源不存在，请检查文件路径或网络地址',
      5400103: '格式不支持，请检查媒体文件格式',
      5400104: '网络错误，请检查网络连接',
      5400105: '解码失败，请尝试降低分辨率或更换格式',
      5400106: '权限不足，请检查是否声明了必要权限',
      5400107: '缓冲区溢出，请检查缓冲策略配置',
    };

    return suggestionMap[code] || '未知错误，请查看日志获取更多信息';
  }

  // 标准化资源释放
  static safeRelease(resource: { release?: () => Promise<void> } | null, name: string) {
    if (!resource) return;
    try {
      resource.release?.();
      console.info(`[资源管理] ${name} 已释放`);
    } catch (error) {
      console.warn(`[资源管理] ${name} 释放失败，可能已被回收`);
    }
  }

  // 标准化异步操作（带超时）
  static async withTimeout<T>(
    promise: Promise<T>,
    timeoutMs: number,
    operation: string
  ): Promise<T> {
    return new Promise<T>((resolve, reject) => {
      const timer = setTimeout(() => {
        reject(new Error(`[超时] ${operation} 在 ${timeoutMs}ms 内未完成`));
      }, timeoutMs);

      promise
        .then((result) => {
          clearTimeout(timer);
          resolve(result);
        })
        .catch((error) => {
          clearTimeout(timer);
          reject(error);
        });
    });
  }
}

// 媒体错误信息
interface MediaErrorInfo {
  code: number;
  message: string;
  context: string;
  timestamp: number;
  severity: 'info' | 'warning' | 'error' | 'fatal';
  suggestion: string;
}

// ======== UI 集成 ========

@Entry
@Component
struct MediaCompatibilityPage {
  private checker: MediaCompatibilityChecker = new MediaCompatibilityChecker();
  @State recommendedFormat: MediaFormatRecommendation | null = null;
  @State apiCompatibility: CompatibilityResult | null = null;
  @State checkResults: string[] = [];

  // 执行兼容性检测
  async runCompatibilityCheck() {
    this.checkResults = [];

    // 1. 检测编解码支持
    const h264 = await this.checker.isCodecSupported('video/avc', false);
    const h265 = await this.checker.isCodecSupported('video/hevc', false);
    const aac = await this.checker.isCodecSupported('audio/aac', false);
    const flac = await this.checker.isCodecSupported('audio/flac', false);

    this.checkResults.push(`H.264 解码: ${h264 ? '✅ 支持' : '❌ 不支持'}`);
    this.checkResults.push(`H.265 解码: ${h265 ? '✅ 支持' : '❌ 不支持'}`);
    this.checkResults.push(`AAC 解码: ${aac ? '✅ 支持' : '❌ 不支持'}`);
    this.checkResults.push(`FLAC 解码: ${flac ? '✅ 支持' : '❌ 不支持'}`);

    // 2. 获取推荐格式
    this.recommendedFormat = await this.checker.getRecommendedFormat();

    // 3. 检测 API 兼容性
    this.apiCompatibility = this.checker.checkApiCompatibility(12);

    // 4. 降级链展示
    const h265Fallback = this.checker.getFallbackChain('H265');
    this.checkResults.push(`H.265 降级链: ${h265Fallback.join(' → ')}`);
  }

  build() {
    Scroll() {
      Column() {
        Text('兼容性适配检测')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .margin({ bottom: 16 })

        // 检测结果
        Column() {
          ForEach(this.checkResults, (result: string) => {
            Text(result)
              .fontSize(14)
              .width('100%')
              .padding({ top: 6, bottom: 6 })
          }, (result: string, index?: number) => `${index}`)
        }
        .width('100%')
        .padding(12)
        .borderRadius(8)
        .backgroundColor('#F5F7FA')
        .margin({ bottom: 16 })

        // 推荐格式
        if (this.recommendedFormat) {
          Column() {
            Text('推荐格式')
              .fontSize(16)
              .fontWeight(FontWeight.Bold)
              .margin({ bottom: 8 })
            Text(`视频编码: ${this.recommendedFormat.videoCodec}`)
              .fontSize(14)
            Text(`音频编码: ${this.recommendedFormat.audioCodec}`)
              .fontSize(14)
            Text(`容器格式: ${this.recommendedFormat.container}`)
              .fontSize(14)
            Text(`最大分辨率: ${this.recommendedFormat.maxResolution}`)
              .fontSize(14)
            Text(`推荐原因: ${this.recommendedFormat.reason}`)
              .fontSize(12)
              .fontColor('#999999')
              .margin({ top: 4 })
          }
          .width('100%')
          .padding(12)
          .borderRadius(8)
          .backgroundColor('#FFFFFF')
          .border({ width: 1, color: '#E8E8E8' })
          .margin({ bottom: 16 })
        }

        // API 兼容性
        if (this.apiCompatibility) {
          Row() {
            Text(this.apiCompatibility.compatible ? '✅' : '❌')
              .fontSize(18)
            Text(this.apiCompatibility.message)
              .fontSize(14)
              .margin({ left: 8 })
              .fontColor(this.apiCompatibility.compatible ? '#67C23A' : '#F56C6C')
          }
          .width('100%')
          .padding(12)
          .borderRadius(8)
          .backgroundColor(this.apiCompatibility.compatible ? '#F0F9EB' : '#FEF0F0')
          .margin({ bottom: 16 })
        }

        // 执行检测按钮
        Button('执行兼容性检测')
          .width('100%')
          .height(44)
          .backgroundColor('#4A90D9')
          .fontColor(Color.White)
          .onClick(() => this.runCompatibilityCheck())
      }
      .padding(16)
    }
    .width('100%')
    .height('100%')
  }
}

四、踩坑与注意事项

4.1 架构设计常见错误

4.2 性能优化关键点

1. 预加载是王道：在用户点击之前就预加载下一首歌曲/下一个视频，能大幅提升体验
2. 缓冲策略要动态：WiFi 下可以少缓冲，蜂窝网络下要多缓冲
3. 图片解码要异步：大图解码很耗时，必须在子线程执行
4. 避免频繁 GC：减少临时对象的创建，复用缓冲区
5. 渲染优化：视频播放时减少 UI 刷新频率，避免不必要的重绘

4.3 内存管理铁律

• 谁创建谁释放：创建播放器/图片的一方负责释放，不要跨组件传递所有权
• 缓存要有上限：LRU 缓存必须设置最大数量，否则会无限增长
• 大文件用流式处理：不要一次性将大文件加载到内存
• 监听器要及时移除：忘记移除监听器是最常见的内存泄漏原因
• 内存警告要响应：系统发出内存警告时，主动释放非必要资源

4.4 兼容性适配要点

1. 先检测再使用：不要假设所有设备都支持 H.265 或 4K，先检测能力再决定策略
2. 降级链要完整：从最优方案到最差方案，每一级都要有对应的降级逻辑
3. API 版本要判断：新 API 在旧系统上不可用，必须做版本检查
4. 格式兼容要测试：不同设备对同一格式的支持可能有差异，实际测试比文档更可靠

4.5 开发规范清单

• [ ] 所有媒体操作都有 try-catch
• [ ] 所有资源在生命周期结束时释放
• [ ] 所有异步操作有超时机制
• [ ] 所有错误有用户可见的反馈
• [ ] 所有日志使用统一前缀和格式
• [ ] 所有硬编码的媒体参数提取为配置
• [ ] 所有播放状态变更通知 UI 层
• [ ] 所有后台任务申请和释放配对

五、HarmonyOS 6 适配

5.1 API 变更

5.2 迁移指南

// HarmonyOS 5 写法：手动实现自适应码率
// 需要自己监听网络状况、手动切换清晰度

// HarmonyOS 6 写法：SmartAVPlayer 自动适配
import { media } from '@kit.MediaKit';

const smartPlayer = await media.createSmartAVPlayer({
  // 自适应码率配置
  abrConfig: {
    enabled: true,
    initialBitrate: 2000000,      // 初始码率
    maxBitrate: 10000000,          // 最大码率
    minBitrate: 500000,            // 最小码率
    // 网络变化时自动调整
    adaptToNetwork: true
  }
});

// 自动选择最佳清晰度，无需手动干预
smartPlayer.url = 'https://example.com/adaptive.m3u8';
await smartPlayer.play();

5.3 新特性：统一能力注册表

HarmonyOS 6 提供了统一的能力注册表，一次查询就能获取设备所有媒体能力：

// HarmonyOS 6 新增：能力注册表
import { capabilityRegistry } from '@kit.MediaKit';

// 一次性查询所有媒体能力
const capabilities = await capabilityRegistry.queryAll({
  categories: ['codec', 'format', 'resolution', 'streaming']
});

// 输出示例：
// {
//   codecs: { decode: ['H264', 'H265', 'VP9'], encode: ['H264', 'AAC'] },
//   formats: ['MP4', 'MKV', 'WebM', 'FLAC'],
//   maxResolution: '4K',
//   streaming: ['HLS', 'DASH', 'SmoothStreaming']
// }

六、总结

mindmap
  root((媒体最佳实践))
    架构设计
      分层架构
      数据层/业务层/UI层
      职责分离
      状态驱动
      错误隔离
    性能优化
      预加载策略
      动态缓冲
      异步解码
      渲染优化
      性能监控
    内存管理
      LRU 缓存
      谁创建谁释放
      大文件流式处理
      内存警告响应
      紧急释放机制
    兼容性适配
      编解码检测
      降级链设计
      API 版本检查
      设备能力检测
      格式兼容测试
    开发规范
      错误处理规范
      资源释放规范
      日志输出规范
      异步超时规范
      状态通知规范
    HarmonyOS 6
      SmartAVPlayer
      ImageCacheManager
      CapabilityRegistry
      MediaPerformanceProfile

关键知识点回顾：

1. 架构是根基：分层架构让代码可维护、可测试、可扩展，不要图省事把所有逻辑堆在一起
2. 性能要量化：FPS、卡顿率、首帧时间，用数据说话，不要凭感觉优化
3. 内存要管控：LRU 缓存、及时释放、紧急回收，三道防线缺一不可
4. 兼容要检测：不要假设设备能力，先检测再使用，降级链要完整
5. 规范要落地：错误处理、资源释放、日志格式，规范不是挂在墙上的，是写进代码里的
6. HarmonyOS 6 更智能：SmartAVPlayer 和 CapabilityRegistry 让很多手动工作变成了自动化

一句话总结：媒体最佳实践的本质是"用工程化的思维做媒体开发"，架构决定上限，细节决定下限，规范决定一致性。