夜雨聆风仓颉鸿蒙新手最该避开的 5 个误区
学华为仓颉编程语言做华为鸿蒙系统应用，真正卡住新手的，往往不是什么高深语法，而是几个没人提前告诉你的小误区。它们藏在第一行代码里、藏在一个看似正常的长度统计里、藏在你以为写对了的配置里，一脚踩进去就是半天找不到原因。
今天把最高频的 5 个误区一次说清楚：包声明、字符串、状态、路径、构建。每一个我都帮你点出「错在哪」和「该怎么做」，看完能帮你省下大把抓狂的时间。
误区一：以为第一行的 package 随便写
很多人照着模板敲，第一行的 `package` 看都不看。但仓颉有条硬规矩：包声明必须和该文件相对 `src/` 的目录路径严格匹配，而且必须是文件里第一个非空、非注释的行。
// src/network/http/client.cj package default.network.http// 必须和目录路径对上
目录是 `network/http`，包名就得是 `default.network.http`。写成别的，编译器立刻报「包名和路径不一致」。这是新手第一天最常见的卡点，记住一句话：包名跟着目录走，别自己瞎起名。
误区二：用 .size 统计中文长度
这个误区特别隐蔽，因为它在英文下「看起来是对的」。你想知道一个字符串有多长，顺手就写了 `.size`。
let name = "你好世界" name.size// 拿到的是字节数，不是 4 name.toRuneArray().size// 这才是字符数 4
问题在于，`.size` 返回的是字节长度。一个中文字符通常占多个字节，所以你用 `.size` 去数中文，结果会大得离谱。正确做法是先转成 Rune 数组，再取 `.size`。凡是涉及中文的长度统计、截断、校验，都要用 `toRuneArray`，否则迟早出问题。
误区三：改了数据，页面却纹丝不动
你写了个计数器，点一下让数字加一，逻辑明明没错，可屏幕上的数字就是不变。这几乎是每个新手都会遇到的「灵异事件」。
@State var count: Int64 = 0
原因是：ArkUI 是声明式 UI，界面靠状态变量驱动刷新。你改的那个变量如果没用 `@State` 修饰，框架根本不知道它变了，自然不会重画界面。记住，凡是「一变就要刷新界面」的数据，都得用 `@State` 这类状态修饰。这不是可选项，是声明式 UI 的运行机制。
误区四：把文字、图片路径硬写死
做页面时，新手习惯把文字直接写在代码里、把图标路径写成固定字符串。短期能跑，但一旦要改文案、做多语言、换主题，就得满工程翻。
{ "label": "$string:app_name", "icon": "$media:layered_image" }
华为鸿蒙系统的正确做法是走资源引用：文字放进 `string.json`，用 `$string:` 引用；图片放进资源目录，用 `$media:` 引用。这样资源和代码分离，改文案、换图、做适配都只动资源文件。一开始就养成这个习惯，后面省事太多。
误区五：构建一报错就慌，其实先看名字对不对
最后一个，是构建环节。新手遇到构建失败，第一反应是怀疑环境、怀疑工具，到处乱试。其实很大一部分构建错误，根源是名字没对上。
[package] name = "ohos_app_cangjie_entry"
`cjpm.toml` 里的 `name`、`module.json5` 里 `srcEntry` 引用的包名、`build-profile.json5` 里模块的 `name`，这几处必须彼此一致、并和目录对得上。任何一处对不上，构建就可能失败。所以构建报错别急着重装环境，先回头核对这几个名字，命中率最高。
这 5 个误区背后，其实是同一件事
回头看，这 5 个误区看着五花八门，但本质是一回事：仓颉鸿蒙开发里，很多东西是有约定的，名字要对应、长度要按字符算、状态要显式声明、资源要走引用、配置要保持一致。新手出问题，多半是把这些约定当成了「随便写写」。
把这 5 条记在心里，你的前几个工程会顺很多。开发这件事，越早知道这些约定，越早能把精力放在真正有意思的功能上。
