Penpot鸿蒙PC适配全记录：在HarmonyOS PC上运行开源设计工作台

承渊政道

11980人浏览 · 2026-09-13 18:44:55

承渊政道 · 2026-09-13 18:44:55 发布

一、为什么选择适配Penpot
二、先确定适配路线：保留原版工作区,拆分客户端与服务端
三、鸿蒙适配工程的目录组织
四、HarmonyOS PC 真机核心功能
五、适配过程中遇到的主要困难
六、关键适配改动
七、编译、安装与启动
八、当前可用范围与能力边界
九、总结

欢迎加入开源鸿蒙PC社区

欢迎在PC社区平台申请新建项目

适配开源地址

一、为什么选择适配Penpot

Penpot 是一套面向产品设计与团队协作的开源设计平台，覆盖界面绘制、组件与设计系统、原型连接、资源管理和多人协作等常用流程。与只提供图片标注或简单画板的工具不同，Penpot 的工作区需要同时处理高频指针事件、复杂图层、字体排版、矢量图形和持续同步，对浏览器图形栈与应用宿主都有较高要求。

选择 Penpot 进行 HarmonyOS PC 适配，首先是因为它代表了一类有实际生产价值的桌面创作工具。设计师需要大屏、键盘和精确指针操作，HarmonyOS PC 的窗口环境与 2in1 设备形态正适合承载这类工作流。其次，Penpot 的前端和渲染核心具备较清晰的开放架构：界面由 ClojureScript 与 React 驱动，画布关键路径使用 Rust、Skia 和 WebAssembly，后端则负责用户、文件、资源和协作数据。适配它可以同时检验 ArkWeb 对现代 Web 应用、WASM 图形和网络会话的承载能力。

本次适配没有把 Penpot 重新绘制成一套 ArkUI 页面。设计工具的价值集中在原版工作区和持续演进的上游能力，如果重写界面，不但工程量巨大，还会让后续同步 Penpot 版本变得困难。因此，鸿蒙侧新增独立的 ohos-pc/ 工程，以 ArkWeb 承载原版 Penpot SPA，并把服务地址、文件选择、下载和新窗口等平台差异集中在薄壳中。真机验证使用 Penpot 2.16.2 服务，鸿蒙应用版本为 1.0.0，Bundle Name 为 app.penpot.ohospc。

二、先确定适配路线：保留原版工作区,拆分客户端与服务端

Penpot 并不是一个可以直接塞进安装包的离线网页。它的前端在浏览器中运行，但登录、项目、文件、资源和协作状态都依赖后端服务；后端又依赖 PostgreSQL、Valkey 和 Exporter。把 JVM 服务和数据库一起搬进 HAP，既不符合移动应用沙箱的运行方式，也会显著增加安装包体积和维护成本。

最终采用“鸿蒙客户端 + 可配置 Penpot 服务”的结构：HarmonyOS PC 负责窗口、ArkWeb 和系统能力桥接；Penpot Backend、PostgreSQL、Valkey 与 Exporter 继续运行在局域网服务器或远程环境中。

层次	Penpot 原有实现	HarmonyOS PC 侧处理
应用入口	浏览器访问 Penpot 站点	`EntryAbility` 创建原生窗口并初始化 ArkWeb
工作区界面	ClojureScript、React、CSS	保留原版构建产物，由 ArkWeb 加载
画布渲染	Rust/Skia WebAssembly、WebGL2、Worker	继续在 ArkWeb 中执行，先通过内置能力探针校验
业务服务	JVM Backend、RPC、WebSocket	运行在局域网或远程服务器，HAP 通过网络连接
数据服务	PostgreSQL、Valkey、对象资源	保留服务端部署方式，不放入应用沙箱
文件导入	浏览器文件选择器	接入 `DocumentViewPicker`，把授权 URI 返回给网页
文件导出	浏览器下载	由 `WebDownloadDelegate` 写入应用下载目录
新窗口	`window.open` 等浏览器行为	通过 `onWindowNew` 在应用内承接弹出页面

应用启动链路如下：

EntryAbility
    ├── initializeWebEngine()
    ├── 初始化 ServerStore
    └── 加载 pages/Index
          ├── 读取已保存的 Penpot 服务地址
          ├── 创建 ArkWeb WebviewController
          ├── 启用 JavaScript / DOM Storage / IndexedDB / 混合内容
          ├── 挂接文件选择、下载与新窗口回调
          └── 加载原版 Penpot SPA
                ├── Backend RPC / WebSocket
                └── WASM + WebGL2 画布

这种拆分让 HAP 保持在约 214 KB，安装包只承担平台接入，不复制 Penpot 庞大的前后端产物。服务端可以独立升级、备份和扩容，鸿蒙客户端也可以连接团队现有的自建环境。

三、鸿蒙适配工程的目录组织

平台代码全部放在 ohos-pc/，原项目的 frontend/、backend/、common/ 和 render-wasm/ 保持上游结构。这样既便于审计鸿蒙改动，也能减少后续合并 Penpot 新版本时的冲突。

ohos_penpot/
├── frontend/                              # ClojureScript / React 前端
├── backend/                               # JVM 后端服务
├── common/                                # 前后端共享模型与逻辑
├── render-wasm/                           # Rust / Skia WASM 渲染模块
├── exporter/                              # 导出服务
└── ohos-pc/
    ├── AppScope/app.json5                 # Bundle、版本、图标与应用名
    ├── build-profile.json5                # SDK、产品与签名配置
    ├── entry/src/main/module.json5        # Ability、2in1 与网络权限
    ├── entry/src/main/ets/
    │   ├── entryability/EntryAbility.ets  # 生命周期、窗口和 Web 引擎初始化
    │   ├── pages/Index.ets                # ArkWeb、工具栏和系统回调
    │   ├── common/ServerStore.ets         # 服务地址校验与持久化
    │   └── bridge/DownloadBridge.ets      # 网页下载到应用沙箱
    ├── entry/src/main/resources/rawfile/
    │   └── probe.html                     # ArkWeb 关键能力探针
    ├── demo_checklist.md                  # 真机功能走查清单
    └── scripts/build-unsigned.sh          # Hvigor 构建入口

module.json5 当前只声明 2in1，窗口最小尺寸为 1280×800，并申请 INTERNET 与 GET_NETWORK_INFO。编译 SDK 为 6.0.2(22)，兼容 SDK 为 5.0.5(17)。这些配置对应的是鸿蒙桌面窗口应用，不包含 Qt 或 Electron 运行时。

四、HarmonyOS PC 真机核心功能

以下 5 张截图均在 2026 年 8 月 25 日对当前签名 HAP 覆盖安装并冷启动后重新采集。测试设备为 HUAWEI MateBook Pro（HAD-W32），系统软件版本为 6.1.0.117，CPU ABI 为 arm64-v8a，屏幕分辨率为 3120×2080。测试服务运行在同一局域网，真机实际完成了能力检测、注册引导、项目首页、文件创建、矩形绘制和文本输入。

1.ArkWeb能力探针确认画布运行前提

首次连接服务前，应用可以打开内置能力探针。真机结果显示 WebAssembly、WebGL2、Worker、OffscreenCanvas、WebSocket、IndexedDB、Local Storage、createImageBitmap 以及 WASM 实例化均进入真实调用路径，User Agent 为 OpenHarmony 6.1 上的 ArkWeb/Chrome 132。

在这里插入图片描述
探针中特意保留了失败和降级结果：当前环境没有 WebGL1，SharedArrayBuffer 与 crossOriginIsolated 也未启用，Clipboard API 处于降级状态。Penpot 当前画布以 WebGL2 为关键前提，因此这些结果不会阻止本轮绘制流程，但后续涉及高性能共享内存或完整剪贴板语义时仍需单独处理。

2.登录后进入原版项目首页

在真机完成演示账号注册和首次使用引导后，页面进入 Penpot 原版项目首页。左侧项目、草稿、字体和共享库导航可以正常显示，主区域提供新建文件、文件导入、库和模板入口，底部模板缩略图也能够通过网络加载。

在这里插入图片描述
这一页面不是鸿蒙侧仿制的静态界面。账号会话、项目统计、模板资源和导航状态均来自 Penpot Backend，说明 Ability、ArkWeb、HTTP 请求、Cookie/Storage 和前端路由已经在同一条真实用户路径上工作。

3.新建文件进入完整设计工作区

点击“新文档”后，真机创建了实际 Penpot 文件并进入设计工作区。左侧可以看到页面与图层区域，中间为带标尺的画布，顶部保留移动、画板、矩形、椭圆、文本、图片、曲线和路径工具，右侧为设计、原型与检查面板。

在这里插入图片描述
从项目首页切换到工作区会加载更多前端模块和 WASM 画布逻辑。空白画布稳定出现，说明本次验证已经越过“网页能够打开”的层次，进入 Penpot 最核心的编辑场景。

4.绘制矩形并读取尺寸与填充属性

在顶部工具栏选择矩形工具后，使用真机触控板在画布中拖拽创建对象。新图层以 Rectangle 出现在左侧，画布显示选区边界，右侧同步给出宽高、坐标、透明度和填充色 B1B2B5。

在这里插入图片描述
这次操作连续经过指针事件、工具状态、WASM/画布渲染、图层树更新和属性面板同步，不是单一按钮的显示验证。对象创建后仍保持选中状态，尺寸为 415×391，可继续调整填充、描边、阴影和导出设置。

5.创建文本并完成真实键盘输入

随后切换到文本工具，在画布输入 Penpot on HarmonyOS PC。文本对象出现在图层列表和画布中，右侧面板显示 Source Sans Pro、字号 14、字重 400、行高、对齐方式和黑色填充。

在这里插入图片描述
矩形与文本保存在同一个文件中，图层顺序和对象属性可以继续选择查看。这一场景验证了键盘输入、文本渲染、图层创建和排版面板之间的联动，也说明 ArkWeb 在鸿蒙 PC 窗口中能够承载 Penpot 的基本设计操作。

五、适配过程中遇到的主要困难

难点一：Penpot不是单体桌面应用

前端页面能够显示，并不代表项目管理和编辑链路可用。Penpot 的认证、文件、媒体、RPC 与协作都依赖服务端，服务端又依赖数据库、缓存和 Exporter。适配初期最重要的工作不是改 UI，而是先划定部署边界：HAP 只做客户端，后端组件继续按 Penpot 官方架构部署。这样才能避免把数据库塞进应用沙箱，也不会让客户端更新与团队数据绑定在一起。

难点二：服务端公开地址必须与真机网络一致

Penpot 会根据 PENPOT_PUBLIC_URI 生成前端配置、资源地址和部分回调链接。开发机浏览器使用 localhost 时一切正常，但真机无法通过自己的 localhost 访问 Mac。实际联调需要把公开地址改为构建机在局域网中的可达 IP，并确认 9001 端口、前端静态资源、Backend API 和 WebSocket 都能从设备访问。页面只加载出框架而资源、登录或文件请求失败，往往不是 ArkWeb 渲染问题，而是服务地址仍指向开发机回环接口。

难点三：设计画布依赖的不只是普通JavaScript

Penpot 工作区会进入 WebAssembly、WebGL2、Worker、OffscreenCanvas 和 IndexedDB 等路径。只用简单页面验证 ArkWeb，无法判断设计画布能否运行。因此适配工程加入独立探针，在连接业务服务前逐项执行 API 和 WASM 实例化测试，并原样展示失败结果。本轮真机确认 WebGL2 与 WASM 可用后，才继续验证矩形和文本操作。

难点四：浏览器文件语义需要映射到鸿蒙系统能力

网页中的 <input type="file">、下载和保存不能假定拥有桌面文件系统权限。onShowFileSelector 需要调用 DocumentViewPicker，由用户授权后再把 URI 列表交还 ArkWeb；导出下载则通过 WebDownloadDelegate 写入应用沙箱的 downloads 目录，并在完成或失败时提供明确反馈。当前桥接代码已经接入构建，文件导入和导出还需要针对具体格式继续完成端到端对照，不能仅凭回调存在就认定所有文件流程已经闭环。

难点五：网页新窗口不能脱离HAP生命周期

登录、帮助、外链或导出流程可能调用 window.open。如果沿用桌面浏览器语义，新页面可能没有宿主承接，或者直接丢失控制器。适配中开启 multiWindowAccess 与 allowWindowOpenMethod，在 onWindowNew 中取得目标 URL 和 handler，再由应用内的第二个 WebviewController 接管，关闭时同步清理页面状态。

难点六：必须区分“API 存在”与“设计动作完成”

能力探针只能回答底层接口是否可调用。真正的适配结果还要沿用户路径检查：账号能否进入项目页、新建文件能否打开画布、指针拖拽能否生成图层、属性面板是否同步、键盘输入能否形成文本对象。本次截图按这条顺序采集，避免用一个加载成功的首页代替完整设计工作区验证。

六、关键适配改动

1.用EntryAbility管理Web引擎与桌面窗口

EntryAbility.ets 在 onCreate 中初始化 ArkWeb 引擎，在 onWindowStageCreate 中等待偏好数据就绪后加载 pages/Index，并把窗口标题设置为 Penpot。Ability 只负责生命周期和宿主，不接管上游业务状态。

2.提供可切换、可持久化的服务地址

ServerStore.ets 使用 Preferences 保存 baseUrl，启动时自动恢复上次连接。输入地址会先去除末尾斜杠，并限制为 http:// 或 https://。工具栏中的“服务器”入口可以随时返回配置页，便于在本地、自建和远程 Penpot 环境之间切换。

3.按 Penpot需求配置ArkWeb

主 Web 组件开启 JavaScript、DOM Storage、数据库访问、在线图片、文件访问和混合内容，并使用默认缓存与关闭自动深色模式。SSL 回调为自建证书提供处理入口，权限请求根据网页声明进行授权，控制器挂接后再注册下载代理，避免初始化时序早于 Web 引擎。

4.接入文件选择与下载桥

网页发起单选或多选时，DocumentViewPicker 分别限制为 1 个或最多 20 个文件；取消和异常都会返回空列表，避免网页一直等待。下载文件名先过滤路径非法字符，再保存到应用沙箱，日志统一使用 PenpotOhos 标签，便于真机定位失败原因。

5.在应用内承接弹出窗口

主 Web 收到新窗口事件后记录 targetUrl 与 handler，显示覆盖式弹出 Web，并用独立的 popupController 建立关联。该实现保留页面原有打开方式，同时让窗口仍受 HarmonyOS Ability 管理。

6.把兼容性检查做成可重复的内置页面

probe.html 随 HAP 打包，不依赖 Penpot 服务即可运行。它输出 User Agent、WASM、WebGL、Worker、存储、剪贴板和隔离状态，并保留 JSON 原始结果。后续 ArkWeb 或系统版本升级时，可以先运行探针，再决定是否需要调整前端能力或服务端响应头。

七、编译、安装与启动

1.获取项目并准备服务

从 AtomGit 获取适配工程：

git clone https://atomgit.com/OpenHarmonyPCDeveloper/ohos_penpot.git
cd ohos_penpot

客户端需要连接一个真机可访问的 Penpot 服务。可以使用现有自建环境，也可以按 Penpot 官方容器方式部署。局域网联调时应将 PENPOT_PUBLIC_URI 设置为设备能够访问的地址，例如：

http://192.168.1.100:9001

不要填写仅对开发机自身有效的 localhost。正式环境应使用可信 HTTPS 域名，并按团队要求配置反向代理、备份和访问控制。

2.构建 HarmonyOS PC HAP

准备 DevEco Studio、HarmonyOS API 22 SDK 和 JBR 21，并在 DevEco Studio 中生成与真机匹配的调试签名。进入鸿蒙工程执行：

cd ohos-pc
./hvigorw assembleHap \
  --mode module \
  -p module=entry@default \
  -p product=default \
  -p buildMode=debug \
  --no-daemon

签名产物位于：

ohos-pc/entry/build/default/outputs/default/
└── entry-default-signed.hap

本轮生成的签名 HAP 为 218705 字节，约 214 KB。签名材料属于本地设备配置，不应提交到公共仓库。

3.安装并在真机启动

hdc list targets
hdc install -r \
  ohos-pc/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa force-stop app.penpot.ohospc
hdc shell aa start -a EntryAbility -b app.penpot.ohospc

本次真机返回 install bundle successfully 与 start ability successfully。首次启动先运行“探针”，确认 WebAssembly 与 WebGL2 通过，再填写 Penpot 服务地址。可使用以下命令观察应用日志：

hdc hilog

日志中搜索标签 PenpotOhos，可以查看 Ability 生命周期、Web 控制器、页面错误、文件选择和下载状态。

八、当前可用范围与能力边界

当前版本已经在 HarmonyOS PC 真机确认以下能力：

签名 HAP 可以覆盖安装，EntryAbility 可以冷启动；
ArkWeb 能够加载局域网中的 Penpot 2.16.2 前端和认证页面；
注册、首次引导、项目首页与模板资源可以正常显示；
WebAssembly、WebGL2、Worker、OffscreenCanvas、WebSocket 和 IndexedDB 可用；
可以新建真实 Penpot 文件并进入原版设计工作区；
矩形拖拽能够创建图层，尺寸、坐标和填充属性同步显示；
键盘输入能够创建文本对象，字体、字号、字重和对齐属性可见；
服务地址能够校验、保存并在应用重启后恢复；
HAP 已声明网络权限，应用窗口支持 2in1 设备和最小尺寸约束。

以下能力仍需继续验证或完善：

SharedArrayBuffer 与 crossOriginIsolated 当前不可用，需要结合服务端 COOP/COEP 响应头评估；
Clipboard API 处于降级状态，复杂图层跨文档复制需要专项验证；
文件选择和下载桥已接入，但 .penpot 导入、图片导入及多种导出格式尚未逐项做内容对照；
多窗口承接逻辑已实现，登录外链、帮助页和第三方集成仍需分别走查；
多人实时协作、评论、版本历史、原型播放和共享链接未纳入本轮五个核心场景；
本轮服务运行在局域网开发环境，生产部署仍需 HTTPS、证书、域名和数据备份；
离线编辑不是当前架构目标，客户端无法访问 Backend 时只能显示网络错误或缓存内容；
触控手势、手写笔压感、高分屏多窗口和长时间大型文件性能仍需扩大测试范围。

九、总结

Penpot 的 HarmonyOS PC 适配已经完成从 ArkTS Ability、ArkWeb 配置、服务地址持久化、系统文件桥接，到 HAP 构建签名和真机启动的主链路。本轮验证也没有停在登录页：真机实际进入了项目首页和原版设计工作区，完成矩形绘制、属性同步、文本输入和排版属性显示，证明 Penpot 最基本的创作路径能够在鸿蒙 PC 上运行。

这次适配的关键不是重写一套设计工具，而是保留 Penpot 已经成熟的前端、WASM 画布和服务协议，把 HarmonyOS 的窗口生命周期、网络入口和系统文件语义收敛到平台层。这样的边界既能控制 HAP 体积，也便于后续跟随上游升级。下一阶段应优先补齐文件导入导出的端到端验证、剪贴板和跨窗口行为，再扩展到多人协作、原型播放与大型文件性能测试，让当前可用的单人设计流程逐步形成更完整的生产工作流。