一、跨平臺編譯與適配問題

1. 平臺特定API不兼容

?問題現象?：使用Router模塊的replaceUrl或startAbility等鴻蒙專屬API時，編譯跨平臺工程報錯can't support crossplatform application。
?解決方案?：

• 改用@ohos.router的跨平臺封裝API，例如router.pushUrl替代router.replaceUrl
• 涉及系統能力調用的功能（如啟動Ability），使用條件編譯區分平臺代碼：

typescriptCopy Code

if (deviceInfo.osFullName === 'HarmonyOS') { // 鴻蒙原生API調用 } else { // 跨平臺替代方案 }

2. Android APK顯示異常

?典型表現?：頁面元素錯位、資源加載失敗或主題樣式失效。
?解決方案?：

• 檢查resources目錄結構是否符合ArkUI-X規范（資源文件需置于common子目錄）
• 使用$r('app.media.icon')統一資源引用路徑，避免硬編碼
• 在build-profile.json5中添加Android特定適配配置：

jsonCopy Code

"targets": { "android": { "compileSdkVersion": 34, "minSdkVersion": 21 } }

---

二、UI組件與交互問題

1. 焦點管理異常

?常見場景?：自定義彈窗中的焦點切換失效，或頁面跳轉后焦點殘留。
?解決方案?：

• 為可聚焦組件顯式設置focusable(true)和focusOnTouch(true)屬性
• 使用FocusControl模塊管理焦點鏈：

typescriptCopy Code

import { FocusControl } from '@arkui/x'; FocusControl.requestFocus('componentId');

2. 浮層組件渲染異常

?問題表現?：遮罩層無法覆蓋原生控件，或自定義浮層內容頻繁重建導致性能下降。
?解決方法?：

• 優先采用ComponentContent方式創建浮層，避免使用CustomBuilder頻繁重建
• 設置overlay參數時添加align和offset精確定位：

typescriptCopy Code

Text('Content').overlay( CustomComponent(), { align: Alignment.Bottom, offset: { x: 0, y: -10 } } )

---

三、原生能力集成問題

1. 原生模塊加載失敗

?典型報錯?：使用Bridge模塊時預覽白屏，或跨平臺編譯后功能異常。
?解決方案?：

• 通過deviceInfo.osFullName判斷運行環境，動態加載原生模塊
• 將原生接口封裝在獨立工具類中，延遲初始化：

typescriptCopy Code

class NativeBridge { static getInstance() { if (deviceInfo.osFullName !== 'OpenHarmony') { return new AndroidBridge(); } return null; } }

---

四、性能優化問題

1. 冷啟動連續丟幀

?性能指標?：動效環節超過0幀丟幀，加載環節超過6幀丟幀。
?優化方案?：

• 使用LazyForEach延遲加載非首屏組件
• 預加載關鍵資源，減少首幀渲染時的IO操作
• 通過trace工具分析主線程阻塞：

bashCopy Code

hdc shell hilog | grep "RenderFrame"

2. 復雜布局性能下降

?表現特征?：頁面滑動卡頓
?優化手段?：

• 使用Canvas替代多層嵌套的布局結構
• 對靜態內容啟用cachedCount屬性復用節點
• 避免在build函數內執行耗時操作

---

五、工具鏈使用問題

1. 熱重載失效

?常見原因?：修改了平臺相關代碼或原生模塊。
?處理流程?：

1. 確認修改范圍是否涉及native目錄
2. 使用Build > Clean Project清除緩存
3. 對于iOS平臺，重啟Xcode派生數據目錄