大家好，我是[晚风依旧似温柔]，新人一枚，欢迎大家关注~

前言

讲句心里话，我见过太多鸿蒙项目，Bug 本身不复杂，复杂的是——没人搞得清楚这玩意儿的状态到底是谁在管。
明明只是一个“切个主题色”“记个登录状态”“跨页面同步个 tabIndex”，结果搞出一堆神秘现象：

• A 页面改了个变量，B 页面死活不刷新
• AppStorage 里面一会儿有值、一会儿没值，跟薛定谔的猫似的
• LocalStorage 胡乱用，页面一多直接精神分裂
• Environment 是啥？“哦，那不是官方文档里顺带提了一嘴的吗？”

然后所有锅统一甩给：

“ArkUI 的状态管理好复杂啊……”

说实话，不是框架太复杂，是你根本没把它当一套完整的设计来看。
所以这篇我们就来认真唠一唠：

鸿蒙状态管理最佳实践：AppStorage / LocalStorage / Environment，到底该怎么优雅地用。

一、先把这“三兄弟”的定位说清楚

咱不整一堆概念，先用人话给他们三个打个标签：

• AppStorage：
  全局状态中心（应用级），适合“全 App 都关心”的状态
  比如：登录信息、主题、语言、用户配置、全局开关等等

• LocalStorage：
  页面 / 组件级的“本地小仓库”，适合多组件共享，但只在这棵树里生效的状态
  比如：某个 Tab 页面内部的多个子组件共享筛选条件

• Environment：
  环境变量 / 系统级上下文，适合描述运行环境：暗色模式、语言、方向、窗口尺寸等
  多用于：适配 / 响应系统变化，而不是你自己瞎写业务变量

我们按你的大纲来拆：

1. 三大存储方式介绍
2. 页面级 vs 全局状态
3. 状态同步流程
4. 项目结构 & 配置建议

一条龙给你整清楚 💪

---

二、三大存储方式详细拆解：到底该用谁？

2.1 AppStorage：全局状态的“唯一真神”

你可以把 AppStorage 理解成鸿蒙版的“全局 Store”，但它跟那种 Redux/Vuex 不太一样——
它更轻、更直接，也更“贴 ArkUI 的响应式模型”。

🧠 关键特性：

• 全局唯一（跟应用同生命周期）
• 基于 key-value
• 修改后会自动触发绑定 UI 刷新
• 可与 @StorageLink / @StorageProp 等装饰器联动

2.1.1 初始化全局状态（一般在入口 or Ability 启动阶段做）

AppStorage.Set('isLogin', false)
AppStorage.Set('theme', 'light')
AppStorage.Set('userProfile', null)

你可以在 UIAbility.onWindowStageCreate、应用入口处初始化这些全局变量。

2.1.2 在组件里“订阅”这些状态

ArkUI 提供了一套很香的装饰器家族，跟 AppStorage 高度绑定：

• @StorageProp('key')：只读，别人改你跟着变
• @StorageLink('key')：可读可写，双向绑定

示例：登录状态全局共享

@Entry
@Component
struct App {
  @StorageLink('isLogin') isLogin: boolean

  build() {
    if (!this.isLogin) {
      LoginPage()
    } else {
      HomePage()
    }
  }
}

登录页这样写：

@Component
struct LoginPage {
  @StorageLink('isLogin') isLogin: boolean

  doLogin() {
    // 验证通过
    this.isLogin = true  // 所有绑定 isLogin 的地方都更新
  }
}

是不是比你手写一堆路由跳转+EventBus 优雅多了？
一个变量，全局联动。

---

2.2 LocalStorage：页面局部小世界（树状作用域）

LocalStorage 是很多人忽略却非常有用的东西。
你可以理解为：在组件树某个节点挂一个“小型 AppStorage”，仅对这棵子树可见。

🔍 典型使用场景：

• 某个页面内部有多个子组件，他们需要共享一些状态（筛选条件、Tab index、列表配置）
• 这些状态没必要放 AppStorage，全局知道反而变乱

2.2.1 创建 LocalStorage

有两种常见方式，简化理解：

@Entry
@Component
struct PageWithLocalStorage {
  private myLocal: LocalStorage = new LocalStorage()

  build() {
    // 把 LocalStorage 绑定到这棵子树
    WithLocalStorage(this.myLocal) {
      ChildA()
      ChildB()
      ChildC()
    }
  }
}

然后你可以在子组件里用 @LocalStorageLink 之类去取值（具体 API 以当前 ArkUI 版本为准，但模式都是“在这个子树共享一份状态”）。

它解决的痛点：

• 不用疯狂往子组件一层一层传 props（痛）
• 不污染 AppStorage（干净）
• 只在这棵树里生效（安全）

2.2.2 和 AppStorage 的区别记牢👇

对比点	AppStorage	LocalStorage
作用域	整个应用	当前绑定的组件树（局部）
生命周期	跟应用同寿命	跟容器组件同寿命
场景	登录、主题、配置、用户信息等	页面内部共享状态、Tab 分页的共享数据
风险	滥用 → 全局变量地狱	滥用 → 结构乱但影响范围有限

一句话总结：

凡是别人不需要知道的状态，就别随便扔进 AppStorage。

---

2.3 Environment：更像“系统上下文”，而不是业务状态仓库

Environment 这家伙，很容易被误解。
很多人看到这个名字就开始乱想：“哇，是不是可以拿来存环境配置？dev / prod / test 之类的？”

不，Environment 更强调的是 运行环境，例如：

• 主题（暗黑 / 亮色）
• 字体缩放
• 窗口尺寸变化
• 语言 / 区域

框架会在环境发生变化时自动通知相关依赖 UI 更新，你可以通过装饰器或相关 API 获取。

它更适合做：“适配型 UI”，而不是业务状态。

举个例子：
你要根据系统主题切换颜色方案，而不是自己在 AppStorage 里搞个 theme = 'dark' 再假装同步系统。

---

三、页面级 vs 全局状态：不要啥都往全局上怼

非常多 Bug，其实不是技术问题，是“状态颗粒度分不清”。

我们先来强行分一波类：

3.1 最该放在 AppStorage 里的那些状态 ✅

• 当前是否登录 isLogin

• 当前用户信息 userInfo

• 当前主题/主题配置 themeConfig

• 当前语言 currentLocale

• 全局配置，比如：

  • “是否显示新手引导”
  • “是否开启性能日志”

特征：

• 多个页面都要用
• 多个模块会依赖
• 改动后希望“全局同步刷新”

3.2 更适合 LocalStorage / 页面级状态的 🟡

• 某个页面内部的筛选条件
• 某个 Tab 页内部的 UI 状态
• 某个复杂组件树内部的共享状态（例如电商首页的筛选条件、排序方式、当前选中的分类等）

比如电商页面：

interface FilterState {
  keyword: string
  categoryId: number
  priceRange: [number, number]
  sortType: 'default' | 'priceAsc' | 'priceDesc'
}

这个状态你完全可以丢进 LocalStorage 而不是 AppStorage。

---

3.3 Environment 负责什么？

可以理解为：

当环境变了，你才能“被动”感知并适配 —— 它不是用来存你自己的业务字段的。

例如：

• @Watch('colorMode') → 有些组件跟着暗黑模式改
• UI 根据窗口宽度决定是“两列布局”还是“三列”

它的地位其实有点像：React 的 useMediaQuery + useTheme + useWindowSize 的合体。

---

3.4 一个综合例子：登录主题配置 + 页面筛选状态

想象你做一个带商品列表的 App：

• 全局：

  • 是否登录 → AppStorage
  • 当前主题 / 语言 → AppStorage / Environment

• 商品列表页内部：

  • 当前选中分类 → @State / LocalStorage
  • 当前分页页码 → @State
  • 当前筛选条件 → LocalStorage

原则：
能缩小作用域，就缩小；能页面解决，就别全局。

---

四、状态同步流程：从“状态源头”到“UI 刷新”的全链路

很多同学只知道：

“改个值，UI 会刷新。”

但真遇到 Bug 你就会问：“为什么有时候刷新，有时候不刷新？！”

ArkUI 状态模型的大致流程是这样👇（简化版）

1. 状态源定义

   • AppStorage.Set('key', value)
   • @State / @StorageProp / @StorageLink 等装饰器

2. 组件订阅

   • 某个组件声明：“我关心这个 key 的变化”

   • 比如：

     @StorageLink('isLogin') isLogin: boolean
     

3. 状态变更

   • 你在任意一处 this.isLogin = true 或 AppStorage.Set('isLogin', true)

4. ArkUI 触发响应式刷新

   • 框架检测到绑定此 key 的组件
   • 在合适的时机调度重新 build / 更新 UI

所以我们写代码时要想清楚：谁是源头？谁是订阅方？
不要出现这几种迷惑写法：

• 同一个字段，既用 @State 又用 AppStorage，互相覆盖
• 乱用 AppStorage.Get() 直接取，不用装饰器绑定，导致 UI 不更新
• 在一堆工具函数里面偷偷改 AppStorage，调试像捉鬼

---

4.1 推荐的“状态流”写法（Best Practice）

以全局登录状态为例，我们定义三层：

1. 状态初始化层（入口 / Ability）
2. 状态修改层（业务逻辑层：登录服务 / 用户中心）
3. UI 订阅层（各个页面组件）

① 初始化（入口处）

// UIAbility.onWindowStageCreate 或 App 启动位置
AppStorage.Set('isLogin', false)
AppStorage.Set('userProfile', null)

② 业务逻辑封装（UserService.ts）

export class UserService {
  static async login(phone: string, pwd: string): Promise<boolean> {
    // ... 调后端接口
    const ok = true // 示例
    if (ok) {
      AppStorage.Set('isLogin', true)
      AppStorage.Set('userProfile', { name: '张三', id: 1 })
    }
    return ok
  }

  static logout() {
    AppStorage.Set('isLogin', false)
    AppStorage.Set('userProfile', null)
  }
}

③ UI 层只订阅，不直接控制 AppStorage

@Entry
@Component
struct Root {
  @StorageLink('isLogin') isLogin: boolean

  build() {
    if (!this.isLogin) {
      LoginPage()
    } else {
      MainTab()
    }
  }
}

@Component
struct LoginPage {
  private phone: string = ''
  private pwd: string = ''

  async doLogin() {
    const ok = await UserService.login(this.phone, this.pwd)
    if (!ok) {
      // toast 提示
    }
  }
}

这样你的状态流就非常清晰：

入口初始化 → service 修改 → UI 只订阅

调试起来会比你在各个页面里乱改 AppStorage 好太多。

---

4.2 LocalStorage 状态同步的小套路

比如某个页面内部的过滤条件：

interface FilterState {
  keyword: string
  onlyInStock: boolean
}

@Entry
@Component
struct ProductPage {
  private ls = new LocalStorage()

  aboutToAppear() {
    this.ls.setOrCreate('filter', { keyword: '', onlyInStock: false })
  }

  build() {
    WithLocalStorage(this.ls) {
      Column() {
        FilterBar()
        ProductList()
      }
    }
  }
}

@Component
struct FilterBar {
  @LocalStorageLink('filter') filter: FilterState

  build() {
    Row() {
      TextField({ text: this.filter.keyword })
        .onChange(v => this.filter.keyword = v)

      Checkbox({ name: '仅看有货', selected: this.filter.onlyInStock })
        .onChange(v => this.filter.onlyInStock = v)
    }
  }
}

@Component
struct ProductList {
  @LocalStorageProp('filter') filter: FilterState

  build() {
    // 根据 filter 请求数据 or 过滤展示
  }
}

这样：

• FilterBar 改 filter → ProductList 自动拿到最新的 Filter
• 整个状态只在这个页面内部流转
• 不会污染全局

---

五、项目结构与配置：别把状态散落一地

讲完原理和流程，我们再落一点“项目工程化”的建议。
不然你虽然会用 AppStorage/LocalStorage/Environment，但项目越做越乱 🥲

5.1 建议的目录结构（仅示例）

entry/src/main/ets/
  app/
    AppInitializer.ts      # 全局状态初始化 & AppStorage 初始值
    EnvironmentConfig.ts   # 和 Environment 相关的适配逻辑
  services/
    user/UserService.ts    # 用户登录 / 退出 / token 处理
    settings/ThemeService.ts
    ...
  state/
    AppStateKeys.ts        # AppStorage 用到的 key 统一定义
    types/
      UserTypes.ts
      ThemeTypes.ts
  pages/
    login/
    home/
    product/
      ProductPage.ets      # 内部用 LocalStorage 共享状态
      FilterSection.ets
      ProductList.ets

5.2 AppStorage 相关的最佳实践 🌟

1. 所有 key 统一定义在一个地方

// AppStateKeys.ts
export const APP_STATE_KEYS = {
  IS_LOGIN: 'isLogin',
  USER_PROFILE: 'userProfile',
  THEME: 'theme',
  LOCALE: 'locale',
}

这样不会出现：
一会儿 'isLogin' 一会儿 'loginState'，改个 Key 直接血崩。

2. 不要在任何组件里随便 Set 未定义的 key

• 统一通过服务层 or 初始化文件管理
• 组件只绑定既有 key

3. 避免“工具函数 + AppStorage.Set() 到处乱写”

• 改状态的逻辑越集中，Bug 越好查

---

5.3 LocalStorage 使用规范 ✅

1. 仅在“页面根组件”创建 LocalStorage 实例

• 其它子组件都通过装饰器去用，不要各自 new
• 它应该被当作页面内部的“共享仓库”。

2. 类型定义清晰

interface ProductFilterState {...}
interface CartState {...}

不要全用 any / object，一旦页面复杂起来，你自己先迷糊。

---

5.4 Environment 相关配置

你可以单独做个环境适配模块，比如：

// EnvironmentConfig.ts
export function getThemeByEnv(): ThemeConfig {
  // 读取系统暗黑 / 亮色模式，返回对应主题
}

export function onEnvChange(callback: (env) => void) {
  // 监听 Environment 变化，如窗口变化、语言切换
}

然后在 App 入口统一处理：

• 系统主题变更 → 更新 AppStorage 的 theme → 全局联动
• 系统语言切换 → 触发 UI 更新

总之：Environment 是“外部环境 → App 的入口层”，不要直接混在各个页面里乱用。

---

最后一段心里话：状态管理写得乱，项目早晚会反噬你 🤷‍♂️

很多人刚上手鸿蒙 ArkUI，第一感觉都是：

“状态真香，写 UI 好顺手。”

等项目一上规模，再回过头一看：

• AppStorage 里塞了一大堆键：a,b,c,flag1,flag2
• LocalStorage 几乎没用，要么压根不知道有
• Environment 完全没管，该适配的一个没做
• 业务逻辑到处乱 Set，全局变量地狱

然后开始骂框架：“状态管理太难了”。

但其实，今天这 4 件事做好，你的状态管理基本就不怎么闹情绪了：

1. AppStorage 只放真正全局的状态
2. LocalStorage 用来管理页面/模块内部共享
3. Environment 负责“环境 → UI”这条通路，不要承载业务
4. 状态初始化 / 修改 / 订阅 分层设计，不要混在一起

如果觉得有帮助，别忘了点个赞+关注支持一下~
喜欢记得关注，别让好内容被埋没～