【OpenHarmony/HarmonyOs 】HarmonyOS NEXT 工程配置详解app.json5、module.json5 与 main_pages.json HarmonyOS 项目能否安装、启动和跳转不只取决于 ArkTS 代码。应用级配置、模块级配置和页面清单共同描述了包名、设备类型、权限、Ability 与路由入口。一、三份配置各管什么AppScope/app.json5 └─ 整个应用包名、版本、图标、厂商 entry/src/main/module.json5 └─ entry 模块Ability、权限、设备、扩展能力 entry/src/main/resources/base/profile/main_pages.json └─ 当前模块可加载的 ArkUI 页面应用可以包含多个模块但包名和版本属于全局页面与 Ability 则属于具体模块。先理解层级再修改配置能够避免字段放错位置。系统从桌面图标进入 ArkUI 页面的完整链路可以概括为点击桌面图标 → app.json5 确认应用身份、名称和图标 →module.json5 根据 skills 找到 EntryAbility → srcEntry 加载EntryAbility.ets → onWindowStageCreate()调用 loadContent()→ main_pages.json 验证目标页面已经注册 → 构建 WelcomePage 或 HomePage因此“能安装但打开白屏”未必是 ArkUI 布局错误也可能是 Ability 路径、页面清单、资源引用或loadContent()目标不一致。二、应用级 app.json5{app: {bundleName:shan.lian.daohang,vendor:shan.lian.daohang,versionCode: 1000000,versionName:1.0.0,icon:$media:layered_image,label:$string:app_name} }bundleName它是应用的稳定身份必须与 AGC/AppGallery Connect 中登记的包名一致。发布后随意更换会被视为另一个应用也会影响签名、数据目录和云服务配置。versionCode 与 versionNameversionName面向用户例如 1.0.0versionCode用于系统判断升级顺序发布新版本时必须递增。不要只改显示版本而忘记内部版本号。资源引用$media:layered_image、$string:app_name引用资源而不是硬编码路径。系统可根据设备、语言和主题选择合适资源。常见资源引用包括$string:app_name字符串$color:start_window_background颜色$media:layered_image图片或分层图标$profile:main_pagesProfile 配置建议把版本概念也分清versionName面向用户versionCode判断升级顺序而本地数据的schemaVersion应独立维护。应用升级不一定修改数据格式数据迁移也不能只靠显示版本判断。三、模块类型与入口{module: {name:entry,type:entry,mainElement:EntryAbility,pages:$profile:main_pages} }type: entry表示这是应用入口模块mainElement指向主要 Ability。pages通过资源引用连接页面清单而不是直接在此写所有页面。模块还配置了deliveryWithInstall:true,installationFree:false前者表示模块随安装交付后者描述当前模块不是免安装形态。应用能够拉起元服务不代表应用自身就是元服务这两个概念不能混淆。未来若将 AI、工具箱拆成 feature 模块还要重新规划模块依赖和按需交付。四、声明支持的设备deviceTypes: [phone,tablet,2in1]声明支持并不代表 UI 已经完成适配。开发者仍要检查窗口断点、横竖屏、输入方式、信息密度和安全区。配置决定“允许运行”布局决定“是否好用”。设备重点检查手机底部手势区、两列 Grid、单手操作平板三至四列布局、横屏、内容最大宽度2in1键鼠焦点、窗口缩放、悬停反馈五、网络权限requestPermissions: [ {name:ohos.permission.INTERNET} ]LinkOS 需要请求搜索建议和加载网页因此必须声明网络权限。权限应遵循最小化原则未使用的位置、相机、麦克风不要提前申请。涉及用户授权的权限还需要运行时请求和拒绝后的降级路径。权限设计可以连续追问三个问题是否真的需要、应在什么时机申请、用户拒绝后如何降级。例如模拟语音搜索不应提前申请麦克风真实语音功能也应在用户点按麦克风时再申请并在拒绝后保留文字搜索。六、UIAbility 配置abilities: [ {name:EntryAbility,srcEntry:./ets/entryability/EntryAbility.ets,icon:$media:layered_image,label:$string:EntryAbility_label,startWindowIcon:$media:startIcon,startWindowBackground:$color:start_window_background,exported:true,skills: [ {entities: [entity.system.home],actions: [ohos.want.action.home] } ] } ]srcEntry必须与源码路径一致启动窗口图标和背景决定 ArkUI 首帧构建前的过渡画面skills声明它可以作为桌面入口启动。exported会影响组件是否可被其他应用访问。能设为 false 的组件不要公开公开组件要验证传入 Want避免把外部参数当可信数据。启动窗口会在 ArkUI 首帧完成前显示。为了减少视觉闪烁startWindowBackground应接近首屏背景启动图标尺寸应稳定。Preferences 初始化属于首屏决策所需操作可以在 Ability 中等待天气、推荐和 AGC 非关键请求则应延后异步执行。skills不只是桌面声明。未来若增加 Deep Link、分享接收或文件打开也需要对应 action/entity并在 Ability 中校验 Want 参数的类型、长度和协议。外部入口越多攻击面越大。七、页面清单{ src: [pages/v2/WelcomePage,pages/v2/HomePage,pages/v2/MiniAppPage,pages/v2/AIAssistantPage,pages/v2/MinePage,pages/v2/WebViewPage] }新增.ets页面后还要加入清单。常见问题包括路径大小写不一致、移动文件后未更新清单、路由使用旧目录、把不带Entry的普通组件误当页面。项目仍保留 v1 源码但当前清单只登记 v2 生产页面。这可以避免旧页面继续进入正式路由。路由字符串还可以集中管理exportclassAppRoutes {staticreadonlyWELCOME pages/v2/WelcomePage;staticreadonlyHOME pages/v2/HomePage;staticreadonlyWEB pages/v2/WebViewPage; }常量减少业务代码中的拼写错误但最终仍要与main_pages.json同步。八、扩展能力项目注册了备份扩展extensionAbilities: [ {name:EntryBackupAbility,srcEntry:./ets/entrybackupability/EntryBackupAbility.ets,type:backup,exported:false,metadata: [ {name:ohos.extension.backup,resource:$profile:backup_config} ] } ]扩展能力由系统在特定场景调度不等同于普通 UI 页面。exported: false也符合内部系统能力的最小暴露原则。当前备份 Ability 只记录回调日志因此配置代表“已注册能力骨架”不是“收藏已经完成备份”。真正落地还需要定义数据范围、快照版本、恢复校验和失败回滚。九、构建配置之间的一致性还要检查build-profile.json5中 targetSdkVersion、compatibleSdkVersion、产品和签名配置。SDK 版本、使用的 API 和设备系统不匹配时可能出现编译成功但安装失败或使用了目标版本不可用接口。项目还启用了严格检查strictMode:{caseSensitiveCheck:true,useNormalizedOHMUrl:true}大小写检查可以提前暴露路径问题规范化 OHM URL 有助于统一模块导入。遇到错误时应修正真实路径不应为了短期通过构建而关闭严格模式。十、AGC、签名与环境一致性接入 AGC 时控制台应用、bundleName、签名材料与agconnect-services.json必须属于同一个项目。常见错误包括下载了另一个应用的配置、debug/release 签名不匹配、修改包名后没有重新配置云服务以及把示例文件当成真实配置。需要特别强调agconnect-services.json是客户端识别 AGC 项目的配置不是保存第三方私密密钥的地方。DeepSeek 等服务密钥仍应只存在于云函数环境变量。建议区分构建环境Debug开发签名、测试服务地址、详细诊断日志Release正式签名、正式地址、受控日志、混淆任何环境都不能把真实业务密钥硬编码进源码。十一、四类常见故障1. router 提示页面不存在检查页面是否登记、路径是否误加.ets、大小写是否一致以及页面移动后是否仍使用旧路由。2. 安装后无法从桌面启动检查mainElement、Ability 的name/srcEntry、home skill 和签名不要只检查页面 build 方法。3. 网络接口全部失败依次检查 INTERNET 权限、HTTPS 地址、设备网络、证书和服务域名。声明权限并不能解决证书或接口错误。4. 模拟器正常真机无法安装重点检查签名、Profile、设备系统版本、SDK 兼容范围和 bundleName。十二、排错顺序 ✅确认 JSON5 语法和尾逗号检查资源名是否真实存在检查 Ability 名称与srcEntry检查页面是否登记检查 bundleName 与 AGC 配置检查 SDK、签名与设备版本清理构建缓存后重新同步查看 hilog 中的明确错误码。十三、发布前检查表bundleName 与 AGC 控制台完全一致versionCode 已递增versionName 展示正确图标、应用名和启动背景使用正式资源删除未使用权限所有生产页面已登记v1 页面未暴露Ability 的 exported 符合最小权限SDK 与目标真机匹配release 签名和 Profile 正确AGC 文件属于正式项目且没有业务密钥release 包完成冷启动、路由、网络和备份回调验证。十四、总结app.json5定义应用身份module.json5描述模块能力main_pages.json注册页面入口构建配置再决定 SDK 与签名。把这几层关系理顺权限、路由、Ability、备份和多设备支持才会形成完整工程而不是一组互不理解的配置文件。✅