---

开篇引子

📌 摘要：本文是一位在校大学生开发 HarmonyCanvas（鸿绘协作板）——一个面向考研人群的「分布式协同白板 + 空间手写双向链接笔记」应用——的完整复盘。文章从项目定位、技术栈（ArkTS + ArkUI + DevEco Studio）讲起，拆解了 LinkLayer、MiniMap、SearchBar 等核心模块，并重点分享了 6 个真实踩坑实录（画布尺寸为 0、modelVersion 层级、module.json5 配置、devDependencies 误用、rawfile 路径、API 12 兼容），最后给出比赛「四件套」应对思路、OpenHarmony 开源硬件生态观察（小鸿 AI 开发板）以及给新手的 5 条建议。适合想入局 OpenHarmony 应用开发的同学对照自查、少走弯路。

我是一个再普通不过的在校大学生。和很多人一样，曾经觉得「国产操作系统」是新闻里的事，离写代码很远。直到某天，我在图书馆用平板记考研笔记，纸笔凌乱、跨设备同步卡顿、想给一个知识点反向链接到另一页却怎么都做不到——那一刻我突然想：能不能自己做一个真正好用的笔记应用，而且就跑在国产的 OpenHarmony / HarmonyOS 上？
这不是一时冲动。这几年「国产操作系统 + 真实能用的应用」这件事，意义远比我们想象的大：系统再强，没有应用生态就是空壳；而开发者愿意为它写第一行代码，生态才开始活起来。于是我启动了 HarmonyCanvas（鸿绘协作板），一个面向考研人群的分布式协同白板 + 空间手写双向链接笔记应用，并把它推上了 OpenHarmony 应用比赛。
这条路，远没有教程里那么顺。从环境搭建、画板渲染被一个 0 卡死，到 module 配置反复报错，再到比赛要求「真实可用、万人并发、跨设备协同、原子化服务」时的一脸懵——我把自己踩过的坑、沉淀的工程资产、还有对 OpenHarmony 生态的另一面（开源硬件）的理解，全写在这篇复盘里。如果你也想入局 OpenHarmony，这篇文章能帮你少走至少一半弯路。
—

这个项目是什么：HarmonyCanvas（鸿绘协作板）

一句话定位：HarmonyCanvas 是一个面向考研人群的「分布式协同白板 + 空间手写双向链接笔记」应用，包名 com.harmonycanvas.app，目标上架华为应用市场。
为什么做它？考研党的真实痛点很具体：

• 知识点是网状的，但传统笔记是线性的——需要一个**双向链接（Bidirectional Link）**把「高数公式」和「它出现的真题页」连起来；

• 复习要在手机、平板、PC 之间反复横跳——需要分布式协同，一处改动多端同步；

• 手写最自然，但手写内容搜不到——需要手写内容搜索。对标竞品时，我没想「再造一个 GoodNotes」，而是取其精华去其糟粕 + 用户反馈驱动：

• 享做 / Starnote / 云记：借鉴它们的纸张质感与笔迹流畅度；

• GoodNotes / 华为笔记：借鉴它们的资料管理与系统级集成；

• 差异化：把「双向链接层」和「分布式协同」做成底层能力，而不是外挂功能。用户反馈里最常被提到的「复习时找不到关联知识点」，正好用双向链接解决。

---

技术栈与开发环境（给新手一句「怎么开始」）

核心栈：

• 语言/框架：ArkTS + ArkUI（声明式开发），Stage 模型；
• IDE：DevEco Studio（截至 2026-08-25，最新稳定版为 DevEco Studio 6.1.1 Release，2026/05/26 发布，配套 API 24 / HarmonyOS 6.1.1；官方对新应用「推荐使用」的是 6.0.0(20)，本文开发基于 6.1.x 验证，请以官网最新为准）；
• 系统版本：测试机为 MatePad Pro 13 模拟器（HarmonyOS 6.1.1，API 24）；
• 平台：Windows + DevEco Studio + PowerShell 工作流。

我的命令行工作流（Windows / PowerShell，路径与你的真实环境一致）：

# 1) hvigorw 在工程 tools\hvigor\bin 目录下，工程根目录执行打包
.\tools\hvigor\bin\hvigorw assembleHap --mode module -p product=default

# 2) hdc 在 SDK 的 toolchains 目录，先确认设备是否被识别
$hdc = "$env:HARMONY_SDK_HOME\toolchains\hdc.exe"
& $hdc list targets
# 输出示例：
# 127.0.0.1:5555    device   <- MatePad Pro 13 模拟器

# 3) 安装到模拟器
& $hdc install entry\build\default\outputs\default\entry-default-signed.hap

💡 给新手的「怎么开始」一句话：先装 DevEco Studio 最新稳定版 → 新建 Empty Ability（Stage + ArkTS）模板 → 跑通官方 HelloWorld → 再碰 Canvas 和分布式，别一上来就堆功能。

---

核心功能拆解（用真实组件名说话）

🖼️ 插入图片｜功能/架构示意：上传文件 img_hc_architecture.png 后，在此处点「插入图片」替换本行

源码根在 entry/src/main/ets/，组件集中在 components/，渲染引擎在 engine/。下面这些不是 PPT 名词，是真正扛住功能的模块：

1. LinkLayer（双向链接层）

解决什么：把任意两个笔记页 / 白板块建立双向引用，点击 A 能跳到 B，B 上也回显「被 A 引用」。它是 HarmonyCanvas 差异化的灵魂，区别于普通白板的「单向跳转」。

2. MiniMap（缩略图导航）

解决什么：考研笔记页数动辄上百，MiniMap 提供全局缩略图，快速定位「我在哪、知识网长什么样」，避免在大画布里迷路。

3. BookmarkBar（书签栏）

解决什么：把高频考点、错题页钉成书签，跨页秒达；数据层与 LinkLayer 解耦，保证书签不随链接结构变动而丢失。

4. SearchBar（手写内容搜索）

解决什么：手写最自然，但最难检索。SearchBar 对接手写识别结果做全文索引，支持「写过的公式也能搜到」，这是对标 GoodNotes 时我坚持要做的能力。

5. engine/ 渲染引擎

解决什么：白板笔迹、图形、图片的混合渲染与增量重绘。把渲染从 UI 组件里抽出来，是后面「画板被 0 卡死」能快速定位的前提。

6. 设计资产：T01 设计令牌 + T05a 断点规范

• T01 设计令牌：统一 HCColor / HCGray / HCSpace / HCRadius 四组令牌，杜绝「这里红一点那里灰一点」的样式漂移；
• T05a 断点规范：sm / md / lg 三档断点布局，让同一套代码在手机、平板（如 MatePad Pro 13）、2in1 上都有合理排布。

这些资产来自参赛过程中沉淀的 48 项优化建议报告（功能类 F-01~F-14、UI 类 U-01~U-05），是项目从「能跑」到「好用」的硬通货。

---

踩坑实录（最值钱的一节）

这一节是我调试到凌晨的真实吐槽合集。每个坑都给「现象 + 代码/配置片段 + 解法」。建议收藏，对照自查。

坑 (a)：canvasWidth / canvasHeight 初始化为 0，画板直接「死」了

现象：白板页面打开后完全空白，手写没反应，Console 没有明显报错，但 engine 拿到的画布尺寸是 0。

根因：在 WhiteboardPage.ets 里，我把 canvasWidth / canvasHeight 初始化成 0，并在 aboutToAppear 阶段就用这两个 0 去创建渲染上下文——而此时组件还没布局完，真实尺寸根本没拿到，后续所有绘制和书写都被阻断。

// ❌ 错误写法：布局未完成就用 0 初始化
@Entry
@Component
struct WhiteboardPage {
  private canvasWidth: number = 0;   // 初始化为 0
  private canvasHeight: number = 0;  // 初始化为 0
  private settings: RenderingContextSettings = new RenderingContextSettings(true);
  private canvasCtx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);

  aboutToAppear(): void {
    // 组件还没布局，拿不到真实尺寸，这里画布等于"空壳"
    this.engine.init(this.canvasCtx, this.canvasWidth, this.canvasHeight);
  }

  build() {
    Canvas(this.canvasCtx)
      .width(this.canvasWidth)   // 0
      .height(this.canvasHeight) // 0
  }
}

解法：渲染上下文先建好，但真实尺寸必须等布局完成（onAreaChange）后再初始化画布。高优先级 bug，修完书写立刻恢复。

// ✅ 正确写法：用 onAreaChange 拿真实尺寸后再初始化
@Entry
@Component
struct WhiteboardPage {
  private canvasWidth: number = 0;
  private canvasHeight: number = 0;
  private settings: RenderingContextSettings = new RenderingContextSettings(true);
  private canvasCtx: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);

  build() {
    Canvas(this.canvasCtx)
      .width('100%')
      .height('100%')
      .onAreaChange((_oldValue: AreaSize, newValue: AreaSize) => {
        // 关键：拿到真实布局尺寸后再初始化 / 重绘
        this.canvasWidth = newValue.width as number;
        this.canvasHeight = newValue.height as number;
        this.engine.init(this.canvasCtx, this.canvasWidth, this.canvasHeight);
      })
  }
}

坑 (b)：modelVersion 配置位置放错层级

现象：hvigorw 构建直接报「无法识别的工程模型版本」，工程打不开。

根因：modelVersion 是 oh-package.json5 的顶层字段，我误把它塞进了 dependencies 里，导致解析失败。

// ❌ 错误：把 modelVersion 放进 dependencies
{
  "name": "harmonycanvas",
  "version": "1.0.0",
  "dependencies": {
    "modelVersion": "5.0.0"
  }
}

// ✅ 正确：modelVersion 是顶层字段
{
  "name": "harmonycanvas",
  "version": "1.0.0",
  "modelVersion": "5.0.0",
  "dependencies": {}
}

坑 ©：module.json5 的 abilities / skills 配置问题

现象：应用装上了，但桌面没有图标、点不开，或「右滑卡片」拉不起应用。

根因：abilities 里 skills 的 entities / actions 配错，导致系统「主页」意图匹配不到入口 Ability。

// ✅ 标准入口 Ability 配置（节选）
{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}

解法：确保入口 Ability 的 skills 含 entity.system.home + action.system.home，且 exported: true；多 Ability 时注意 mainElement 指向正确。

坑 (d)：devDependencies 误声明运行时依赖

现象：本地 Previewer 正常，真机/模拟器一运行就报「找不到模块」。

根因：把一个运行时真正需要的依赖误写进了 devDependencies。devDependencies 不会被打包进 HAP，运行时自然缺模块。

// ❌ 错误：运行时要用的库放进了 devDependencies
{
  "dependencies": {},
  "devDependencies": {
    "[@xyz/ui-kit": "1.2.0"   // 实际运行时也要用！
  }
}

// ✅ 正确：运行时依赖放 dependencies
{
  "dependencies": {
    "@xyz/ui-kit": "1.2.0"
  },
  "devDependencies": {}
}

解法：只有构建期工具（如类型定义、lint）才进 devDependencies；任何在 import 里被业务代码引用的，都必须进 dependencies。

坑 (e)：rawfile 资源目录位置踩坑

现象：getRawFileContent 读不到字体/模板资源，报文件不存在。

根因：rawfile 必须放在 entry/src/main/resources/rawfile/ 下（区分大小写），我一度放到 resources/base/ 或工程根目录，路径自然不对。

✅ 正确结构：
entry/src/main/resources/rawfile/
└── templates/
    └── kaoyan_cover.bin

❌ 错误位置：
entry/src/main/resources/base/rawfile/   (目录层级错)
project_root/rawfile/                      (不在 module 内)

解法：rawfile 严格置于 entry/src/main/resources/rawfile/，用 getContext().resourceManager.getRawFileContent('templates/kaoyan_cover.bin') 读取。

坑 (f)：API 12 兼容性适配问题

现象：在低版本设备/模拟器上，部分 ArkUI 新能力直接崩溃或失效。

根因：我用到的一些能力是 API 12（HarmonyOS 5.0.0）及以上才稳定支持。未在 build-profile.json5 正确设 compatibleSdkVersion，也没做降级。

// ✅ 用设备 API 版本做兼容守卫
import { deviceInfo } from '@kit.BasicServicesKit';

if (deviceInfo.sdkApiVersion >= 12) {
  // 使用 API 12+ 的手势 / 组件新能力
  this.enableAdvancedGesture();
} else {
  // 降级到兼容方案，保证低版本不崩
  this.enableFallbackGesture();
}

同时在 build-profile.json5 合理设置：

{
  "app": {
    "signingConfigs": [],
    "compatibleSdkVersion": "6.0.0(20)",
    "products": [{ "compileSdkVersion": "6.1.1(24)", "targetSdkVersion": "6.1.1(24)" }]
  }
}

（版本号以官网「所有 HarmonyOS 开发套件版本」页最新为准；本文基于 6.1.1(24) 验证。）

---

比赛视角：官方要的「四件套」我怎么接

比赛（无论你参加的是「开源鸿蒙大学生创新大赛·校园与创新应用」还是「开放原子开源大赛·原生 AI 应用开发大赛」）对作品核心看真实可用、万人并发、跨设备协同、原子化服务四个维度。我的应对思路：

• 真实可用：靠那 48 份优化报告（F-01~F-14 功能类、U-01~U-05 UI 类）闭环打磨；每个吐槽点都变成一条可执行项，而不是「感觉差不多」。
• 万人并发：作为学生项目，重点在架构可扩展——渲染与状态分离（engine/ 独立）、数据层可接分布式 KV，为后续水平扩展留口子；这一项我如实写成「架构准备」而非夸大。
• 跨设备协同：HarmonyCanvas 的立身之本。基于 OpenHarmony 分布式能力（分布式软总线 + 跨设备数据同步），白板改动在手机/平板/PC 间接力，正是「分布式体验」赛题的题眼。
• 原子化服务：把高频能力（如「一键开空白白板」「今日待复习链接」）设计为元服务 / 原子化服务卡片，无需完整打开 App 即可被系统智慧分发拉起，呼应比赛对「原子化服务」的要求。

老实说，这些维度对单人学生项目是「高标」。我的态度是：不注水、不夸大，把能落地的落地，把架构想清楚的写清楚——这比硬编数据更有说服力，也更符合 OpenHarmony 社区的氛围。

---

OpenHarmony 生态的另一面：软件之外，开源硬件也起来了

做应用这一年，我最大的认知转变是：OpenHarmony 不只在手机和平板的屏幕里，它正在往下扎进芯片和电路板。

说到这必须提 小鸿 AI——AtomGit 推出的全开源端侧 AI 开发板，也是我看 OpenHarmony 生态「从应用到硬件」完整闭环的最佳样本：

• 芯片：海思 WS63，采用 RISC-V 32 位架构，主频最高 240MHz；
• 系统：搭载 OpenHarmony 6.0/6.1 轻量系统（双开源：开源鸿蒙 + RISC-V）；
• 无线：集成 星闪 NearLink（SLE 1.0），并支持 Wi-Fi 6、BLE 5.2；
• 交互：1.54 寸 TFT 彩屏（240×240），CI1302 语音芯片支持离线唤醒；
• 可玩性：硬件原理图、PCB、BOM、全量系统代码全部开源，还能在云端配置专属语音智能体，做「一声唤醒，万物响应」的智能家居中枢。

我特别喜欢它的一点：它不是封死的智能音箱，而是一块你能改写固件、接外设、训练专属语音助手的开发板。当我的 HarmonyCanvas 在平板上跑，小鸿 AI 在桌面上用星闪联动家里的灯和窗帘——这一刻，「OpenHarmony 从软件应用走到开源硬件」这件事，变得非常具体。

这也是为什么我坚持在文章打上 openharmony 标签：国产操作系统的生态，本就该应用与硬件双轮驱动。

---

给想入局 OpenHarmony 的新手：5 条真心建议

1. 先吃透 ArkTS + ArkUI 声明式思维：别用写 Android/iOS 的命令式脑子硬套。先理解 @State / @Prop / @Link 的状态驱动，白板这类高频重绘场景能少写一半 bug。
2. 环境一次配好，别反复重装：DevEco Studio 装最新稳定版，配好 OHPM 国内镜像（registry=https://ohpm.openharmony.cn/ohpm/），hvigorw 卡 45% 多半是源的问题。
3. 版本号看官网口径，别只看大小：官方「所有 HarmonyOS 开发套件版本」页会标注「推荐使用 / 按需使用」，compatibleSdkVersion 别乱抬，否则真机装不上。
4. 多看真实工程，少看碎片化教程：AtomGit、开源鸿蒙社区、官方文档三件套走起；像「小鸿 AI」这种全开源硬件项目，连芯片移植都公开，是学底层适配的宝藏。
5. 先做一个「小而真」的东西再参赛：别一上来就想做大。一个能真正解决自己痛点的小应用，比十个 Demo 更能帮你理解 OpenHarmony 的分布式与原子化服务。

---

结语 + 互动话术 + 下篇预告

写到这，画板上的笔迹已经从一团乱麻变成了清晰的知识网。回头看，OpenHarmony 给我最大的礼物不是某个 API 怎么用，而是一个普通学生，也能在国产操作系统上，留下自己写的一行代码、一个能用的应用。

如果你也在做或想做 OpenHarmony 应用，别怕踩坑——坑踩完了，就是你的资产。

👍 觉得有用，点个赞让更多同学看到；
⭐ 收藏这篇，踩坑时回来对照；
💬 评论区聊聊你踩过最离谱的鸿蒙坑，我挨个回；
➕ 关注我，后续持续更 OpenHarmony 实战。

下篇预告（二选一，听你们的）：

• 《小鸿 AI 烧录我自己的第一个 C 应用：WS63 + OpenHarmony 底层适配实录》
• 《分布式协同白板底层原理：OpenHarmony 软总线是怎么把两块画板连起来的》

---