零基础开发第一个HarmonyOS APP：从环境搭建到上架全攻略

张

张建站

2026/6/2 6:14:02

10分钟阅读

零基础开发第一个HarmonyOS APP从环境搭建到上架全攻略引言为什么选择HarmonyOS2024年HarmonyOS设备数量已突破8亿台成为全球发展最快的智能终端操作系统。对于开发者而言这意味着一个全新的蓝海市场——一个与Android/iOS并行的第三大移动生态正在形成。但更吸引人的是HarmonyOS的开发体验统一的ArkTS语言、声明式UI开发范式、以及“一次开发多端部署”的核心理念。本文将带你从零开始3小时内完成第一个HarmonyOS应用并上架到华为应用市场。第一章DevEco Studio安装与配置详解1.1 系统要求与前期准备在开始之前请确保你的开发环境满足以下要求项目最低要求推荐配置操作系统Windows 10 64位 / macOS 10.14 / Ubuntu 18.04Windows 11 / macOS 12内存8GB RAM16GB RAM 或更高存储空间20GB 可用空间50GB SSDJava环境JDK 17JDK 17 或更高第一步安装JDK 17# 检查当前Java版本java-version# 如果没有安装JDK 17从官网下载# https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html# 安装后配置环境变量Windows示例# 1. 新建系统变量JAVA_HOME C:\Program Files\Java\jdk-17# 2. 在Path中添加%JAVA_HOME%\bin# 验证安装javac-version1.2 下载与安装DevEco StudioDevEco Studio是华为官方提供的HarmonyOS应用开发IDE基于IntelliJ IDEA构建专为鸿蒙生态优化。下载地址https://developer.harmonyos.com/cn/develop/deveco-studio安装步骤Windows版为例选择安装路径建议使用默认路径确保路径中无中文字符C:\DevEcoStudio\配置安装选项☑ 创建桌面快捷方式☑ 将DevEco Studio添加到Path环境变量☑ 关联.hvigor和.hap文件安装HarmonyOS SDK首次启动时IDE会自动检测并提示安装HarmonyOS SDK# SDK配置推荐初学者版本SDK版本:HarmonyOS 4.0.0 (API 9)Node.js:16.19.1 或更高版本Ohpm包管理工具:1.0.0 或更高版本构建工具:Hvigor 2.0.01.3 配置开发环境安装完成后需要进行必要的配置步骤1登录华为开发者账号// 如果没有账号先注册// https://developer.huawei.com/consumer/cn/// 在DevEco Studio中登录// 1. 点击右上角头像图标// 2. 选择登录// 3. 使用华为开发者账号登录步骤2配置SDK路径文件(File) → 设置(Settings) → 外观和行为(Appearance Behavior) → 系统设置(System Settings) → HarmonyOS SDK步骤3安装必要插件推荐安装的插件:-Chinese (Simplified) Language Pack:中文语言包-ArkTS Assistant:ArkTS语言支持-Git Integration:Git集成-Markdown Support:Markdown支持步骤4配置模拟器可选但推荐# 如果开发机性能足够建议安装本地模拟器# 路径工具(Tools) → 设备管理器(Device Manager)推荐模拟器配置 - Phone: Huawei P60 Pro(HarmonyOS4.0)- Tablet: MatePad Pro(HarmonyOS4.0)- 内存分配: 4GB RAM - 存储: 64GB第二章Hello World项目创建与模拟器调试2.1 创建第一个HarmonyOS项目步骤1新建项目项目配置详情:-项目模板:Empty Ability (空Ability)-项目名称:FirstHarmonyApp-包名:com.yourname.firstharmonyapp-保存路径:C:\Users\YourName\HarmonyOSProjects\-编译API版本:9 (HarmonyOS 4.0)-模型:Stage (推荐)-启用Super Visual:否 (初学者建议先用代码)-语言:ArkTS步骤2项目结构解析创建完成后你会看到以下项目结构FirstHarmonyApp/ ├── AppScope/ # 应用全局资源 │ ├── resources/ # 多语言、多分辨率资源 │ └── app.json5 # 应用级配置 ├── entry/ # 主模块 │ ├── src/ │ │ ├── main/ │ │ │ ├── ets/ # ArkTS代码目录 │ │ │ │ ├── entryability/ │ │ │ │ │ └── EntryAbility.ts # 应用入口 │ │ │ │ └── entryability/ │ │ │ │ └── pages/ │ │ │ │ └── Index.ets # 首页 │ │ │ ├── module.json5 # 模块配置 │ │ │ └── resources/ # 模块资源 │ │ └── ohosTest/ # 测试代码 │ └── build-profile.json5 # 模块构建配置 ├── build-profile.json5 # 工程构建配置 └── hvigorfile.ts # 构建脚本2.2 编写第一个页面Hello HarmonyOS让我们修改首页代码创建一个简单的计数器应用// entry/src/main/ets/pages/Index.etsEntryComponentstruct Index{Statemessage:string你好鸿蒙Statecount:number0// 自定义弹窗控制器StatedialogController:CustomDialogControllernewCustomDialogController({builder:CustomDialogExample({}),cancel:this.onCancelClick,autoCancel:true})build(){Column({space:20}){// 标题Text(this.message).fontSize(30).fontWeight(FontWeight.Bold).fontColor(#007DFF)// 计数器显示Text(当前计数: this.count).fontSize(24).fontColor(#182431).margin({top:20})// 计数器进度条Progress({value:this.count%100,total:100,type:ProgressType.Ring}).width(100).height(100).margin({top:20,bottom:20})// 按钮容器Row({space:15}){// 增加按钮Button(增加,{type:ButtonType.Capsule}).backgroundColor(#007DFF).width(100).height(40).onClick((){this.countthis.showToast(计数增加: this.count)})// 减少按钮Button(减少,{type:ButtonType.Capsule}).backgroundColor(#FF6B81).width(100).height(40).onClick((){if(this.count0){this.count--this.showToast(计数减少: this.count)}})}.margin({top:20})// 重置按钮Button(重置,{type:ButtonType.Normal}).backgroundColor(#34C759).width(150).height(40).margin({top:20}).onClick((){this.dialogController.open()})// 更多功能按钮Column({space:10}){Button(显示设备信息).width(200).height(40).backgroundColor(#8E8E93).onClick((){this.showDeviceInfo()})Button(切换主题).width(200).height(40).backgroundColor(#AF52DE).onClick((){this.toggleTheme()})}.margin({top:30})}.width(100%).height(100%).justifyContent(FlexAlign.Center).padding(20)}// 显示Toast提示privateshowToast(message:string){// 使用系统提示prompt.showToast({message:message,duration:2000})}// 显示设备信息privateshowDeviceInfo(){try{constsystemInfodeviceInfo.getDeviceInfo()this.dialogControllernewCustomDialogController({builder:DeviceInfoDialog({info:systemInfo}),autoCancel:true})this.dialogController.open()}catch(error){this.showToast(获取设备信息失败)}}// 切换主题示例功能privatetoggleTheme(){this.showToast(主题切换功能开发中...)}// 取消对话框privateonCancelClick(){console.log(对话框取消)}}// 自定义对话框组件Componentstruct CustomDialogExample{controller:CustomDialogControllerbuild(){Column({space:10}){Text(确认重置计数器).fontSize(18).fontWeight(FontWeight.Medium).margin({bottom:20})Row({space:20}){Button(取消).width(100).onClick((){this.controller.close()})Button(确认).width(100).backgroundColor(#007DFF).onClick((){// 这里应该重置计数器的逻辑// 由于是示例仅关闭对话框this.controller.close()prompt.showToast({message:计数器已重置})})}}.padding(20).backgroundColor(Color.White).borderRadius(10)}}// 设备信息对话框Componentstruct DeviceInfoDialog{privateinfo:deviceInfo.DeviceInfobuild(){Column({space:10}){Text(设备信息).fontSize(20).fontWeight(FontWeight.Bold).margin({bottom:15})// 设备信息列表ForEach(Object.keys(this.info),(key:string){Row(){Text(key:).fontSize(14).fontColor(#666666).width(120).textAlign(TextAlign.Start)Text(this.info[key].toString()).fontSize(14).fontColor(#182431).textAlign(TextAlign.Start).layoutWeight(1)}.width(100%).margin({bottom:8})})Button(关闭).width(120).margin({top:20}).onClick((){// 关闭逻辑由父组件处理})}.padding(20).backgroundColor(Color.White).borderRadius(10).width(80%)}}2.3 配置应用基本信息修改应用配置文件添加必要的权限和配置// entry/src/main/module.json5 { module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ts, description: $string:EntryAbility_desc, icon: $media:icon, label: $string:EntryAbility_label, startWindowIcon: $media:icon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ], requestPermissions: [ { name: ohos.permission.INTERNET } ] } }// AppScope/app.json5 { app: { bundleName: com.yourname.firstharmonyapp, vendor: yourname, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name, distributedNotificationEnabled: true, supportBackup: false, associatedWakeUp: false } }2.4 运行与调试应用方法1使用远程模拟器推荐点击工具栏的运行按钮▶️选择Sign in登录华为开发者账号选择设备类型如Phone选择远程模拟器如HUAWEI P60 Pro等待模拟器启动并运行应用方法2使用本地模拟器# 如果本地模拟器已安装# 1. 工具(Tools) → 设备管理器(Device Manager)# 2. 选择本地模拟器# 3. 启动模拟器首次启动较慢# 4. 运行应用到本地模拟器方法3使用真机调试真机调试步骤:1. 手机开启开发者模式:-设置 → 关于手机 → 连续点击版本号7次2. 开启USB调试:-设置 → 系统和更新 → 开发人员选项 → USB调试3. 连接电脑:-使用原装USB数据线4. 信任电脑:-手机弹窗选择信任此计算机 5. 在DevEco Studio中运行到真机调试技巧// 使用console.log输出日志console.log(当前计数:,this.count)// 使用debugger设置断点debugger// 代码会在此处暂停// 查看组件树和状态// 在DevTools中: Components → 查看组件层次结构// 在DevTools中: Console → 查看日志输出第三章应用签名与华为应用市场发布流程3.1 申请开发者资质在发布应用前需要完成开发者实名认证步骤1注册华为开发者账号访问https://developer.huawei.com/consumer/cn/ 点击注册 → 填写信息 → 完成邮箱验证步骤2完成实名认证个人开发者:-身份证正反面照片-手持身份证照片-手机号验证企业开发者:-营业执照-对公账户验证-法人身份证-联系人信息步骤3签署开发者协议在开发者平台 → 管理中心 → 协议签署阅读并同意《华为应用市场开发者协议》3.2 生成应用签名证书HarmonyOS应用必须使用华为的数字证书进行签名后才能发布方法1通过DevEco Studio自动生成推荐// 步骤// 1. 点击菜单: 文件(File) → 项目结构(Project Structure)// 2. 选择: Project → Signing Configs// 3. 点击添加签名配置(Add Signing Config)配置示例:-证书文件类型:HarmonyOS Application-存储路径:C:\Users\YourName\firstharmonyapp.p7b-存储密码:设置复杂密码8位以上-密钥别名:key0-密钥密码:设置密钥密码-有效期:25年默认-证书颁发者:个人/公司名称-国家代码:CN方法2命令行生成证书# 使用Java keytool工具生成证书keytool-genkeypair-aliaskey0-keyalgRSA-keysize2048\-validity9125-keystorefirstharmonyapp.p12\-storetypepkcs12-storepassyourpassword\-dnameCNYourName, OUYourOrgUnit, OYourOrg, LYourCity, SYourState, CCN# 转换为HarmonyOS需要的P7B格式# 需要使用华为提供的工具进行转换重要提示妥善保管签名证书和密码丢失无法找回建议将证书备份到安全位置企业应用建议使用企业证书3.3 配置应用签名在项目中配置签名信息// entry/build-profile.json5 { app: { signingConfigs: [ { name: release, material: { certpath: firstharmonyapp.p7b, storePassword: your_store_password, keyAlias: key0, keyPassword: your_key_password, profile: firstharmonyapp.p7b, signAlg: SHA256withECDSA, storeFile: firstharmonyapp.p7b } } ], products: [ { name: default, signingConfig: release, compileSdkVersion: 9, compatibleSdkVersion: 9, runtimeOS: HarmonyOS } ] } }3.4 构建发布版本步骤1配置构建类型# 在DevEco Studio中# 1. 点击菜单: 构建(Build) → 构建HAP/APP(s)# 2. 选择构建变体: release# 3. 等待构建完成步骤2检查构建产物构建完成后在项目目录中会生成build/ ├── outputs/ │ └── default/ │ ├── entry-default-signed.hap # 签名后的HAP包 │ ├── entry-default-unsigned.hap # 未签名的HAP包 │ └── app/ │ └── firstharmonyapp.app # APP包步骤3验证HAP包# 使用hdc工具检查HAP包hdc appinstallentry-default-signed.hap# 或在模拟器中手动安装# 1. 将HAP包复制到模拟器# 2. 在模拟器中点击安装3.5 提交应用到华为应用市场步骤1登录AppGallery Connect访问https://developer.huawei.com/consumer/cn/service/josp/agc/index.html 使用开发者账号登录步骤2创建应用应用信息填写:-应用名称:我的第一个鸿蒙应用-应用分类:工具 / 效率-默认语言:简体中文-应用类型:应用-是否上架:是-安装包类型:HarmonyOS应用 (HAP)步骤3上传应用包点击添加版本上传构建的HAP文件填写版本信息设置版本更新说明步骤4填写应用详情需要准备的材料: 1. 应用图标: 512x512像素PNG格式 2. 应用截图: 至少3张16:9比例 3. 应用描述: 详细功能介绍 4. 关键词: 3-5个相关关键词 5. 隐私政策: 如果应用需要权限 6. 客服信息: 邮箱或联系方式步骤5提交审核审核流程时间:-普通审核:3-5个工作日-加急审核:1-2个工作日需符合条件-修改后重新提交:1-3个工作日步骤6查看审核结果审核状态说明: - 审核中: 应用正在审核 - 待修改: 需要修改后重新提交 - 审核通过: 可以上架 - 审核拒绝: 查看拒绝原因3.6 应用上架后的运营监控应用数据// 集成华为分析服务可选// 在项目中添加依赖// ohpm install ohos/hianalyticsimporthiAnalyticsfromohos/hianalytics// 初始化hiAnalytics.init(context,{collectAdsIdEnabled:false,channel:AppGallery})// 记录用户行为hiAnalytics.onEvent(button_click,{button_name:increase_button,page_name:main_page})更新应用版本// 更新app.json5中的版本号 { app: { versionCode: 1000001, // 比上一个版本大 versionName: 1.0.1, // 语义化版本 } }第四章常见问题与解决方案4.1 环境配置问题问题1DevEco Studio启动失败解决方案:1. 检查Java环境:java-version2. 清理缓存: 删除用户目录下的.DevEcoStudio目录3. 重新安装: 使用卸载工具完全卸载后重装问题2模拟器无法启动解决方案:1. 检查网络: 确保可以访问华为云服务2. 检查账号: 确认已登录开发者账号3. 切换模拟器: 尝试其他型号的模拟器4. 使用真机调试: 作为临时替代方案4.2 开发问题问题3页面布局异常// 常见原因父容器高度未设置Column(){// 子组件}.height(100%)// 添加高度.width(100%)问题4真机调试失败解决方案:1. 检查USB连接:更换数据线或USB端口2. 检查开发者选项:确认USB调试已开启3. 重新授权:断开重连重新授权电脑4. 检查驱动:安装最新的华为手机驱动4.3 发布问题问题5应用审核被拒常见原因及解决方案: 1. 权限过度申请: 只申请必要的权限 2. 隐私政策缺失: 添加完整的隐私政策链接 3. 应用描述不清晰: 详细描述应用功能 4. 截图不符合要求: 按要求重新制作截图 5. 应用存在崩溃: 彻底测试后再提交