引言：為什么我要寫這份開發指南？

作為一名老技術，最近特別喜歡研究鴻蒙相機功能，而且目前已經更新到API15了，那么咱們更要好好研究一下。而且從手持云臺到車載記錄儀，每個項目都面臨獨特挑戰：車載場景的高溫穩定性、可穿戴設備的低功耗限制、多設備分辨率適配的玄學…… 這些痛點促使我重新梳理 HarmonyOS 相機開發的技術脈絡 —— 這正是本文的起源。

比如之前在一款運動相機項目中，我們最初直接復用 Android 相機邏輯，結果在 HarmonyOS 5.0 設備上頻繁出現預覽與錄像流撕裂（畫面比例失調）。深入研究發現：鴻蒙 Camera Kit 的 Surface 管道架構要求預覽 / 錄像流的寬高比嚴格對齊。通過重構輸出流創建邏輯（動態匹配分辨率列表），最終在中端設備上實現了全分辨率適配 —— 這個過程讓我意識到：硬件層開發需要建立鴻蒙特有的知識體系，而系統化的實踐總結尤為稀缺。

市面上的鴻蒙教程多聚焦 UI 框架，對 Camera Kit、Media Kit 等硬件交互模塊的解析停留在 API 層面。作為一線開發者，我希望將設備適配、性能調優的實戰經驗轉化為可復用的開發范式。本文不僅包含官方文檔的深度解讀，更融入了真實項目的「避坑指南」—— 從 Surface 生命周期管理到多線程資源調度，每個環節都經過設備兼容性驗證，也希望幫助到大家少踩坑。

核心開發流程：從代碼到設備的落地實踐

一、環境準備與模塊初始化

1. 權限聲明：在config.json中聲明相機、錄音、存儲權限，遵循鴻蒙最小權限原則：

   "reqPermissions": [{"name": "ohos.permission.CAMERA","reason": "用于相機取景與錄制"}
   ]
   

2. 模塊導入：引入核心工具類（錯誤處理、相機服務、媒體服務）：

   import { BusinessError } from '@ohos.basicServices';
   import { camera } from '@ohos.camera';
   import { media } from '@ohos.media';
   

二、錄像流創建的核心邏輯

1. Surface 關聯：通過media.createAVRecorder()創建錄制實例，獲取輸入 Surface：

   async function createRecorderSurface(config: media.AVRecorderConfig): Promise<string | null> {try {const recorder = await media.createAVRecorder();recorder.prepare(config);return recorder.getInputSurface();} catch (err) {console.error(`Recorder創建失敗：${(err as BusinessError).code}`);return null;}
   }
   

2. 分辨率匹配：從設備支持的videoProfiles中篩選符合寬高比的配置（以 4:3 為例）：

   const validProfile = capabilities.videoProfiles.find(p => p.size.width / p.size.height === 4/3 &&p.size.width >= 640 // 最低分辨率保障
   );
   

三、錄制控制與狀態管理

1. 啟停流程：嚴格遵循「輸出流先啟后停」原則，避免資源泄漏：

   // 啟動：先激活輸出流，再開始錄制
   videoOutput.start(); 
   await recorder.start();// 停止：先停止錄制，再關閉輸出流
   await recorder.stop(); 
   videoOutput.stop();
   

2. 狀態監聽：注冊生命周期回調（首幀 / 末幀 / 錯誤），實現錄制狀態可視化：

   videoOutput.on('frameStart', () => console.log('[錄像開始] 首幀已捕獲'));
   videoOutput.on('frameEnd', () => console.log('[錄像結束] 末幀處理完成'));
   videoOutput.on('error', (err) => handleCameraError(err.code)); // 自定義錯誤處理
   

四、設備適配的三大法則

1. 旋轉補償：通過VideoOutput.getVideoRotation()獲取物理旋轉角度，修正畫面方向：

   const rotation = await videoOutput.getVideoRotation(); // 0/90/180/270度
   recorderConfig.rotation = rotation; // 同步到錄制配置
   

2. 動態幀率：根據設備負載調節幀率（示例：低功耗模式降為 15fps）：

   if (batteryLevel < 20%) {profile.videoFrameRate = 15; // 切換低幀率配置updateRecorderProfile(profile);
   }
   

3. 編解碼優化：優先使用硬件編碼器（VIDEO_AVC），降低 CPU 占用：

   const profile: media.AVRecorderProfile = {videoCodec: media.CodecMimeType.VIDEO_AVC, // 硬件編碼videoBitrate: 8 * 1024 * 1024, // 8Mbps碼率（1080p標準）
   };
   

總結：鴻蒙相機開發的「三重境界」

1. 功能實現：掌握 API 調用順序（Surface 創建→流配置→狀態監聽）
2. 設備適配：理解硬件特性（分辨率、旋轉、編解碼能力）的差異化處理
3. 體驗設計：從用戶場景出發（防抖、低功耗、多端協同），構建全場景解決方案

本文很多的優化策略是吸取官方?HarmonyOS 官方最佳實踐。無論你是鴻蒙開發新手，還是想拓展硬件交互能力的工程師，希望這份指南能成為你探索全場景開發的「實戰手冊」。

當然最終能希望大家少踩坑～

有需要的同學可以收藏～