🛠️ 鸿蒙开发实战：100 个项目疑难杂症汇编

背景：基于 HarmonyOS NEXT (ArkTS Stage 模型)，记录了从环境搭建到上线打包的真实血泪史。

💀 第一板块：环境与配置之坑 (1-10)

1. Previewer 预览白屏/崩溃：检查是否在 onWindowStageCreate 中使用了 AppStorage 初始化数据，预览器不走完整生命周期，需做非空判断。
2. 模拟器无法联网：模拟器默认 DNS 可能有问题，尝试在模拟器设置中配置代理，或者检查宿主机防火墙。
3. hvigor ERROR: BUILD FAILED 无详细日志：在命令行执行 ./hvigorw assembleHap --info --debug 查看详细堆栈。
4. **真机调试安装失败 error: install parse profile missing prop**：通常是 signingConfigs 签名文件过期或 device-id 未注册，需重新生成 Profile。
5. SDK 版本不匹配：build-profile.json5 中的 compileSdkVersion 必须与 DevEco Studio 版本对应的 SDK 匹配，不可随意修改。
6. 资源引用报错 $r 找不到：检查 string.json 或 media 是否刚添加？尝试 Build -> Clean Project，R 文件生成有时有延迟。
7. Git 冲突导致 ResourceTable.h 报错：不要把 ResourceTable.h 和 ResourceTable.txt 加入 Git 版本控制，它们是自动生成的。
8. 断点调试进不去：检查是否开启了 Release 模式？必须切换回 Debug 模式。
9. HSP 模块无法引用：HSP 必须在主项目的 oh-package.json5 中通过 file:./library 方式引入，且需运行 ohpm install。
10. 模拟器打不开网页：需要在 module.json5 中申请 ohos.permission.INTERNET 权限（虽然是基础权限，但必须声明）。

🏗️ 第二板块：ArkTS 语法与逻辑之坑 (11-25)

11. 回调函数中 this 为 undefined：经典 JS 问题。在回调中调用类方法，必须写成 () => this.method() 或在构造函数中 .bind(this)。
12. JSON.parse 丢失精度：后端返回的 Long 类型 ID（如雪花算法 ID）超过 16 位，JS 会丢失精度。需使用 json-bigint 库或后端转 String。
13. number 类型 0.1 + 0.2 !== 0.3：涉及金额计算必须用 Decimal 库，严禁直接用 float 计算。
14. interface 类型强转失效：as MyInterface 只是编译期欺骗，运行时如果不符合结构，访问属性会崩。建议用 class-transformer 做转换。
15. 循环引用导致内存溢出：ArkTS 强类型引用容易造成引用计数无法归零，尽量使用 WeakRef 处理父子相互引用。
16. **console.info 打印对象显示 [object Object]**：请使用 JSON.stringify(obj) 包裹，或使用 %j 格式化。
17. Date 时区问题：new Date() 获取的是设备本地时间，与后端 UTC 时间交互时需注意时区偏移。
18. Map 遍历顺序：ArkTS 的 Map 遍历顺序与插入顺序一致，但 Object.keys 不保证顺序。
19. switch-case 穿透：ArkTS 静态检查严格，但也需注意 break，否则逻辑会穿透。
20. struct 无法继承：不要试图让组件继承另一个组件。复用逻辑请用 Mixin 模式或组合模式。
21. 私有属性 _xxx 无法在 @Builder 中访问：@Builder 本质是函数，作用域微妙。建议通过参数传递。
22. import 路径过长：配置 oh-package.json5 或 tsconfig.json 的 paths 别名（如 @/utils）。
23. 空值合并运算符 ?? 与 || 混用：?? 只处理 null/undefined，|| 会处理 0 和空字符串。业务逻辑中要分清。
24. LazyForEach 数据源修改不刷新：修改了数据源数组，但没有调用 listener.onDataReloaded()，UI 不会动。
25. Promise 异常未捕获导致 Crash：必须写 .catch() 或在 async 函数中用 try-catch 包裹。

🎨 第三板块：ArkUI 布局与渲染之坑 (26-45)

26. List 滑动闪烁/跳动：99% 是因为 LazyForEach 的 keyGenerator 写了 (item, index) => index。绝对禁止用 index 做 key，必须用 item.id。
27. Image 加载网络图空白：检查是否申请网络权限？检查 URL 是否是 http（需配置 cleartext）？
28. 文本被截断/省略号不显示：Text 组件必须设置 width 或 flexShrink(1)，否则它会无限撑开父容器。
29. 输入法遮挡输入框：使用 expandSafeArea 或在 windowStage 设置键盘避让模式 keyboardDesign(KeyboardDesign.ADJUST_PAN)。
30. z-index 不生效：z-index 只能调整同一父容器内的层级。不同父容器需调整组件树结构。
31. Visibility.Hidden 占位问题：Hidden 会保留布局空间。如果想完全消失且不占位，用 Visibility.None。
32. Row 里面的 Text 不换行：给 Text 设置 .layoutWeight(1) 或 .width('100%')，否则会把 Row 撑出屏幕。
33. Swiper 滑动冲突：Swiper 内部嵌套 List/Scroll 时，需根据滑动方向处理手势拦截。
34. 圆角设置无效：父容器设置了 borderRadius，子图片没切角？给父容器加 .clip(true)。
35. 自定义 Dialog 无法全屏：CustomDialogController 默认有 padding 和圆角，需设置 customStyle: true。
36. RelativeContainer 锚点报错：锚点 ID 必须存在且唯一，__container__ 代表父容器。
37. Flex 布局性能差：在鸿蒙中，能用 Row/Column 尽量不用 Flex，Flex 计算量大。
38. SVG 图标颜色无法修改：SVG 必须把内部的 fill 属性改成 currentColor，然后通过 .fillColor() 修改。
39. Grid 组件 GridItem 高度不一致：默认 GridItem 会自适应。如需整齐，需固定宽高或使用 aspectRatio。
40. 沉浸式状态栏内容重叠：未获取 systemSafeArea 高度并设置 Padding。
41. Web 组件加载本地 HTML 失败：本地文件需放在 rawfile 下，并通过 $rawfile('index.html') 访问。
42. Tabs 切换重新加载：Tabs 默认会销毁不可见的 TabContent。需设置 .barMode(BarMode.Fixed) 配合缓存策略。
43. 富文本显示：RichText 组件底层是 Web，性能较重。简单格式建议用 Text + Span 组合。
44. 阴影 shadow 导致卡顿：大面积高斯模糊阴影非常耗 GPU，尽量用图片代替复杂阴影。
45. 页面转场黑屏：跳转时未配置 pageTransition 或生命周期中有耗时同步操作。

🔄 第四板块：状态管理之坑 (46-60)

46. 对象深层属性修改不刷新：@State 监听不到 this.obj.nested.prop = 1。需用 @Observed + @ObjectLink 或 V2 的 @Trace。
47. AppStorage 数据错乱：AppStorage 是全局单例，多个页面同时修改同一个 Key 会冲突。
48. @Watch 无限循环：在 Watch 回调里又修改了被监听的变量。务必加判断条件。
49. @Link 初始化报错：父组件传给 @Link 子组件时，必须使用 $ 符号引用（如 $myState）。
50. LocalStorage 获取不到：LocalStorage 必须在 loadContent 时传入，否则页面内 GetShared 为空。
51. 数组 push 不刷新：直接 arr[0] = x 不会刷新，需用 arr.splice 或重新赋值 arr = [...newArr]。
52. PersistentStorage 拖慢启动：千万别存大 JSON！它会在应用启动时同步读取磁盘。
53. @Builder 传参不更新：调用 Builder 时直接传 this.val 是按值传递。需传对象或使用 $$this.val (按引用)。
54. @Provide 别名问题：@Provide('alias') 和 @Consume('alias') 别名必须一致，否则连不上。
55. V2 版本 @Local 赋初值问题：@Local 变量必须初始化，否则编译报错。
56. SubscribableAbstract 内存泄漏：手动实现的数据源监听器，组件销毁时必须 off 掉监听。
57. Environment 字体大小变化适配：需监听 Environment.envProp('fontSizeScale') 动态调整 UI。
58. 多线程状态同步：TaskPool 无法访问 AppStorage。需将数据通过参数传入 Task，计算完返回更新。
59. this 在 build 中指向错误：不要在 build 里解构 this（如 const { val } = this），这样会丢失响应性。
60. 状态变量改名未重构：IDE 重构有时漏掉字符串引用的状态（如 AppStorage 的 key），导致运行时错误。

⚡ 第五板块：交互与路由之坑 (61-75)

61. router.push 超过 32 层报错：页面栈限制。需配合 router.replace 或 router.clear，或者改用 Navigation。
62. Navigation 标题栏无法隐藏：需设置 .hideTitleBar(true)。
63. Back 键无法拦截：onBackPress 必须返回 true 才能拦截系统的返回行为。
64. 手势冲突：List 里的 Slider 滑动困难。需设置 gesture 的 PanGesture 优先级或 gestureMask。
65. 点击热区太小：给小图标设置 .responseRegion({ width: 50, height: 50 }) 扩大点击范围。
66. 多次点击导致打开多个页面：跳转逻辑需加防抖（Throttle）处理。
67. Dialog 点击遮罩不关闭：需设置 autoCancel: true。
68. 软键盘顶起布局错乱：布局未包裹在 Scroll 或 List 中，导致无法滚动查看被遮挡内容。
69. TextInput 无法获取焦点：检查 .enabled 或 .focusable 属性，或者是否被透明组件遮挡。
70. WebView 拦截 URL：onLoadIntercept 返回 true 表示拦截，不要搞反了。
71. 侧滑返回手势失效：全屏模态转场 (bindContentCover) 默认会屏蔽侧滑返回。
72. Navigation 参数传递丢失：NavPathStack push 时参数必须放在 param 字段，目标页在 onLoad 中获取。
73. TabContent 切换动画卡顿：Tab 内容过于复杂。建议用 custom 模式自己控制显示隐藏，或简化 DOM。
74. 长按事件与点击事件冲突：长按松开后触发了点击？区分 Action.Up 和 Action.Cancel。
75. 拖拽 onDrag 不触发：组件必须设置 .draggable(true) 且长按默认 500ms 才会触发。

📡 第六板块：网络与数据之坑 (76-85)

76. HTTP 默认为空：鸿蒙默认禁止明文 HTTP，需在 module.json5 配置 requestPermissions 的 securityConfig。
77. 请求超时无反应：http 模块需手动设置 connectTimeout 和 readTimeout，默认值可能过长。
78. 文件上传 Content-Type 错误：multipart/form-data 需要手动拼接边界（Boundary），或使用 request.uploadFile。
79. Preferences 数据覆盖：put() 后必须 flush() 才能持久化写入磁盘。
80. RDB 数据库多线程读写锁：RDB 连接池有限，并发写入可能报错 SQLITE_BUSY。
81. KVStore 存满报错：分布式 KV 数据库有单条 4MB 和总大小限制，不可当文件系统用。
82. RawFile 读取耗时：getRawFileContent 是同步 IO，大文件会卡死主线程，必须用异步或 Worker。
83. 图片缓存策略：Image 组件默认有缓存，但更新头像（URL 不变）时缓存不刷新。需在 URL 后加时间戳。
84. JSON 解析崩溃：后端返回的 JSON 格式错误（如多逗号），JSON.parse 直接抛异常，必须 try-catch。
85. 网络断开重连监听：connection.createNetConnection() 监听网络状态，注意去重（系统可能多次回调）。

📱 第七板块：设备与原生能力之坑 (86-95)

86. 权限申请不弹窗：requestPermissionsFromUser 必须在 UIAbility 的 onWindowStageCreate 之后调用，且必须在 module.json5 声明。
87. 定位获取不到：室内 GPS 无信号，需优先使用 LocationRequest 的 PRIORITY_ACCURACY 或网络定位。
88. 相机预览黑屏：XComponent 的 surfaceId 必须在 onLoad 回调后才能获取并传给相机。
89. NAPI 字符串乱码：C++ 与 ArkTS 字符串编码转换（UTF-8 vs UTF-16）未处理好。
90. 后台播放音乐被杀：未申请 continuousTask 且未在通知栏显示播放控制器 (AVSession)。
91. 扫码识别率低：使用了通用的相机流自己解析？建议直接调用 ScanKit，华为优化过。
92. 剪贴板读取失败：只有前台且获取焦点的应用才能读取剪贴板，后台读取会抛错（隐私安全）。
93. 屏幕亮度调节失效：需申请 SystemPermission.MANAGE_SETTINGS（通常只有系统应用有权）。
94. 震动反馈无效果：检查设备是否开启静音/免打扰模式？或者 vibrator 时长太短。
95. 获取设备 ID (UDID) 失败：普通应用拿不到 UDID，只能用 AAID 或 ODID。

💣 第八板块：打包与发布之坑 (96-100)

96. 混淆后 Crash：使用了反射或动态属性访问，但属性名被混淆了。需配置 -keep-property-name。
97. APP ID 校验失败：发布的 Profile 文件中的 bundleName 与项目配置不一致。
98. HAP 包体积超标：单包超过限制无法上架。必须拆分 HSP 或使用分包上传。
99. 隐私协议审核被拒：启动时初始化 SDK 获取了 mac 地址？必须在用户点击“同意”隐私协议之后再初始化 SDK。
100. 32位/64位 SO 库冲突：引用的第三方库只有 armeabi-v7a，但真机是 arm64-v8a。需在 build-profile 中过滤 ABI。

💡 结语

写鸿蒙项目，不仅要会写代码，更要会**“排雷”**。这 100 个坑，每一个都是前人用发际线换来的经验。建议收藏本文，在遇到莫名其妙的 Bug 时拿出来对照查阅。

祝各位开发者：编译一次过，上线无 Bug！