一、跨平臺編譯與適配問題
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. 熱重載失效
?常見原因?：修改了平臺相關代碼或原生模塊。
?處理流程?：
- 確認修改范圍是否涉及
native目錄 - 使用
Build > Clean Project清除緩存 - 對于iOS平臺，重啟Xcode派生數據目錄
