前言在 HarmonyOS 应用中每个页面要想被router或Navigation路由框架找到必须先在main_pages.json中注册。这个文件是 ArkUI 页面路由的“黄页“——系统通过它知道应用有哪些页面、它们的路径在哪里。本文以「猫猫大作战」的entry/src/main/resources/base/profile/main_pages.json为锚点讲解页面注册的完整规则、多页面扩展方案、与loadContent和router的协作关系。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–77 篇。本篇是阶段三第 78 篇。一、项目中的 main_pages.json1.1 当前配置{ src: [ pages/Index ] }当前「猫猫大作战」只有单个页面Index.ets所有游戏逻辑主菜单、游戏棋盘、暂停、游戏结束都在一个页面内通过if/else状态切换。1.2 路径映射main_pages.json 中声明的路径 ↓ pages/Index ↓ 实际文件entry/src/main/ets/pages/Index.ets ↓ loadContent(pages/Index) 或 router.pushUrl({ url: pages/Index })二、页面注册规则2.1 语法规则{ src: [ pages/Index, pages/Detail, pages/Settings/SettingsPage ] }规则说明示例路径相对 ets/相对于entry/src/main/ets/pages/Index不含文件扩展名不要写.ets✅pages/Index❌pages/Index.ets支持子目录可在 pages 下建子目录pages/Settings/SettingsPage支持多个页面注册所有需路由跳转的页面[pages/A, pages/B, ...]2.2 模块引用规则module.json5中引用main_pages.json{ module: { pages: $profile:main_pages } }$profile:main_pages指向resources/base/profile/main_pages.json。三、多页面扩展方案3.1 为猫猫大作战增加页面{ src: [ pages/Index, pages/Leaderboard, pages/Settings, pages/GameHistory, pages/About ] }对应的文件目录entry/src/main/ets/pages/ ├── Index.ets ← 主游戏页面 ├── Leaderboard.ets ← 排行榜页面 ├── Settings.ets ← 设置页面 ├── GameHistory.ets ← 游戏历史页面 └── About.ets ← 关于页面3.2 子目录组织对于大型应用使用子目录组织页面{ src: [ pages/Index, pages/game/GameBoard, pages/game/GameOver, pages/user/Login, pages/user/Profile, pages/shop/ShopMain, pages/shop/ItemDetail ] }目录结构pages/ ├── Index.ets ├── game/ │ ├── GameBoard.ets │ └── GameOver.ets ├── user/ │ ├── Login.ets │ └── Profile.ets └── shop/ ├── ShopMain.ets └── ItemDetail.ets四、通过 router 跳转4.1 pushUrl 基本用法// 从 Index 页面跳转到 Leaderboard 页面 import { router } from kit.ArkUI; router.pushUrl({ url: pages/Leaderboard, params: { pageTitle: 高分排行榜, defaultTab: 0 } });4.2 路由路径与 main_pages 的对应main_pages.json → pages/Leaderboard router.pushUrl → { url: pages/Leaderboard } loadContent → loadContent(pages/Leaderboard) 三者路径必须完全一致且都已在 main_pages.json 中注册。4.3 完整跳转示例// Index.ets — 排行榜按钮 Button( 排行榜) .onClick(() { router.pushUrl({ url: pages/Leaderboard, params: { fromGame: true, highScore: this.highScore } }); }) // Leaderboard.ets — 接收参数 Entry Component struct Leaderboard { State fromGame: boolean false; State highScore: number 0; aboutToAppear() { const params router.getParams() as Recordstring, Object; this.fromGame params?.[fromGame] as boolean ?? false; this.highScore params?.[highScore] as number ?? 0; } }五、与 Navigation 的配合如果使用 Navigation 而非 routermain_pages.json依然需要注册所有页面// Navigation 同样依赖 main_pages.json 的注册 Entry Component struct NavigationPage { private stack: NavPathStack new NavPathStack(); build() { Navigation(this.stack) { // NavBar 内容 } } // 跳转到 Leaderboard — 路径同样来自 main_pages.json goToLeaderboard() { this.stack.pushPath({ name: pages/Leaderboard, param: { fromGame: true } }); } }六、跨模块页面路由6.1 feature 模块的页面当应用有多个 HAP/HSP 模块时feature 模块也有自己的main_pages.json// ranking_feature/src/main/resources/base/profile/main_pages.json { src: [ pages/RankingMain, pages/PlayerDetail ] }6.2 跨模块跳转// 从 entry 模块跳转到 ranking_feature 模块的页面 import { common } from kit.AbilityKit; import { Want } from kit.AbilityKit; const want: Want { bundleName: com.maomaodazuozhan.game, abilityName: RankingAbility, parameters: { pageType: main } }; startAbility(want);七、常见踩坑7.1 坑一路径未注册就跳转// 错误url 在 main_pages.json 中不存在 router.pushUrl({ url: pages/NotFound }); // → 崩溃Cannot find page pages/NotFound解决方法在main_pages.json中添加对应路径{ src: [pages/Index, pages/NotFound] }7.2 坑二路径包含 .ets 扩展名// 错误 router.pushUrl({ url: pages/Index.ets }); // ❌ 多写了 .etsmain_pages.json和router中的路径都不能包含文件扩展名。7.3 坑三路径大小写不一致// main_pages.json { src: [pages/Leaderboard] } // router 中写成小写 router.pushUrl({ url: pages/leaderboard }); // ❌ 大小写不匹配ArkTS 文件名区分大小写路径必须精确匹配。八、主从页面注册设计8.1 单页应用 vs 多页应用模式页面数适用场景优点缺点单页猫猫大作战当前1游戏、工具类状态集中管理代码规模大难维护多页2-10大多数应用模块化、清晰页面间需传参复杂多页10电商、社交彻底解耦路由管理成本高8.2 推荐逐步拆分随着功能增加可以逐步从单页拆分为多页阶段 1当前pages/Index含全部逻辑 阶段 2pages/Index pages/Settings设置页面 阶段 3pages/Index pages/Settings pages/Leaderboard九、总结main_pages.json虽小当前仅 5 行但它是页面路由体系的基石——所有页面跳转都依赖它的注册。核心要点main_pages.json在resources/base/profile/目录下路径相对于ets/不要写.ets扩展名所有通过router/Navigation/loadContent访问的页面必须注册支持多页面列表和子目录组织多个 HAP 模块各自有独立的main_pages.json下一篇预告第 79 篇将深入router.pushUrl— 基础导航跳转的实现与参数传递。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源页面路由配置文档router API 参考main_pages.json 配置参考module.json5 pages 字段Navigation 路由架构开源鸿蒙跨平台社区第 77 篇app.json5 全局配置第 79 篇router.pushUrl 基础导航