�鸿蒙报错速查：Cannot find name 'AppStorageV2'，忘 import 编译就炸，根因 + 眜解法

报错原文

ERROR: 10505001 ArkTS Compiler Error
Error Message: Cannot find name 'AppStorageV2'. Did you mean to use 'import AppStorageV2 from "@ohos.arkui.StateManagement"' instead? At File: xxx.ets:N:N

报错触发场景

你写鸿蒙 ArkUI V2 应用级状态时，直接用 AppStorageV2 不 import 就炸：

// ❌ 报错写法
@Entry
@ComponentV2
struct Index {
  appCfg = AppStorageV2.connect(...)  ← 直接用，没 import
}

根因

鸿蒙 ArkTS 的 V2 装饰器 AppStorageV2 不是全局名 ------它定义在 @ohos.arkui.StateManagement 模块里，必须显式 import 才能用。

这跟 V1 的 AppStorage 不同------V1 的 AppStorage 是全局名（编译器内置），不用 import。新手从 V1 迁 V2 最容易踩这个坑：肌肉记忆直接用 AppStorageV2，编译就报「Cannot find name」。

ArkTS 这么设计的原因：V2 装饰器体系按 ES Module 规范设计------每个模块要显式 import，避免全局名污染。代价是多写一行 import，但模块化更清晰。

真解法

一种解法：显式 import

// ✅ 正解
import { AppStorageV2 } from '@ohos.arkui.StateManagement'

@ObservedV2
class AppConfig {
  @Trace theme: string = 'light'
  @Trace lang: string = 'zh'
}

@Entry
@ComponentV2
struct Index {
  appCfg: AppConfig = AppStorageV2.connect(AppConfig, 'appConfig', () => new AppConfig()) ?? new AppConfig()
}

import { AppStorageV2 } from '@ohos.arkui.StateManagement'------用 { } 解构单个装饰器，不是 import AppStorageV2。

真机配图：import 正解能编译能跑

import { AppStorageV2 } 后------正解，能编译能跑。改应用级可观察对象成员真触发 UI 重绘：

import 正解初始态（theme=light, lang=zh, n=0）：

点改 theme + 改 lang 后（theme=dark, lang=en, n=2，UI 重绘）：

报错写法（忘 import）编译就炸，装不上真机；正解写法（显式 import）能跑，改成员就重绘。忘 import 就炸，import 了就跑------这是 V2 装饰器非全局最直白的证据。

高频踩坑场景

场景 1：V1 AppStorage 是全局名，V2 AppStorageV2 不是

// V1 正确（全局名，不用 import）
AppStorage.set('theme', 'dark')

// V2 报错（不是全局名，要 import）
AppStorageV2.connect(...)  ← Cannot find name

// V2 正解
import { AppStorageV2 } from '@ohos.arkui.StateManagement'
AppStorageV2.connect(...)

场景 2：用 import AppStorageV2 而非 import { AppStorageV2 }

// ❌ 报错（AppStorageV2 是 named export，不是 default export）
import AppStorageV2 from '@ohos.arkui.StateManagement'

// ✅ 正解（用 {} 解构 named export）
import { AppStorageV2 } from '@ohos.arkui.StateManagement'

场景 3：PersistenceV2 也忘 import

// ❌ 报错（PersistenceV2 也在 @ohos.arkui.StateManagement 里）
PersistenceV2.globalConnect(...)

// ✅ 正解
import { PersistenceV2 } from '@ohos.arkui.StateManagement'
PersistenceV2.globalConnect(...)

场景 4：V2 装饰器体系全表

V2 装饰器都不是全局名，要 import：

// ✅ 全部从 @ohos.arkui.StateManagement import
import { AppStorageV2, PersistenceV2 } from '@ohos.arkui.StateManagement'

// 下面这些是 V2 装饰器但装在 struct 上不用 import（编译器内置）：
// @ComponentV2 / @Local / @Param / @Once / @Event / @Monitor / @Computed / @ObservedV2 / @Trace / @Provider / @Consumer

V2 装饰器	import 吗	来源
@ComponentV2 / @Local / @Param / @Once / @Event / @Monitor / @Computed	不用（编译器内置）	-
@ObservedV2 / @Trace	不用（编译器内置）	-
@Provider / @Consumer	不用（编译器内置）	-
AppStorageV2 / PersistenceV2	要 import	@ohos.arkui.StateManagement

铁律 ：struct 上装的 V2 装饰器（@Local/@Param 等）不用 import，但 class AppStorageV2/PersistenceV2 要 import。

一句话速查

Cannot find name 'AppStorageV2' → 忘 import，加 import { AppStorageV2 } from '@ohos.arkui.StateManagement'

跟 V1 AppStorage 的差异

维度	V1 AppStorage	V2 AppStorageV2
import	不用（全局名）	要 import
存取 API	set/get 键值对	connect 拿可观察对象
改成员触发重绘	不触发	触发（@Trace 装的成员）
配套	@StorageLink / @StorageProp	同 key connect 同对象

前端转鸿蒙或 V1 迁 V2 最容易踩这个坑------V1 AppStorage 不用 import 是全局名，V2 AppStorageV2 要 import。新项目从一开始就养成「V2 class 装饰器必 import」的习惯，避坑。

完整代码仓库

本文所有正解写法都已托管到 AtomGit：

🔗 仓库地址 ：atomgit.com/JaneConan/a...

仓库包含：

• 四种高频踩坑场景的 ❌ 报错写法 + ✅ 正解写法对照
• V2 装饰器「要 import / 不用 import」全表
• 可直接用 DevEco Studio 打开参考

---

作者：JaneConan 仓库：atomgit.com/JaneConan/a... 协议：Apache-2.0，随便用，别告我