这篇记录我做鸿蒙任务时遇到的一个高频问题：页面刚进入时 @StorageLink 还没有准备好，ArkUI 构建函数里却已经开始读取数组、对象或字符串，最后在切换 Tab、进入详情页、刷新首页时出现 Cannot read property toString of undefined 这一类运行时错误。

本文不是讲一个单独语法点，而是把状态初始化、页面渲染、重置流程和构建验证串成一个闭环。只要项目里用了 AppStorage、PersistentStorage 或多个页面共享状态，这个检查点都值得提前做。

这篇解决什么问题

• 页面首次挂载时共享状态可能还没有完成水合。
• @Builder 里直接拼接对象或读取数组长度，容易把 undefined 放大成运行时崩溃。
• 新增一个持久化 key 时，只改页面字段是不够的，还要补启动、重置和删除路径。

代码来自哪里

• entry/src/main/ets/entryability/EntryAbility.ets
• entry/src/main/ets/common/PersistKeys.ets
• entry/src/main/ets/pages/Index.ets

下面这段是我更推荐的检查方式：把默认值集中放在启动阶段，页面只消费已经存在的稳定状态。

export const FAVORITE_RECORDS_KEY: string = 'favorite_records';

export function hydrateAppStorage(): void {
  AppStorage.setOrCreate<Array<string>>(FAVORITE_RECORDS_KEY, []);
  AppStorage.setOrCreate<boolean>('privacy_policy_accepted', false);
  AppStorage.setOrCreate<string>('active_theme', 'system');
}

页面里不要假设 @StorageLink 一定已经是数组，尤其不要在 @Builder 参数和模板字符串里直接消费复杂对象。

@StorageLink(FAVORITE_RECORDS_KEY) favoriteRecords: Array<string> = [];

getFavoriteCount(): number {
  return Array.isArray(this.favoriteRecords) ? this.favoriteRecords.length : 0;
}

@Builder FavoriteBadge() {
  Text(`${this.getFavoriteCount()} 条收藏`)
    .fontSize(12)
}

跑出来是什么效果
建议截图时重点保存三张图：

• 第一次安装后进入首页，不再因为共享状态未准备好而闪退。
• 删除或重置数据后重新进入收藏页，数量展示回到 0。
• 从详情页返回首页，徽标和列表能一起刷新。

流程串联：应用启动 → setOrCreate 默认值 → 页面读取安全方法 → 写入服务统一更新 → 重置流程同步清理

实操步骤

1. 先搜索所有新增的 @StorageLink key，确认它们在启动阶段都有 setOrCreate。
2. 再检查 @Builder 中有没有 .length、.toString()、模板字符串直接读取对象或数组。
3. 把页面展示需要的派生值改成普通方法，例如 getFavoriteCount()，方法内部返回安全默认值。
4. 找到重置、退出登录、删除记录等路径，确认这些 key 会一起回到默认状态。
5. 真机验证首次安装、杀进程重启、删除最后一条数据、快速切 Tab 四个场景。

工程质量点

• 共享状态的默认值应该在应用启动阶段统一建立，而不是散落在多个页面里兜底。
• 页面展示不要直接依赖复杂对象可用，先做类型和空值保护。
• @Builder 中尽量保持声明式，把临时计算移到普通方法里。
• 新增持久化 key 时，同时补充 reset/delete/export/import 的边界。
• 构建通过不代表运行时安全，状态水合类问题必须靠真机路径验证。