简介面向HarmonyOS初学者的鸿蒙5.0系统app开发入门Demo是一套从项目初始化到部署的完整示例工程涵盖源码、配置文件、构建脚本与说明文档。压缩包共445个文件以js、json、ts、ets、json5等源码与配置为主辅以md说明、png示意图、hap安装包等整体大小仅1.84MB便于快速下载与解压。文件类型覆盖代码格式化.clang-format、Git忽略规则、依赖锁文件、构建配置、代码规范检查、项目元数据以及hvigor构建脚本系统展示了鸿蒙应用开发中环境配置、依赖管理、静态检查与构建打包的关键环节。通过阅读与实践这些配置和示例代码开发者可以理解鸿蒙5.0应用目录结构、ArkTS页面编写方式、模块间依赖关系及部署流程并能在此基础上快速搭建自己的开发环境完成Demo运行。已有453人学习下载适合零基础或刚接触鸿蒙生态的开发者作为入门参考。 直接说个现象最近我身边好几个做Android的朋友开始碰鸿蒙他们的第一反应都是“先把老项目用鸿蒙跑起来”。结果无一例外全卡在第一步——连Hello World都起不来。原因倒不复杂大家都把鸿蒙开发想得太接近安卓了实际上HarmonyOS NEXT从工程模型、开发语言到构建产物几乎整个链路都是另一套玩法。这篇博客就是写给这些准备入坑鸿蒙5.0、但又不知道从哪下手的开发者的我会用一个小Demo串起从环境准备、工程创建、UI基础到打包构建的完整路径把容易踩的坑提前标出来。1. 开发前的第一课HarmonyOS NEXT与开源鸿蒙不是同一个东西1.1 先搞清楚你写的是什么系统不少第一次接触鸿蒙的人会去搜“开源鸿蒙PC版下载”“鸿蒙模拟器电脑版”结果下载回来发现根本跑不了DevEco Studio创建的工程然后一头雾水。这里必须先掰开一个概念HarmonyOS NEXT也就是常说的“纯血鸿蒙”5.0对应的是这个版本和OpenHarmony开源鸿蒙是两个层次的东西。OpenHarmony是开源底座相当于一个操作系统的内核级项目主要面向设备厂商和底层开发者一般开发者接触不到太多拿它搭桌面系统、移植到其它硬件那是另一条技术路线。HarmonyOS NEXT是华为基于OpenHarmony打造的商业发行版我们普通应用开发者用DevEco Studio开发、跑在华为手机/平板/车机上的就是这个系统。它在OpenHarmony之上增加了完整的应用框架、SDK、HMS Core能力和上架分发体系。所以后面所有操作都默认你用的是HarmonyOS NEXT的开发环境真机也建议直接用华为手机兼容性和调试体验远好于模拟器。1.2 别再想着套安卓开发模式我见过很多“五年Android开发经验”的人上手鸿蒙时心态崩核心原因就是过往经验不仅帮不上忙反而会形成阻碍。HarmonyOS NEXT从5.0开始已经完全不兼容Android APK这意味着不能用Java/Kotlin直接写应用得用ArkTS——基于TypeScript扩展的语言初看像TS但UI描述、状态管理、组件通信模型都跟Android的XMLActivity那套思路完全不同。没有Activity/Fragment、没有Gradle、没有AndroidManifest.xml取而代之的是Stage模型、module.json5、hvigor构建系统。构建产物不是APK而是HAPHarmonyOS Ability Package一个应用包由多个HAP组成这一点和“安装一个APK”的思路差异很大。如果没有在动手前建立这套认知后面每写一行代码都会产生“这为什么要这样”的疑问。我的建议是把过往的移动端经验当作底层素养但不要试图把安卓的知识映射到鸿蒙上直接按鸿蒙自己的生态来学反而是最快的。2. 工具链硬核准备DevEco Studio与模拟器的搭配方案2.1 DevEco Studio的版本千万别装错做鸿蒙开发绕不开的IDE是DevEco Studio它是基于IntelliJ IDEA定制的。这里有个特别容易踩的坑版本与HarmonyOS NEXT版本需要匹配。如果你用的是HarmonyOS 5.0的手机最好下载DevEco Studio 5.0及以上版本并且配套的HarmonyOS SDK也要在SDK Manager里拉到对应版本。我见过一个朋友手上有台HarmonyOS 4.2的旧手机又下载了5.0的IDE结果工程编译没问题跑到真机上提示“SDK版本与设备不兼容”。后来查了文档才知道API版本和系统版本必须对应4.2对应API 115.0对应API 12/13错一个版本都可能出问题。具体版本对应关系建议安装时直接看官方文档最新表格这里给一个大概参考以当前主流版本为例系统版本API版本DevEco Studio最低版本HarmonyOS 4.2API 114.xHarmonyOS 5.0API 125.0HarmonyOS 5.1API 135.12.2 模拟器还是真机怎么选很多新手先问“有没有鸿蒙模拟器电脑版”说实话DevEco Studio自带的是Local Emulator本地模拟器但功能和性能跟Android模拟器比有不小差距而且在模拟器上调试网络、推送、相机等硬件能力会各种受限。我的建议是入门阶段只为跑通Hello World、验证布局和简单交互用模拟器没问题启动速度也还行。只要涉及网络请求、端云协同、应用间跳转、扫码这类系统级能力直接上真机否则很多功能在模拟器里是残缺的。真机调试需要先设置手机开启“开发者模式”然后在DevEco Studio里登录华为账号并开启自动签名这个流程后面会细说。如果你手头连华为设备都没有那模拟器就是唯一选择但尽量把API版本和环境升级到最新减少兼容性干扰。3. 从零跑通第一个鸿蒙Demo工程结构、签名与运行链路3.1 工程创建与目录结构打开DevEco Studio后File → New Project选择Application → Empty Ability模板这个模板会生成一个最简的Hello World工程。命名时注意Package Name的命名规范类似安卓包名比如com.example.myfirstdemo。选完项目模板后IDE会自动拉取依赖并构建这个过程首屏因为要下载Gradle不一定准——其实鸿蒙用的是hvigor是字节跳动开源的前端构建工具链的鸿蒙适配版但用法和Gradle神似依赖仓库是华为的Maven镜像。一个标准工程的目录结构长这样MyFirstDemo/ ├── AppScope/ │ ├── app.json5 │ └── resources/ ├── entry/ │ ├── build-profile.json5 │ ├── hvigorfile.ts │ ├── oh-package.json5 │ └── src/main/ │ ├── ets/ │ │ ├── entryability/ │ │ └── pages/ │ │ └── Index.ets │ ├── resources/ │ └── module.json5 └── oh-package.json5这里面最核心的几个文件module.json5是模块配置声明Ability、页面路由、权限申请等Index.ets是页面逻辑与UI入口app.json5是应用级配置包含应用名称、版本号等。3.2 签名Auto Sign还是Manual Sign很多新手在跑第一个Demo时点运行按钮弹出一堆签名配置错误整个人都懵了。鸿蒙应用运行前必须签名即使是在模拟器上。DevEco Studio提供两种方案Auto Sign自动签名登录华为账号后由IDE自动生成签名证书并配置好。这是最省心的方式前提是你的开发设备必须登录华为账号且手机开启了“华为开发者选项”中的自动签名授权。Manual Sign手动签名需要自己生成密钥库.p12文件、申请证书.cer文件、配置Profile文件流程繁琐一般用于企业分发或上架应用市场新手可以直接跳过。我强烈建议刚入门的朋友直接走Auto Sign登录账号后点一下“同步”IDE自动帮你配好。常见的坑是换了电脑、换了手机签名文件失效报错signature verification failed此时只需重新登录账号并重新Sync即可。3.3 运行到真机的完整链路真机运行的步骤按我这边的习惯写一下手机开启“开发者模式”设置 → 关于手机 → 连点版本号7次。返回设置 → 系统和更新 → 开发人员选项 → 打开“USB调试”并确保“仅充电模式下允许ADB调试”也打开。数据线连接电脑手机弹窗选择“允许USB调试”。DevEco Studio里登录华为账号File → Project Structure → Signing Configs → 勾选Automatically generate signature。点击Run ▶IDE会先编译、签名再安装到手机最后拉起应用。首次运行因为要同步SDK、构建缓存会慢一些后面每次增量编译就快很多。如果遇到设备列表看不到手机大概率是驱动问题Windows上装一下华为手机助手或更新USB驱动即可。4. ArkTS声明式UI基础用Tab页面拼出一个稍有小型的Demo4.1 组件的核心心智状态驱动UI从第一个Demo开始你要先建立“UI是状态的函数”这个心智模型而不是像安卓原生那样“findViewById然后setText”。ArkTS提供了一套装饰器系统最常用的是Entry、Component、State。拿一个极简计数器来演示Entry Component struct CounterPage { State count: number 0 build() { Column() { Text(点击次数${this.count}) .fontSize(24) .margin({ bottom: 20 }) Button(点我 1) .onClick(() { this.count }) } .width(100%) .padding(20) } }这里State装饰的count一旦变化UI中依赖它的Text组件会自动刷新无需手动拿到节点再更新。这种数据驱动视图的写法如果你写过Vue或React会感觉很亲切。4.2 做一个底部Tab导航的完整Demo计数器只能让你感受装饰器要做成“有点完整感”的Demo最好做一个底部Tab导航页面——这也是绝大多数App的主框架形态。鸿蒙里的Tabs组件天然支持这个场景下面是关键代码结构Entry Component struct MainPage { State currentIndex: number 0 private tabsController: TabsController new TabsController() build() { Tabs({ barPosition: BarPosition.End, controller: this.tabsController }) { TabContent() { HomePage() } .tabBar(this.tabBuilder(0, 首页, 0xe6e6e6)) TabContent() { MinePage() } .tabBar(this.tabBuilder(1, 我的, 0xe6e6e6)) } .onChange((index: number) { this.currentIndex index }) } Builder tabBuilder(index: number, title: string, normalColor: number) { Column() { Text(title) .fontSize(this.currentIndex index ? 18 : 14) .fontColor(this.currentIndex index ? #007DFF : #999999) } .width(100%) .padding({ top: 6, bottom: 6 }) } }这里面两个核心点Builder装饰器可以复用UI片段类似Vue的插槽或者React的render函数。我定义的tabBuilder根据当前选中的index动态变化字体和颜色这个思路可以套用到任意需要动态样式的场景。TabsController负责控制Tab的跳转onChange回调监听切换事件。如果以后需要“点击按钮跳到某个Tab”直接调用this.tabsController.changeIndex(1)即可。热词里有朋友问“鸿蒙stack布局子组件怎么控制自己在底部上方100的位置居中”这个在ArkTS里很典型你可以把navbar容器做成Stack然后给子组件设置alignRules或者直接用position加偏移。举个最常见的写法Stack({ alignContent: Alignment.Bottom }) { // 底部留白100vp的容器 Column() .height(100) .width(100%) Text(我在底部上方100vp并居中) .alignSelf(ItemAlign.Center) .margin({ bottom: 100 }) }Stack的alignContent控制子组件整体对齐方式alignSelf控制单个子组件的对齐方式。想让子组件在底部上方100的位置居中就是在底部对齐后再加上下边距或者用position: { bottom: 100 }。这块我用过几次其实是鸿蒙布局里面最好理解的对齐模型比安卓的多层LinearLayout嵌套要清爽得多。4.3 关于状态管理的两个进阶点入门Demo一旦超过一个页面状态共享问题立刻浮出水面。ArkTS除了State还提供了Prop、Link、Provide和Consume这几类装饰器适用场景各不相同State组件内部管理的状态只能自己改自己的。Prop父子单向传递父组件更新会传给子组件但子组件不能反过来改父值。Link父子双向同步子组件改了父组件同步变相当于引用传递。Provide/Consume跨层级传递状态类似依赖注入适合较深的组件树。我在Demo里做“我的”页面时头像昵称需要多处引用同一个用户数据于是用Provide在根组件注入子组件用Consume取这样比一层层用Prop传参清爽得多。不过也要提醒Link和Consume用得太多状态流向会变得很难追踪小项目控制在一两个全局状态即可多了建议引入状态管理库。5. 网络请求Demo与权限申请入门必踩的坑5.1 请求权限的方式和安卓完全不同热词里有人提到“flutter兼容鸿蒙拉起iap支付”也有人问“开发app的时候打开没有全屏海报”可见很多人在做的是基于鸿蒙的网络请求和跨端能力验证。但这里面有一个非常容易忽略的前提HarmonyOS的权限分两种常规权限system_grant和用户授权权限user_grant。system_grant在module.json5里声明后安装时自动授予。user_grant比如定位、相机、麦克风等需要在代码里动态请求用户弹窗确认后才会授予。没有做动态请求就调用相机应用会直接闪退而且IDE控制台可能只打一行很不起眼的permission verification failed。我之前在外包调试一个扫码功能时就在这里耗了快半天。正确的做法是使用abilityAccessCtrl模块import { abilityAccessCtrl, bundleManager, common, Permissions } from kit.AbilityKit; async function requestPermission(context: common.UIAbilityContext): Promisevoid { const atManager abilityAccessCtrl.createAtManager(); const permissions: ArrayPermissions.Permission [ohos.permission.CAMERA]; // 先检查是否已授权 const grantStatus abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED; const authResult await atManager.requestPermissionsFromUser(context, permissions); if (authResult.authResults[0] ! grantStatus) { console.error(权限未授予); } }5.2 网络请求与网络安全配置HarmonyOS NEXT的HTTP请求默认不允许明文流量即http:// 地址如果你只是本地联调一个Web API请求会被直接拦截报cleartext not permitted之类的错误。这是安全策略可以从module.json5的deviceConfig配置或者网络安全管理器里临时配置信任的域名但正式版必须要用https。一个比较标准的请求Demoimport { http } from kit.NetworkKit; async function fetchData(): Promisevoid { const httpRequest http.createHttp(); const response await httpRequest.request(https://api.example.com/user/info, { method: http.RequestMethod.GET, header: { Content-Type: application/json, Authorization: Bearer xxxx }, connectTimeout: 10000, readTimeout: 10000 }); if (response.responseCode 200) { const data JSON.parse(response.result as string); console.info(请求成功${JSON.stringify(data)}); } else { console.error(请求失败状态码${response.responseCode}); } httpRequest.destroy(); }注意http.createHttp()创建的对象单次用完最好destroy()防止连接泄漏。以及如果你打算长期保持长连接做IM类功能就要考虑kit.NetworkKit里的WebSocket或者直接用华为的推送服务做消息触达。5.3 从Demo到组件的网络层封装思路这个Demo我建议顺手做得规范一点定义一个HttpUtil类统一处理GET/POST、超时、异常捕获然后页面里只管调用。原因很实际鸿蒙的网络回调如果散落在各个页面后期改基础URL或者加统一鉴权头会导致全项目大扫除。我自己的做法是基础URL和超时时间放在一个ApiConfig.ets文件里。每个接口一个函数返回PromiseApiResultT。页面通过async/await调用onError统一弹Toast。这样从第一个Demo开始就养成好习惯后面项目变大时不用重构能省掉一大笔时间成本。6. 打包与构建hap、hsp、har的区别和工程选择6.1 三种产物分别是什么热词里有朋友问“可以打包成hap、hsp、har的鸿蒙demo”这确实是入门到进阶的一道必答题。简单来说它们的定位差别很大产物类型全称定位类比HAPHarmonyOS Ability Package应用的能力包最终安装到设备的单元包含UIAbility、页面和资源类似APK但一个App可以有多个HAPHSPHarmonyOS Shared Package共享资源包运行时的动态共享多个HAP可以复用它类似动态库/共享模块如Flutter的plugin包HARHarmonyOS Archive静态资源包编译时被其它模块引用最终打进HAP里类似AAR/JAR纯代码和资源包简单理解HAR是编译时合并进HAP的HSP是运行时动态加载的。如果你的代码是工具库、UI组件库供主工程引用用HAR就够了但如果你做的是大型应用有多个HAP模块且需要复用一个公共能力模块为了减小包体积、支持动态加载用HSP更合理。6.2 创建HAR/HSP模块及引用方式右键工程根目录 → New → Module → 选择“Static Library”生成HAR选“Shared Library”生成HSP。生成后模块有自己的oh-package.json5主模块在依赖中这样声明{ dependencies: { my_har: file:../my_har, my_hsp: file:../my_hsp } }写完后运行hvigor sync主模块代码里直接import { MyComponent } from my_har即可使用。要注意的是HAR的ets代码和资源是直接打包进HAP的所以HAR越大主包的安装包就越大HSP因为是运行时加载包体会更小但首次动态加载会有额外的IO开销。6.3 构建证书、包名与上架前的检查构建发布版HAP时签名不能再用开发版的自动签名了需要在AGCAppGallery Connect上申请发布证书和Profile然后在Build → Generate Key Store生成.p12文件、填写证书指纹最后选择Release签名构建。这部门其实和Android的v1/v2签名流程类似但操作入口比较隐蔽新手建议先在官方文档里搜“应用签名”再把AGC里面的选项一步步对照着操作。另外包名这块千万先想清楚应用市场审核时包名不可更换一旦某个包名已经申请过签名指纹后续都想绑着这个走。遇到两个包名太长、用了非法字符立刻编译期报错倒是还好但生成签名指纹时如果包名变了审核就会提示签名不一致。我自己在实际开发中还有两个屡试不爽的检查项确认module.json5里的abilities配置中exported是否正确——如果想让系统桌面拉起到主Ability主Ability的exported必须为true。确认versionCode是自增的否则上传AGC版本时会提示版本号重复。7. 鸿蒙开发路上的几点个人体会带一批朋友跑通这个Demo之后我越来越确信一个判断鸿蒙开发入门最大的学习成本不在语言而在思维模式转换。ArkTS语法本身两三天就能上手真正需要花时间的是理解Stage模型的设计意图、组件装饰器的状态管理范围以及清楚设备厂商对应用分发能力的边界要求。遇到问题第一时间去查官方API文档和示例代码比满网搜第三方教程靠谱得多网上信息更新速度很难跟上鸿蒙的版本迭代。另外建议起步阶段尽量小而精不要一上来就搞大而全的工程结构。先跑通一个空模板再逐步加入网络、存储、扫码、推送每加入一个能力点就在能运行的Demo上做增量修改这样定位bug时永远能快速缩小范围。不要迷信热词里那些“开源鸿蒙PC版搭建”之类的方案那不是应用开发者的主赛道主赛道是把体验做实、把工程做规范、把权限处理好这些基本功才是所有鸿蒙项目的地基。本文还有配套的精品资源点击获取
