鸿蒙开发踩坑笔记，这些实际问题你肯定也遇到过

TOMO

11人浏览 · 2025-11-12 22:11:37

TOMO · 2025-11-12 22:11:37 发布

最近维护几个鸿蒙5的老项目，遇到不少 “文档没写透” 的问题。从组件适配到权限调用，有些坑调试起来特别费时间。整理了几个高频场景的解决思路，附实测代码，希望能帮到还在维护鸿蒙5项目的同学。

第一个问题：@Builder 组件在低版本真机上不显示

问题现象：用 @Builder 写的自定义标题栏，在鸿蒙 5.0.0.188 以上版本正常，在 5.0.0.156 及以下机型（比如老款 P40）完全不显示，预览器也没报错。

排查过程：

一开始以为是布局层级问题，加了背景色依然不显示；
对比官方示例发现，鸿蒙 5 早期版本对 @Builder 的参数类型校验更严格—— 如果传参包含 undefined，会导致整个组件渲染失败。

解决代码：

// 有问题的代码（参数可能为undefined）
@Builder TitleBar(title?: string) {
  Row() {
    Text(title) // 当title为undefined时，低版本直接不渲染
      .fontSize(18)
  }
  .width('100%')
  .height(50)
}

// 修复后
@Builder TitleBar(title: string = '') { // 强制设置默认值，避免undefined
  Row() {
    Text(title || '默认标题') // 再加一层兜底
      .fontSize(18)
  }
  .width('100%')
  .height(50)
  .backgroundColor('#F5F5F5') // 加背景色，方便调试是否渲染
}

关键改动：

给 @Builder 的参数设置默认值（比如title: string = ''），避免传入 undefined；
低版本真机对 “空内容组件” 的处理更严格，Text、Image 等组件如果内容为空，可能直接不渲染，建议加兜底内容。

第2个网络请求在部分鸿蒙 5 机型上偶发失败

问题现象：用 @ohos.net.http 发起 POST 请求，在 Mate 30（鸿蒙 5.0.0.210）上正常，在 Nova 7（鸿蒙 5.0.0.190）上偶尔报 “net::ERR_CONNECTION_RESET”，且失败概率随请求体增大而升高。

排查过程：抓包发现失败的请求没带 Content-Length 头，鸿蒙 5 的 http 模块在处理大于 1KB 的请求体时，低版本可能漏加该头部，导致服务器拒收。

解决代码：

import http from '@ohos.net.http';

async function postData(url: string, data: object) {
  let request = http.createHttp();
  try {
    const body = JSON.stringify(data);
    const response = await request.request(
      url,
      {
        method: http.RequestMethod.POST,
        header: {
          'Content-Type': 'application/json',
          'Content-Length': body.length.toString() // 手动添加长度头
        },
        extraData: body,
        connectTimeout: 60000, // 延长超时时间，避免低性能机型处理慢
        readTimeout: 60000
      }
    );
    return response.result;
  } catch (err) {
    console.error('请求失败：', err);
  } finally {
    request.destroy();
  }
}

关键改动：

手动在 header 里添加Content-Length，值为请求体字符串的长度；
低版本机型性能较差，建议把超时时间从默认的 30 秒延长到 60 秒，减少因处理慢导致的超时失败。

第三个List 组件滑动时偶发数据错乱

问题现象：用 List+ListItem 渲染列表，快速滑动时偶尔出现 “数据重复” 或 “内容和索引不匹配”，尤其在鸿蒙 5.0.0.170 以下版本明显。

排查过程：发现是鸿蒙 5 的列表复用机制导致 —— 当 item 包含 @State 变量时，滑动复用 item 时，状态没有被正确重置，导致显示上一个 item 的残留数据。

解决代码：

// 有问题的代码（@State在复用中不重置）
@Component
struct GoodsItem {
  @State count: number = 0; // 复用item时，count会保留上一次的值
  item: Goods;

  build() {
    Row() {
      Text(this.item.name)
      Button(`+${this.count}`)
        .onClick(() => this.count++)
    }
  }
}

// 修复后（用@Prop接收父组件状态，复用即重置）
@Component
struct GoodsItem {
  @Prop count: number; // 从父组件传入，复用item时重新初始化
  item: Goods;

  build() {
    Row() {
      Text(this.item.name)
      Button(`+${this.count}`)
        .onClick(() => this.count++)
    }
  }
}

// 父组件使用时，为每个item创建独立状态
List() {
  ForEach(this.goodsList, (item, index) => {
    ListItem() {
      GoodsItem({
        item: item,
        count: this.counts[index] || 0 // 用数组保存每个item的状态
      })
    }
  })
}

关键改动：

子组件的状态（如 count）改用 @Prop 接收，避免 @State 在复用中残留数据；
父组件用数组（如 counts []）保存每个 item 的独立状态，确保复用 item 时能正确初始化。

第四个：应用退到后台再打开，数据被重置

问题现象：用户在页面 A 输入内容，切换到后台再返回，页面 A 的数据（如 @State 变量）被重置，鸿蒙 5.0.0.160 及以下版本常见。

排查过程：鸿蒙 5 的进程保活机制在低版本较严格 —— 应用退到后台超过 30 秒，若内存不足会被回收，再次打开会重启页面，导致状态丢失。

解决代码：

import preferences from '@ohos.data.preferences';

@Entry
@Component
struct PageA {
  @State inputText: string = '';
  private pref: preferences.Preferences | null = null;

  async aboutToAppear() {
    // 初始化偏好设置
    this.pref = await preferences.getPreferences(getContext(), 'pageA_data');
    // 读取保存的状态
    this.inputText = await this.pref.get('inputText', '') as string;
  }

  // 监听页面切换到后台
  onBackground() {
    if (this.pref) {
      // 保存状态到偏好设置
      this.pref.put('inputText', this.inputText);
      this.pref.flush();
    }
  }

  build() {
    Column() {
      TextInput({ placeholder: '输入内容' })
        .value(this.inputText)
        .onChange((val) => this.inputText = val)
    }
  }
}

关键改动：