夜雨聆风别急着写页面，先把工程地图拿到手
很多新手打开一个华为鸿蒙系统项目，第一眼不是看到页面，而是被一堆目录和配置文件拦住了。更要命的是，如果这个项目用华为仓颉编程语言开发，你会同时看到鸿蒙应用配置，仓颉源码，构建脚本，资源目录，测试模块，感觉每个地方都像入口。
真正的学习顺序不是一上来就写一个按钮，而是先知道这个工程为什么能启动。你只要先把项目地图拿到手，后面再看页面，状态，路由，网络，都会顺很多。
一个仓颉鸿蒙项目，先看这棵树
一个最小可运行的仓颉鸿蒙工程，通常不是单个 `src` 目录，而是由应用级配置，模块级配置，仓颉源码，资源文件和构建工具共同组成。可以先把它想成一栋房子，根目录是地基，`AppScope` 是身份证，`entry` 是主入口，`resources` 是装修材料，仓颉源码是里面真正运转的房间。
MyApplication/ ├── build-profile.json5 ├── oh-package.json5 ├── hvigorfile.ts ├── AppScope/ │└── app.json5 ├── entry/ │├── build-profile.json5 │├── oh-package.json5 │├── cjpm.toml │└── src/ │└── main/ │├── cangjie/ ││├── ability_stage.cj ││├── index.cj ││└── main_ability.cj │├── module.json5 │└── resources/ └── hvigor/ └── hvigor-config.json5
先不要被文件数量吓到。新手第一轮只需要记住四层关系，应用是谁，模块在哪里，页面从哪里加载，资源从哪里取。
根目录负责搭舞台，不负责写业务
根目录的配置文件决定整个应用怎么构建，依赖怎么装，模块怎么被识别。这里最重要的是 `build-profile.json5`，`oh-package.json5` 和 `hvigorfile.ts`。
`build-profile.json5` 会告诉构建系统这个应用有哪些模块，默认模块通常叫 `entry`。`oh-package.json5` 管理鸿蒙侧依赖。`hvigorfile.ts` 则是 Hvigor 构建任务的入口。它们看起来不像业务代码，但少了它们，页面写得再漂亮也跑不起来。
{ "app": { "products": [ { "name": "default", "runtimeOS": "HarmonyOS" } ] }, "modules": [ { "name": "entry", "srcPath": "./entry" } ] }
读根目录时，不要试图把每个配置项都背下来。先确认它把 `entry` 模块挂进来了，再确认 SDK 和构建模式是否符合当前项目。
AppScope 是应用身份证
`AppScope/app.json5` 负责应用级信息，比如包名，版本号，应用图标和应用名称。它不关心某个按钮怎么画，也不关心某个页面怎么跳转，它回答的是一个更底层的问题，这个应用在系统里是谁。
{ "app": { "bundleName": "com.example.myapplication", "vendor": "example", "versionCode": 1000000, "versionName": "1.0.0", "icon": "$media:layered_image", "label": "$string:app_name" } }
新手常见的困惑是，为什么页面还没写，就要先管这些配置。原因很简单，鸿蒙应用不是一段孤立代码，它要被安装，被识别，被展示，被启动。`AppScope` 就是这些能力的全局入口。
entry 是主模块，也是你最常待的地方
大多数入门项目只有一个主模块，目录名通常就是 `entry`。它既有模块级配置，也有仓颉包管理文件，还包含真正的源码和资源。
`entry/build-profile.json5` 会配置这个模块怎样构建。`entry/cjpm.toml` 是仓颉包管理配置，告诉仓颉编译工具该从哪里找源码和依赖。`entry/src/main/module.json5` 则描述这个模块的类型，主 Ability，以及页面资源。
entry/ ├── build-profile.json5 ├── oh-package.json5 ├── cjpm.toml └── src/ └── main/ ├── cangjie/ ├── module.json5 └── resources/
你可以把 `entry` 理解成应用的主舞台。根目录把舞台搭起来，`AppScope` 说明应用身份，而 `entry` 才是你长期写页面，写状态，接业务能力的地方。
三个仓颉文件，串起应用启动链路
仓颉源码通常放在 `entry/src/main/cangjie` 下面。入门阶段最值得先看的，是 `ability_stage.cj`，`main_ability.cj` 和 `index.cj`。
`ability_stage.cj` 更偏应用阶段生命周期。`main_ability.cj` 继承 `UIAbility`，负责窗口创建和页面加载。`index.cj` 常常是入口页面，里面会出现 `@Entry` 和 `@Component`，也就是你最熟悉的界面声明式代码。
package ohos_app_cangjie_entry import kit.AbilityKit.* import kit.ArkUI.* class EntryAbility <: UIAbility { public override func onWindowStageCreate(windowStage: WindowStage): Unit { windowStage.loadContent('pages/Index') } }
这条链路特别关键。系统先创建 Ability，Ability 再创建窗口，窗口再加载页面。你理解了这个顺序，就不会把所有问题都归结为页面代码。
resources 不是边角料，它决定页面能不能像应用
`resources` 目录放的是字符串，颜色，图片，页面配置等资源。比如应用名可以放在 `string.json`，颜色可以放在 `color.json`，图标可以放在 `media`，页面列表可以放在 `profile/main_pages.json`。
很多初学者写 Demo 时会把文字，颜色，图片路径都直接塞进页面。小练习可以这样做，但真正进入 App 开发后，资源集中管理会让页面更稳定，也更容易适配。
resources/ └── base/ ├── element/ │├── string.json │└── color.json ├── media/ │├── layered_image.json │└── startIcon.png └── profile/ └── main_pages.json
从工程阅读角度看，资源目录能帮你判断页面里出现的名称，颜色，图标到底从哪里来。它不是最后才看的目录，而是理解页面表现的重要线索。
新手第一次打开工程，按这个顺序读
推荐顺序很简单，先看根目录确认构建和模块，再看 `AppScope/app.json5` 确认应用身份，然后进入 `entry` 看模块配置，接着看 `main_ability.cj` 找页面加载入口，最后看 `index.cj` 和资源目录。
如果你只看页面，很容易遇到一个现象，代码明明没有报错，应用却没有按预期启动。很多时候问题不在组件，而在模块配置，Ability 入口，页面路径或资源引用。先读工程结构，就是在给自己建立排查路线。
会看结构之后，写页面才不会迷路
仓颉鸿蒙项目的学习，不是从某个组件孤立开始，而是从“这个应用怎样被系统识别，怎样被构建，怎样加载窗口，怎样进入页面”开始。你把这条线理顺了，再去学 Text，Button，List，Navigation，状态管理，都会有落点。
新手最应该建立的不是背文件名的能力，而是看到一个目录就知道它在启动链路里负责什么。根目录负责构建舞台，`AppScope` 负责应用身份，`entry` 负责主模块，`main_ability.cj` 负责窗口和页面加载，`index.cj` 才是你真正写界面的地方。
先看懂工程长什么样，再开始写页面，这不是绕远路，而是在给后续开发打地基。
