企业官网建设流程全解析

简介：这个源码是第十九届“挑战杯”揭榜挂帅·华为赛道中AI质检助力制造业数智化创新项目的鸿蒙APP成果，面向大学生竞赛参赛者和鸿蒙应用开发入门、进阶学习者，展示了一个从真实赛题落地而来的完整工程，适合系统学习、课程设计与竞赛备赛等场景。压缩包共57个文件、约4.97MB，其中ets为ArkTS页面逻辑代码，json/json5为工程与模块配置，png与gif分别呈现界面截图和操作演示，另有ts脚本及README说明文档；目录按AppScope、entry、hvigor等模块组织，结构清晰，便于按工程流程逐层研读。已有64人浏览学习。借助这套源码，可以掌握鸿蒙应用从工程配置、页面编写到OpenHarmony能力调用的完整写法，理解AI质检场景下前端展示与数据交互的实现路径；配合演示动图和截图，还能快速复盘赛题方案。整体上是一份兼具项目完整度与学习价值的参考资料，适合用于备赛冲刺或系统提升鸿蒙开发实战技能。

1. 一个鸿蒙 APP 源码 zip，在挑战杯华为赛道里到底交的是什么

挑战杯华为赛道交作品时，常见形式是一个源码压缩包：挑战杯华为赛道-鸿蒙APP源码.zip。它既是代码，也是交付物本身。很多队伍拿到队友传来的包或从网上下到的示例，第一反应是双击解压、直接拖进 IDE，结果在导入环节就卡住，报错一堆，最后只能现场敲键盘救场。这个 zip 的打开方式，决定了你后面两小时是改功能还是修环境。

这篇不聊比赛规则，只聊一件具体的事：拿到一个鸿蒙 APP 源码 zip 之后，怎么在最短时间里完成校验解压、工程识别、DevEco Studio 导入、签名真机运行、二次开发和重新打包。按这套流程走下来，新手能无痛跑通，老手也能在答辩前少踩几个隐蔽的坑。

2. 鸿蒙 APP 源码 zip 的工程识别：先分清 HarmonyOS 还是 OpenHarmony

一个 zip 文件能解压不代表它能构建。鸿蒙生态里存在 HarmonyOS 和 OpenHarmony 两套侧重点不同的工程，源码目录长得像，构建参数不一样。先花五分钟认清包里的工程身份，比直接双击 DevEco Studio 要省一小时。

2.1 解压前先校验：zip 完整性、哈希与文件编码

先不急着解压。比赛源码包经常在网盘或群里转手，一个被截断的 zip 会让 IDE 报出极其误导的错误。第一步是验证文件完整，用unzip -t测试 zip 内部的 CRC 记录，再用 sha256 与发布方给出的哈希值比对，确认压缩包没被替换过。如果包带密码，不要依赖来路不明的 zip 密码破解工具，先回去找发布方核对，顺带校验哈希。

unzip -t ./challenge-huwei-harmonyos-app.zip sha256sum ./challenge-huwei-harmonyos-app.zip

参数说明：unzip -t只做 CRC 校验，能发现解压时损坏的文件，但发现不了「文件被整体替换」这类问题；sha256sum计算整个文件的 SHA-256 摘要，比对源文件或赛题官网给出的值。Windows 没有sha256sum时，可以用certutil -hashfile <文件> SHA256达到同样目的，macOS 自带shasum。

接下来解压。最常见的翻车点是文件名编码：Windows 资源管理器压缩的 zip 里中文文件名常是 GBK 编码，macOS 或 Linux 解压后变成乱码目录，IDE 打开后找不到 module.json5。我的处理方式是优先用 7z 解压，它对中文编码的兼容性比系统自带解压好。

7z x ./challenge-huwei-harmonyos-app.zip -o./src

参数说明：x表示解压并保留目录结构；-o指定输出目录，注意它后面直接跟路径、不加空格。如果解压出的目录名是乱码，不要继续在 IDE 里打开，先用 7z 重新解压一次，再用 Python 的zipfile列出内部文件名确认编码是否正常。

提示：不要在一层目录里塞多个版本。解压后先 cd 进目录，确认是否有build-profile.json5，有它才说明这是鸿蒙工程根目录。

2.2 打开工程第一眼：stage 模型、hvigor 与 module.json5

鸿蒙应用工程在 API 9 之后统一走 stage 模型。判断一个 zip 里的代码是不是正经的鸿蒙工程，就看根目录有没有这些文件：

project-root/ ├── build-profile.json5 # 工程级构建参数 ├── hvigorfile.ts # hvigor 构建脚本入口 ├── oh-package.json5 # ohpm 依赖清单 ├── AppScope/ │ ├── app.json5 # 应用级配置 │ └── resources/ └── entry/ ├── build-profile.json5 ├── oh-package.json5 └── src/ ├── main/ │ ├── module.json5 # 模块配置 │ ├── ets/ │ │ ├── entryability/EntryAbility.ets │ │ └── pages/Index.ets │ └── resources/ └── ohosTest/

带build-profile.json5的那一层才是工程根目录，entry只是模块。oh-package.json5声明依赖，hvigorfile.ts是打包脚本入口。如果 zip 里只有 entry 文件夹丢在根下、没有 build-profile.json5，那大概率是被人拆了一半的工程，导入必失败。

打开entry/src/main/module.json5，这个文件决定了 App 怎么启动。关键字段示意如下：

{ "module": { "name": "entry", "type": "entry", "deviceTypes": ["phone", "tablet"], "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "exported": true } ] } }

说明：srcEntry指向应用启动时加载的 ArkTS 文件，一般和entryability目录下的文件对应。type为entry表示这是应用主模块；如果看到的是feature，说明这是被拆出来的子模块，不能单独安装。老版本 FA 模型里没有这个文件，而是一个config.json和app.js；遇到老工程，常见做法是手动迁移到 stage 模型，或者直接去找一份新的赛题模板，而不是硬编。

2.3 识别 API 版本，避免导入就报错

DevEco Studio 导入工程时，第一件事是读 build-profile.json5 里的 SDK 版本声明。版本对不上会直接弹 compileSdkVersion 相关错误。来自赛题的源码通常配了开发者的本机环境，评委或队友机器上未必有对应 SDK。

{ "app": { "products": [ { "name": "default", "compileSdkVersion": 10, "compatibleSdkVersion": 9, "runtimeOS": "HarmonyOS" } ] } }

这是旧版工具链里比较常见的写法，新版 IDE 生成的内容字段名会略有变化，但核心概念一致。逐字段理解：

runtimeOS是很容易被忽略的坑。开源鸿蒙 PC 版、开发板用的工程和手机上的 HarmonyOS 工程，SDK 差异很大。把 OpenHarmony 的工程塞进手机版 DevEco Studio，最后在设备安装时会报签名或系统版本不兼容。先看清runtimeOS再决定要不要继续，可以避免在错误的路上调半天。解压后先全局搜一遍compileSdkVersion，把版本信息记下来，后面导入、跑真机全靠它。

3. 把 zip 变成可运行 App：DevEco Studio 导入与签名配置

识别完工程身份，接下来就是让它在你自己电脑上跑起来。这一步的目标不是写功能，是把一个别人的源码 zip 变成一台真机上能点的 App，才能在它基础上改东西。

3.1 最小导入路径：解压、打开、同步依赖

常见的错误操作是把 zip 直接拖进 IDE 窗口，IDE 会当它一个文件打开，然后一脸茫然。正确姿势是：先解压，再在 File > Open 里选择包含 build-profile.json5 的工程根目录。DevEco Studio 会开始扫描和同步，第一阶段什么都别点，等右下角进度条走完。

同步完成后做两件事：确认依赖已安装，然后在项目终端执行：

ohpm install ohpm install --all

参数说明：ohpm是鸿蒙生态的包管理器，读取oh-package.json5里的依赖描述；--all会把当前 workspace 下所有模块的依赖一起处理。如果 IDE 右侧没有出现 ohpm 的报错，再执行一次构建，让 hvigor 生成缓存。执行期间会有网络下载依赖的日志，公司网络严格时可能超时，常见做法是切到手机热点重试。

Windows 上报错里有failed to copy spatial iop zip这类资源复制失败，原因基本是解压路径太长或杀毒软件拦截了复制。把工程放到D:\work\hmapp这种纯英文短路径下重新解压，关掉杀毒对构建目录的实时扫描，再重新导入。macOS 上则注意 zip 是否包含__MACOSX目录，有就删掉再导入。

3.2 API 版本不匹配时改哪几个参数

入门选手最常碰到的弹窗是 compatibleSdkVersion mismatch。这时候不是重新装 IDE，是改工程参数。打开模块级的 build-profile.json5，找到 app.products 数组，把 compileSdkVersion 改成 IDE 提示的可用版本，把 compatibleSdkVersion 改成不大于目标设备的版本。

{ "app": { "products": [ { "name": "default", "compileSdkVersion": 12, "compatibleSdkVersion": 10, "runtimeOS": "HarmonyOS" } ] } }

改完不要手动删.hvigor和oh_modules，直接在 IDE 里 File > Sync and Refresh Project。如果 IDE 还提示 hvigor 版本不一致，工程根目录的hvigor/hvigor-config.json5里可以指定项目要用的 hvigor 版本，选择本地已装的版本即可。注意compatibleSdkVersion大于演示机系统 API 时，App 会直接装不上；宁可低，不要高。

3.3 签名、调试证书与真机运行

鸿蒙 App 要装进真机必须有签名。日常开发不用自己去申请发布证书，DevEco Studio 登录华为账号后可以在 Project Structure > Signing Configs 里勾选自动生成签名，它会生成调试证书并写进构建配置。注意自动签名生成的调试证书只在本机有效，打包评审包时要用账号下的正式证书重新配置。

构建 HAP 用 hvigorw，在工程根目录执行：

./hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

参数说明：assembleHap是 hvigor 的构建任务，产出 HAP 文件；buildMode=debug会使用调试签名，release需要正式证书；--no-daemon让构建进程跑完即退出，避免在比赛机器上留下占内存的后台进程。构建产物默认在entry/build/default/outputs/default/下，文件一般叫entry-default-signed.hap。

真机安装用 hdc，先确认设备被识别，再安装：

hdc list targets hdc install -r ./entry/build/default/outputs/default/entry-default-signed.hap

参数说明：list targets会列出已连接设备的序列号，什么都没有就先检查 USB 调试、驱动和手机上的开发者模式；install -r表示覆盖安装同名应用。模拟器在 Device Manager 里启动，不需要 hdc，但模拟器的定位、相机等传感器行为和真机不同，比赛演示前至少要在真机上完整跑一遍主流程。

4. 从「能跑」到「能改」：ArkTS 页面结构、状态管理与路由

导入跑通只是热身。挑战杯作品最后考察的是你在这个源码上做了什么。看懂 ArkTS 的页面和状态管理逻辑，才能在两天内把示例代码改成自己的作品，而不是从头建工程。

4.1 源码主入口：EntryAbility 里发生了什么

每个鸿蒙 App 启动时，先从 module.json5 里声明的 EntryAbility 开始。它的 onCreate 做初始化，onWindowStageCreate 把第一个页面挂到窗口上。打开entryability/EntryAbility.ets，重点看 loadContent 指向哪个页面。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit' import { window } from '@kit.ArkUI' export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { console.info(`EntryAbility created, launchReason=${launchParam.launchReason}`) } onWindowStageCreate(windowStage: window.WindowStage) { windowStage.loadContent('pages/Index', (err) => { if (err.code) { console.error(`loadContent failed: ${err.message}`) return } console.info('first page loaded') }) } }

这里的导入用的是新版 @kit 写法；老工程里可能是@ohos.app.ability.UIAbility和@ohos.window，功能等价。loadContent的第一个参数是页面路径，对应src/main/ets/pages/下的文件。比赛常见的白屏问题，一半是这里路径写错，一半是页面文件里抛了异常。第一次维护别人的源码，先别动这个文件，只确认路径存在。

4.2 最小可改页面：在 ArkUI 里做列表和交互

ArkUI 的页面是一个个 struct 组件。竞赛项目里最常改的就是页面和组件。给你一个最小可运行的结构，理解它就能看懂大多数工程：

@Entry @Component struct QuickStart { @State count: number = 0 build() { Column({ space: 12 }) { Text(`点击次数：${this.count}`) .fontSize(20) Button('点我') .onClick(() => { this.count++ }) } .padding(24) } }

说明：@State标记的变量在值变化时会让 UI 局部刷新，这是声明式 UI 的核心。.onClick里直接改状态，不需要像传统命令式 UI 一样手动 find 控件再设值。注意 ArkTS 里不要写any；@State修饰数组时，调用 push 这类方法不一定触发刷新，要给数组重新赋值，后面多选删除会用到这个规则。

4.3 比赛作品常见功能：多选列表、删除与网络请求

答辩时评委最常点开的功能是带数据的列表页和增删操作。下面给鸿蒙 ArkTS 多选列表删除的最小实现，这也是近两年鸿蒙面试题里出现过的高频考点：

@Entry @Component struct SelectableList { @State items: string[] = ['鸿蒙入门', 'ArkUI 布局', '状态管理', '网络请求'] @State selected: number[] = [] build() { Column({ space: 8 }) { List({ space: 8 }) { ForEach(this.items, (item: string, index: number) => { ListItem() { Row({ space: 8 }) { Text(this.selected.includes(index) ? '[x] ' : '[ ] ') Text(item) } .onClick(() => { if (this.selected.includes(index)) { this.selected = this.selected.filter((n: number) => n !== index) } else { this.selected = [...this.selected, index] } }) } }, (item: string) => item) } .width('100%') .layoutWeight(1) Button('删除选中') .onClick(() => { const kept = this.items.filter((_: string, i: number) => !this.selected.includes(i)) this.items = kept this.selected = [] }) } .padding(16) } }

说明：selected 存的是勾选索引。点击行时用展开运算符生成新数组，保证@State能感知变化；删除时用 filter 同时重建 items 和 selected。ForEach 的第三个参数是 key 生成器，返回唯一值，这里用 item 本身，内容不重复即可。这套模式在鸿蒙 app 开发小项目里非常常见。

如果作品需要拉取远程数据，用 @ohos.net.http 发请求。先在 module.json5 的 module 节点里加网络权限：

"requestPermissions": [ { "name": "ohos.permission.INTERNET" } ]

import http from '@ohos.net.http' const request = http.createHttp() request.request( 'https://api.example.com/contest/list', { method: http.RequestMethod.GET, connectTimeout: 10000, readTimeout: 10000, header: { 'Content-Type': 'application/json' } } ).then((resp: http.HttpResponse) => { if (resp.responseCode === 200) { console.info(`list: ${resp.result}`) } }).catch((err: Error) => { console.error(`request failed: ${err.message}`) })

参数说明：connectTimeout 和 readTimeout 的单位是毫秒，现场网络不稳定时，超时低于 5000 很容易断；真机上访问 http 明文地址在不同 API 版本下有限制，赛前统一改用 https 接口最省事。

常用 ArkUI 组件速查：

读懂这些组件，再看源码里的页面就快了。先画页面，再拆组件，最后看 @State 和 @Link 谁在管数据。比赛代码不需要炫技，把列表、详情、表单、网络请求这几板斧做扎实，答辩能讲清楚就行。

5. 赛道评审前最后 10 分钟：日志、真机验证与 zip 打包避坑

5.1 用 hdc + hilog 抓崩溃现场

现场演示最怕的是点开页面直接闪退。在交付前，用数据线连着真机跑一遍主流程，抓一轮日志看看有没有 fatal error。先清空日志，再操作 App，最后过滤：

hdc shell hilog -c hdc shell hilog -T EntryAbility -e "ERROR|FATAL"

-c清空历史日志，让下一次操作产生的日志成为干净样本；-T按 tag 过滤，默认 tag 常用类名或 ability 名；-e接正则过滤关键词。如果只看 ArkTS 侧的报错，可以再加一个-e "ArkTS|ERROR"。跑完一轮操作后看有没有 FATAL，有就展开堆栈定位到具体页面；没有，至少能证明主路径没有严重崩溃。

5.2 重新打包 zip 的三个细节

提交源码前重新压 zip，三个细节容易踩。第一，不要带 build、oh_modules、.hvigor、.idea 这些目录，评委解压后第一次 sync 会花大量时间，甚至因缓存目录里带本机路径而报错。第二，不要在压缩时再套一层同名文件夹，解压后第一层看不到 build-profile.json5，会让人误判工程不完整。第三，用命令行压缩时显式排除缓存：

zip -r challenge-huwei-harmonyos-app.zip . \ -x "*/build/*" -x "*/.hvigor/*" -x "*/oh_modules/*" -x "*/.idea/*" -x "*/.git/*"

参数说明：-x后面跟排除规则，*匹配任意层级的目录。Windows 下也可以用 7z，命令是7z a加-xr!build。导出资源包时如果报invalid zip archive: could not find eocd，说明压缩包在传输中被截断了——EOCD 是 zip 文件末尾的中央目录记录，文件不完整就会找不到它，重新从源头下载并比对哈希，不要浪费时间找修复工具。

5.3 用 Python 校验解压路径，防止 zip slip

从网上下载的源码包，解压前用脚本检查一下路径。恶意构造的 zip 可以带../把文件写到目标目录之外，比赛包大概率没这个问题，但这是交付前值得保留的习惯：

import zipfile from pathlib import Path dst = Path('./unzip-check') with zipfile.ZipFile('./challenge-huwei-harmonyos-app.zip') as zf: for name in zf.namelist(): target = (dst / name).resolve() if not target.is_relative_to(dst.resolve()): raise RuntimeError(f'illegal path: {name}') zf.extractall(dst) print('zip is safe to extract')

参数说明：zipfile.namelist()返回包内所有条目，resolve()会拼接出实际落盘路径，is_relative_to判断是否还在目标目录内，脚本依赖 Python 3.9 及以上。把这段检查逻辑加进交付前的压缩脚本，和 sha256 校验一起跑，zip 包在评委机器上解压时会少很多不必要的报错。

本文还有配套的精品资源，点击获取