# 从空白模板到真机运行:鸿蒙文件管家 AITest 一天开发实录 > 发布时间: 2026-08-12 08:46 # 从空白模板到真机运行:鸿蒙文件管家 AITest 一天开发实录 > 本文记录一个 HarmonyOS 应用从需求调研、SDK 大版本迁移、编码、编译排错到真机安装运行的完整一天,以及途中踩过的十几个真实的坑。没有粉饰,没有"凭代码反推",全是聊天记录里真实发生过的事。 > > 注:文中的服务器地址、API 路径、Key、设备标识等均已脱敏。 ## 项目是什么 两件事,两个项目: | 项目 | 角色 | 技术栈 | |------|------|--------| | **AITest** | 鸿蒙客户端(本文主角) | ArkTS + HarmonyOS 6.1.0(23) | | **FileUploadServer** | 远程文件服务器(已部署) | ASP.NET Core 10 + PostgreSQL | 服务器跑在公网(域名略),提供一套基于 **API Key** 的文件操作接口。客户端的目标很朴素:用户输入一个 Key 登录,然后能看文件列表、上传、下载、删除。不造后端,只对接 HTTP API。 服务器的认证方式简洁到可爱:受保护的文件接口,鉴权就靠 URL query 参数 `?key=<你的密钥>`。密钥分两种--Admin(管全部文件,365 天有效,只能服务器本机创建)和 Temporary(只管自己的,24h 过期,公网可申请但依赖 IP 白名单)。 因为手机出口 IP 不固定、临时密钥又卡 IP 白名单,客户端**不做密钥申请**,让用户手动输入一个已有的 Admin Key 登录。这个决策从一开始就定了,省掉后面一大堆麻烦。 --- ## 一、起点:调研、验证、决策 第一件事不是写代码,是先把服务器摸清楚。我用 curl 把几个关键端点都打了一遍: | 测试 | 请求 | 结果 | 结论 | |------|------|------|------| | HTTPS 可达性 | 请求文件接口(不带 Key) | 401,0.13s | 在线,HTTPS 正常 | | 无效 Key | 带一个乱造的 Key 请求 | `Unauthorized` | 鉴权符合预期 | | 公开端点 | 请求公开文件接口 | 200 + JSON | 匿名可用 | | Admin Key | 带新 Admin Key 请求文件接口 | 200 + 完整列表 | 可用 | 服务器确认可用后,SSH 到服务器本机调密钥管理接口创建了一个 Admin Key(有效期到 2027-08-11),作为开发期的长效密钥。创建完顺手拿真实响应扒了一下 `FileItem` 的完整字段--比服务端文档详细,含一堆客户端用不上的内部字段(`storedFileName`、`encryptionVersion`、`storageMode` 等),客户端只保留 `id/fileName/fileSize/contentType/uploadedAt/isPublic/publicPath` 七个。 接着用一轮结构化提问跟自己确认了几个关键点:Key 来源(SSH 建 Admin)、上传来源(相册图片 + 任意文件)、下载位置(公共下载目录)、是否做密钥申请入口(不做)。 --- ## 二、意料之外的迁移:API 9 -> API 23 这是整个项目最没有预料到的一段。 工程最初是 API 9 的老模板,`build-profile.json5` 里 `compileSdkVersion: 9`,代码用 `@ohos.*` 命名空间。我本来建议"先用 API 9 开发,代码用兼容命名空间,后续再升"。用户很干脆:**"我先装最新 api"**。 装完一看,不是 API 11,也不是 12,是 **API 23(OpenHarmony 6.1.0.32,DevEco Studio 6.1.1.300)**。一个 API 9 到 API 23 的 **14 个大版本跨度**。 这跨度意味着配置文件格式几乎全变: | 项 | API 9 旧格式 | API 23 新格式 | |----|------------|--------------| | 构建工具版本 | `hvigorVersion: 2.4.2` | `modelVersion: "5.0.0"` | | SDK 版本字段 | `compileSdkVersion: 9` | `compatibleSdkVersion` / `targetSdkVersion: "6.1.0(23)"`(字符串) | | wrapper 脚本 | `hvigor-wrapper.js` | `hvigorw.js` | | 命名空间 | `@ohos.*` | `@kit.*` | 手动改这种配置几乎一定踩坑。于是我没硬写,而是去翻 DevEco Studio 6.1 安装目录里自带的项目模板(`plugins/codegenie-plugin/previewProjectTemplate/`),把模板的 `build-profile.json5`、`hvigor-config.json5` 等标准配置拿来对照着改,同时确认了 hvigor 版本是 6.24.4。照模板改,一遍过。 这一段还有两个小坑: - **emoji 让 Edit 工具失配**:改 `doc/00-integration-plan.md` 末尾时,Edit 报 `String to replace not found`,试了转义和原字符都不行--文档里有 emoji,old_string 和文件实际内容有不可见差异。最后改用 Write 整体重写。 - **Write 覆盖前必须先 Read**:某次直接 Write 一个已存在的 `oh-package.json5` 报 `File has not been read yet`。因为我之前是用 `cat` 看的,没用 Read 工具。补一次 Read 再 Write 就过了。 --- ## 三、一口气写完代码 环境就绪后,按三层架构把代码一次性铺开: ```plantuml @startuml skinparam componentStyle rectangle skinparam shadowing false package "UI 层 (ets/pages)" { [Index.ets\n登录页] as Login [FileListPage.ets\n文件列表页] as List } package "服务层 (ets/services)" { [ApiConfig] as Cfg [ApiService] as Api [AuthService] as Auth [FileService] as File } package "鸿蒙系统能力 (@kit.*)" { [NetworkKit\nnet.http] [BasicServicesKit\nrequest] [CoreFileKit\npicker / fs] [ArkData\npreferences] } cloud "FileUploadServer\n(公网,域名略)" as Server Login --> Auth : 存取 Key Login --> Api : 校验 Key List --> Api : 列表/删除 List --> File : 上传/下载 Api --> NetworkKit File --> BasicServicesKit File --> CoreFileKit Auth --> ArkData NetworkKit ..> Server : HTTPS + ?key= BasicServicesKit ..> Server @enduml ``` - **ApiConfig**:集中管理服务器地址和 5 个端点 URL,`?key=` 统一 `encodeURIComponent`。 - **ApiService**:基于 `net.http` 的 JSON 请求(列表、删除、Key 校验),统一错误码映射,业务错误用自定义 `ApiException` 携带状态码。 - **AuthService**:`preferences` 做 Key 的本地持久化,存/取/清。 - **FileService**:封装 `request.uploadFile` / `downloadFile`,处理沙箱拷贝和进度回调。 - **Index.ets**:登录页,输入 Key -> 校验 -> 存 -> 跳转,支持自动登录。 - **FileListPage.ets**:列表页,上传/下载/删除/退出。 代码写完,会话结束。但**没有验证编译**--WSL 里 SDK 路径是 Windows 格式,DevEco 工具链也在 Windows 侧,跑不了 hvigor。我留了三个待验证风险点交给用户在 DevEco 里 sync: 1. `compatibleSdkVersion: "6.1.0(23)"` 是从 SDK 的 `oh-uni-package.json` 推断的,没经 sync 验证。 2. `getContext(this)` 在字段初始化时可能报错。 3. 公共下载目录受 Scoped Storage 限制,当前下载到沙箱,后续优化。 这三个伏笔,后面应验了。 --- ## 四、编译器教我做人:21 个 ERROR 用户在 DevEco 里一 Rebuild,炸了:**21 个 ERROR、40 个 WARN**,集中在三个文件。 这次最耗时的不是改代码,是**逐个去 SDK 的 `.d.ts` 声明文件里查证每个 API 的真实形态**。鸿蒙 API 在不同版本差异大、Kit 重组频繁,靠记忆写一定会错。事实证明的确如此。 ### 坑 1:`@kit.RequestKit` 在 API 23 里根本不存在 `FileService.ets` 里 `import { request } from '@kit.RequestKit'` 报错,`find "$SDK" -iname "*RequestKit*"` 无任何结果。 连锁后果很严重:`request` 变成隐式 `any`,导致后面 `UploadConfig`/`File`/`RequestData` 等对象字面量全部报 `arkts-no-untyped-obj-literals`--8 条错误都是这一个 import 的连锁反应。 根因:`@ohos.request.d.ts` 文件头标注的是 `@kit BasicServicesKit`,`request` 实际由 `@kit.BasicServicesKit` 导出。改成 `import { request } from '@kit.BasicServicesKit'`,8 条连锁错误瞬间消失。 ### 坑 2:`@kit.CoreFileKit` 不导出 `fs` `import { fs } from '@kit.CoreFileKit'` 失败。读声明文件发现 CoreFileKit re-export 的是 `fileIo`。改成 `import fs from '@ohos.file.fs'`。 ### 坑 3(最有价值):修好 import 后,被 `any` 掩盖的隐藏 bug 会暴露 这是我自认为本次最值得的一步。修完上面两个 import,我主动追问了一句:**"修好 import 后,原本被 `any` 掩盖的类型不匹配会暴露"**,然后去声明文件里逐一核验所有相关 API 签名,挖出 4 处原本根本不报错的隐藏 bug: 1. `fs.OpenMode.WRITE` 不存在--命名空间成员只有 `READ_ONLY / WRITE_ONLY / READ_WRITE / CREATE / TRUNC / APPEND`。原代码没报错纯粹因为 `fs` 是 `any`。改 `WRITE_ONLY`。 2. `DownloadConfig` 没有 `filename` 字段--声明里只有 `filePath?: string`。原代码 `filename: fileName` 被 `any` 放过。改 `filePath`。 3. `DownloadTask.on('complete', ...)` 回调无参数--声明是 `callback: () => void`,原代码写 `(downloadPath: string) => ...` 签名不匹配。 4. `DownloadTask.on('fail', ...)` 参数是 `number`--声明是 `(err: number) => void`,原代码写 `(err: BusinessError) => ...`。 后两条要重写 `awaitDownloadComplete` 为 `Promise`,回调对齐 SDK 签名,并移除不再用的 `BusinessError` 导入。 这 4 个 bug 修完,用户重新 Build 才不会再撞新错。**编译器之前"放过"它们,不是因为对,是因为类型信息缺失**。这个教训我记下了:修完一个类型 import,一定要回头扫一遍同文件里所有用到该类型的调用。 ### 其他小坑(罗列) - `PhotoSelectResult.uris` 不存在,实际属性是 `photoUris`。 - `DocumentViewPicker.select()` 直接返回 `Promise>`,没有 `uris` 包装。 - `Progress` 的 `.style()` 已废弃(`@useinstead type`),改用构造器 `Progress({ type: ProgressType.Linear })`。 - `List` 的对齐方法是 `.alignListItem()`,不是 `.align()`。 - ArkTS 严格模式不允许 `throw e`(`arkts-limited-throw`),要 `throw e as Error`。 - `resp.result` 是 `string | Object | ArrayBuffer` 联合类型,赋给 `string` 要 `as string`。 --- ## 五、取回钥匙,准备上手机 编译过了之后,用户要 Key。文档里记录了 Key 的有效期,但明确写"key 值不入库"。于是 SSH 上服务器,在服务器本机调密钥管理接口查到了之前创建的那个 Admin Key 的值,跟文档记录吻合。顺手存进项目 memory,下次直接取,不用再翻聊天记录。 接着是打包。当时 `signingConfigs: []` 是空的,模拟器能跑但真机必须有签名。用户没配过自动签名,我给了流程:DevEco 里 `Automatically generate signature`(需华为开发者账号)-> 开 USB 调试 -> Build 出 `-signed.hap` -> `hdc install`。 这里用户问了个好问题:**"我构建了 hap 和 app,应该用哪个?"** 查产物发现两个都是 `-unsigned`,还没签名。解释:hap 是单模块安装包,`hdc install` 直接装手机;app 是上架应用市场的整包格式,装不了。自用一律 hap。 还有一个:**"所以一定要先插上手机对吗?"**--配签名本身不需要手机(云端生成证书),但 HarmonyOS 的 Debug Profile 会绑定允许调试的设备 UDID。如果配签名时没连手机,Profile 里没设备 UDID,debug 包装上去会报设备不匹配。所以建议先连手机再配签名,一次把 UDID 塞进 Profile。 --- ## 六、伏笔应验:版本号报错 晚上继续,用户报"发布到手机失败了"。读构建日志,错误 `00303015 Configuration Error`。读 `build-profile.json5` 发现: ``` compatibleSdkVersion: "6.1.1(24)" // 比 target 高 targetSdkVersion: "6.1.0(23)" ``` 这就是上午留的第一个伏笔--版本号是推断的。用户中间可能动过版本号,把 compatible 调到了 6.1.1(24),但本地只装了 API 23 的编译 SDK(6.1.1 仅有系统镜像用于模拟器),没有 API 24 的 ets SDK。规则要求 `compatible <= target <= 已装SDK`,所以必须把 compatible 降回 `"6.1.0(23)"`,让 `23 <= 23 <= 23` 成立。 上午推断的风险,晚上如实应验。 --- ## 七、装机:hdc 的路径坑与无线调试 版本号修好,构建出一个已签名的 hap(153K)。`hdc list targets` 确认设备已连。 然后撞了 hdc 的一个别扭坑: ``` hdc install "E:/Code/.../entry-default-signed.hap" # 报:no such file or directory, path:E:\Code\...\E:/Code/.../entry-default-signed.hap ``` 带盘符的正斜杠绝对路径,被 hdc 拼到了 cwd 前面。**改用相对路径**(`cwd` 是项目根)就过了: ``` hdc install "entry/build/default/outputs/default/entry-default-signed.hap" ``` 后来用户想切无线调试。`hdc shell ifconfig wlan0` 查到手机 WiFi 局域网 IP,用 `hdc tconn <手机IP>:<端口>` 连上,无线 `hdc install` 也成功。 --- ## 八、功能开发:批量上传与长按菜单 装上能跑了,用户提了四个功能:图片批量上传、前端图片直接预览、长按操作、不能预览的显示大文件图标占位。交互方案选了"纯长按菜单"(去掉右侧下载/删除按钮,列表更干净),批量上限 99 张。 ### 坑 4:ArkTS 严格模式拒绝 `Array