前言在 ArkUI 中router.pushUrl/router.replaceUrl是页面跳转的核心 API但很多人会遇到「页面找不到」的错误原因往往是main_pages.json中漏注册了页面。本篇以小分享 App 的 16 个页面为例深入讲解路由表的配置与维护。详细 API 可参考 HarmonyOS Router 官方文档。一、完整配置1.1 main_pages.json 全文小分享 App 的entry/src/main/resources/base/profile/main_pages.json如下{ src: [ pages/Index, pages/SplashPage, pages/HomePage, pages/CreateSelectPage, pages/TextEditPage, pages/PreviewPage, pages/TemplateSelectPage, pages/ImageEditPage, pages/LinkEditPage, pages/SharePreviewPage, pages/FavoritesPage, pages/ProfilePage, pages/DiscoverPage, pages/TemplateDetailPage, pages/MoreFunctionsPage, pages/SettingsPage ] }1.2 文件结构整个文件只有一个src数组列出所有可访问的页面。每个路径必须以pages/开头且不带.ets后缀。提示DevEco Studio 新建 Page 时会自动追加到此文件但手动复制 Page 文件时务必同步更新。二、页面路径规则2.1 不带后缀pages/Index ✅ pages/Index.ets ❌src数组中的路径不需要.ets后缀系统会自动映射到entry/src/main/ets/pages/Index.ets。2.2 前缀必须为 pagespages/HomePage ✅ HomePage ❌ subpages/DetailPage ❌ArkUI 默认约定页面位于src/main/ets/pages/目录下路径前缀固定为pages/。2.3 子目录页面若把页面放在pages/profile/SettingsPage.ets则src数组需要写成src: [ pages/profile/SettingsPage ]跳转时也要带上完整路径router.pushUrl({ url: pages/profile/SettingsPage });三、跳转 API 对比3.1 四大路由 APIHarmonyOS 提供四种核心路由 APIAPI作用返回栈变化router.pushUrl入栈跳转新页面入栈router.replaceUrl替换当前页当前页销毁新页入栈router.back出栈返回当前页出栈router.clear清空栈全部出栈3.2 小分享 App 的典型用法小分享 App 的典型用法如下// SplashPage 跳到 HomePage用 replaceUrl避免返回时回到启动页 aboutToAppear(): void { setTimeout(() { router.replaceUrl({ url: pages/HomePage }); }, 2000); } // HomePage 跳到 TextEditPage用 pushUrl保留返回入口 router.pushUrl({ url: pages/TextEditPage }); // 编辑页返回上一级 router.back();3.3 路由选型建议路由选型建议如下启动页跳首页用replaceUrl避免返回启动页列表页跳详情页用pushUrl保留返回入口表单页跳成功页用replaceUrl避免返回修改底部 Tab 切换用replaceUrl避免路由栈膨胀四、main_pages.json 的两种生成方式4.1 方式 1DevEco Studio 自动注册在 DevEco Studio 中新建 Page 时IDE 会自动把页面路径追加到main_pages.json。这是最推荐的方式。4.2 方式 2手动维护某些场景下开发者会手动复制 Page 文件此时必须手动修改main_pages.json否则跳转会失败。提示建议在工程根目录配置 git pre-commit 钩子校验main_pages.json与实际 Page 文件的一致性。五、跳转失败的常见原因5.1 原因 1页面未注册router.pushUrl({ url: pages/NewPage }); // 报错page not found解决把pages/NewPage加入main_pages.json的src数组。5.2 原因 2路径大小写不匹配router.pushUrl({ url: pages/Homepage }); // ❌ 实际文件名是 HomePageHarmonyOS 路径区分大小写必须与文件名完全一致。5.3 原因 3路由栈溢出ArkUI 默认路由栈上限为 32。当页面深度过大时如无限详情页嵌套会出现The route stack cannot exceed 32 pages解决使用router.replaceUrl替代pushUrl或使用Navigation组件实现无限层路由。六、带参数跳转6.1 params 传递参数router.pushUrl支持params字段传递参数router.pushUrl({ url: pages/TemplateDetailPage, params: { templateId: ink-001, title: 水墨古风 } });6.2 目标页接收参数目标页通过router.getParams()获取aboutToAppear(): void { const params router.getParams() as Recordstring, string; this.templateId params.templateId; this.title params.title; }提示getParams()返回Object必须做类型断言否则在严格模式下会编译失败。七、本篇核心知识点7.1 main_pages.json 核心规则main_pages.json 核心规则总结如下路径不带后缀前缀固定为pages/子目录页面需带完整路径路径区分大小写7.2 路由 API 选型路由 API 选型建议如下pushUrl入栈跳转保留返回入口replaceUrl替换当前页避免返回back出栈返回clear清空栈7.3 实战开发要点实战开发中需要重点关注以下几个要点跳转失败通常是路径写错或漏注册复杂嵌套场景建议使用Navigation组件带参数跳转用params字段目标页用router.getParams()接收参数总结本文深入剖析了 HarmonyOS main_pages.json 路由表的配置规则结合小分享 App 的 16 个页面讲解了路径规范、跳转 API 对比、常见陷阱、带参数跳转等关键知识点。下一篇我们将看app.json5全局配置理解 bundleName、版本号等元数据。附录完整实现细节1. 核心 API 参考API作用说明本文涉及的核心 API功能实现参见华为官方文档2. 完整代码示例// 核心功能代码 // 详见正文中的完整实现3. 常见问题排查问题原因解决方案编译错误import 路径错误检查路径和 API 版本运行时异常参数不合法使用 try/catch 捕获性能问题主线程耗时操作使用异步 API4. 最佳实践错误处理完善使用 try/catch 包裹资源及时释放避免内存泄漏异步操作使用 async/await权限配置完整按需申请5. 完整代码文件索引文件路径说明本文涉及的代码文件见正文6. 实现要点总结核心实现要点API 的正确使用方法和参数说明完整的代码实现流程常见问题的排查方案性能优化和安全建议7. 总结本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。开发注意事项1. API 版本兼容性确保使用的 API 在目标 SDK 版本中可用。不同版本的 HarmonyOS 可能对 API 的支持有所不同建议查阅官方文档确认。2. 权限配置根据功能需求配置相应的系统权限。权限在 module.json5 中声明运行时通过 abilityAccessCtrl 申请。3. 错误处理所有异步操作使用 try/catch 包裹确保异常不会导致应用崩溃。错误信息通过 hilog 输出便于调试。4. 资源释放使用完毕后及时释放系统资源避免内存泄漏。例如文件操作后关闭文件句柄数据库操作后关闭 ResultSet。5. 性能优化避免在主线程执行耗时操作使用异步 API 处理耗时任务。大量数据渲染时使用 LazyForEach 懒加载。完整代码文件索引文件路径说明本文涉及的代码文件见正文核心 API 参考API/组件用途文档链接文中涉及的 API核心功能华为官方文档总结本文详细讲解了小分享 App 中对应功能的完整实现涵盖 API 使用、代码示例、常见问题、性能优化等核心知识点。通过本文的学习读者可以掌握 HarmonyOS 开发的完整流程。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力
