准备开发环境

本文档介绍开发 OpenDesk 所需安装的依赖项，含桌面端通用环境（Node.js / Electron）与 HarmonyOS HAP 构建环境。

1. NVM (Node Version Manager)

我们建议使用 NVM 来安装和管理不同平台上的 NodeJS 和 NPM。

Windows

nvm-windows 下载最新的 Release 版本安装包安装即可。

macOS

macOS 环境推荐使用 nvm，按照官网指引或直接执行以下命令安装：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

或者使用 Homebrew：

brew install nvm

Linux

Linux 环境推荐使用 nvm，按照官网指引或直接执行以下命令安装：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后，首先重启终端，然后在终端中 (Powershell, Bash, 命令提示符, …) 中运行如下指令，正常输出就说明已经正确安装。

$ nvm version
1.2.2

2. 安装 NodeJS 和 NPM

使用 NVM 安装最新版本的 NodeJS（这里以v25.2.1为例，你可以使用最新版本或任何你习惯的18以上的版本）：

$ nvm install v25.2.1
$ nvm use v25.2.1
$ node -v
v25.2.1

Windows Arm64 特别说明

⚠️ Windows Arm64 用户注意：nvm-windows 默认安装的 NodeJS 是 x86 架构，虽然可以通过转译层运行，但性能较差。请务必按以下步骤安装 Arm64 原生版本。

安装 NodeJS 时必须指定 arm64 架构：

$ nvm install v25.2.1 arm64
$ nvm use v25.2.1 arm64
$ nvm list
# 应当看到
#   * 25.2.1 (Currently using arm64-bit executable)
#              ~~~~~~~~~~~ 注意这里必须是 arm64

如果 nvm list 显示的是 64-bit 或 32-bit 而非 arm64-bit，说明安装错误。

3. 配置国内镜像源

国内用户建议配置镜像源以加速下载。

3.1 配置 NPM 镜像

$ npm config set registry https://registry.npmmirror.com
$ npm config get registry
https://registry.npmmirror.com

3.2 配置 Electron 镜像

Electron 安装过程中会单独下载二进制文件，需要额外配置镜像。

Windows

在 Windows 环境变量中添加：

变量名	值
ELECTRON_MIRROR	https://npmmirror.com/mirrors/electron/

PowerShell 设置方式：

[Environment]::SetEnvironmentVariable("ELECTRON_MIRROR", "https://npmmirror.com/mirrors/electron/", "User")

CMD 设置方式：

setx ELECTRON_MIRROR "https://npmmirror.com/mirrors/electron/"

设置后需重新打开命令行窗口生效。

macOS

在 ~/.zshrc 中添加：

echo 'export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/' >> ~/.zshrc
source ~/.zshrc

Linux

在 ~/.bashrc 中添加：

echo 'export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/' >> ~/.bashrc
source ~/.bashrc

4. 安装项目的NPM依赖三方库

进入 OpenDesk 代码仓库目录，执行：

$ npm install --verbose

该命令会自动安装所有依赖（包括 Electron）。

5. 验证项目安装

安装完成后，可以尝试运行 Opendesk Cli 来检查是否安装正常：

$ npm run cli

如果一切正常，你应当可以看到下面的界面。

然后再验证下桌面端是否可以正常运行:

$ npm run start

如果一切正常，你应当可以看到我们的桌面端图形界面。

接下来就可以开始 Opendesk 的开发了!

正常情况下，Opendesk的开发者团队会定期构建和推动安装包到:

• opendesk-cli cli版本会推送到npmjs，方便通过npm一键安装;
• opendesk-desktop 这里将持续发布桌面端的新版本;

但如果你需要本地构建可以安装到不同设备上的桌面端安装包，你仍然需要继续安装下面的依赖。

6. 打包依赖安装

构建 Windows 安装包所需的依赖

构建 MacOS 安装包所需的依赖

构建 HarmonyOS (HAP) 安装包所需的依赖

基于 HarmonyOS/OpenHarmony 的 OpenDesk 桌面版 HAP 由独立工程 OpenDesk-ohos 构建与维护。请先完成上文第 1–5 节（Node.js 与 OpenDesk 主仓依赖），再按本节准备鸿蒙构建环境并出包。

工程结构

OpenDesk-ohos/
└─ ohos_hap/
   ├─ electron/                 # Electron 主模块（ArkTS）
   ├─ web_engine/               # Web 引擎与适配层（ArkTS）
   ├─ patches/                  # 对内嵌 app 仓库应用的补丁
   ├─ build_hap.py              # 一键构建脚本
   ├─ daily_build_and_upload.py # 每日构建 + 上传（ssh / r2 / both）
   ├─ r2_upload_file.py         # 独立 Cloudflare R2 上传脚本
   └─ build-profile.json5       # 工程产品 / 签名配置

环境要求

项目	要求
操作系统	Windows 10/11 或 macOS Tahoe 及以上
Python	3.9+
DevEco Studio	≥ 6.1.0 Beta2（见下文）
SDK	与工程匹配；当前 compatibleSdkVersion 为 6.0.1(21)（见 ohos_hap/build-profile.json5）
Git LFS	拉取 .so / .zip 等大文件（见下文）
其他工具	可用的 git、npm、ohpm、scp（若走 SSH 上传）；boto3（若走 R2 上传）

build_hap.py 会优先自动解析 DevEco 自带的 Node / hvigor 工具链，并在子进程中注入构建所需环境变量，一般无需手工 setx。

安装 DevEco Studio

在 鸿蒙开发者网站 注册账号，并下载安装 DevEco Studio，建议最低版本为 DevEco Studio 6.1.0 Beta2。

项目	说明
推荐版本	6.1.0 Beta2 及以上：自动签名 Profile 的 ACL 可包含 ohos.permission.CUSTOM_SANDBOX
默认安装路径	Windows：D:\DevEco Studio；macOS：/Applications/DevEco-Studio.app/Contents
自定义路径	构建时传 --devec-root，或设置环境变量 DEVECO_STUDIO_HOME
SDK 对齐	请在 DevEco 中安装 API 6.0.1(21)，避免 hvigor 报 SDK 版本不匹配

安装时请记下 DevEco 的安装路径；若路径非默认，后续构建需通过 --devec-root 或 DEVECO_STUDIO_HOME 指定。

在 SDK 中开放部分受限权限

OpenDesk 桌面版运行需要额外申请以下受限权限：

• ohos.permission.READ_WRITE_USER_FILE — bash、nodejs 等工具依赖家目录下的配置文件，需提前申请家目录读写权限
• ohos.permission.CUSTOM_SANDBOX — nodejs 需使用 io_uring 等高性能接口，在鸿蒙权限模型下需启用自定义沙箱以放通相关系统调用

为了让这些权限申请能够正常使用，你需要手动修改 SDK 下的授权模板文件。该文件位于：

sdk/default/openharmony/toolchains/lib/UnsgnedReleasedProfileTemplate.json

打开后修改以下字段：

{
    ...,
    "bundle-info": {
        ...,
        "apl": "system_basic",
        ...
    },
    "acls": {
        "allowed-acls": [
            "ohos.permission.READ_WRITE_USER_FILE",
            "ohos.permission.CUSTOM_SANDBOX"
        ]
    },
    ...
}

修改完成后重新生成签名，再继续构建。

克隆 OpenDesk-ohos 与 Git LFS

git clone https://gitcode.com/openharmony-robot/OpenDesk-ohos.git
cd OpenDesk-ohos

仓库通过 Git LFS 管理 *.so、*.zip 等大文件（如 ohos_hap/electron/libs/arm64-v8a/ 下的原生库）。若克隆后 .so 只有几 KB 的指针文件，或构建报找不到有效原生库，请执行：

git lfs install    # 每台机器首次使用 LFS 时执行一次
git lfs pull       # 在仓库根目录拉取 LFS 对象

也可在克隆时一并拉取：GIT_LFS_SKIP_SMUDGE=0 git clone <仓库地址>。

个人调试证书签名的适用范围

ohos_hap/build-profile.json5 默认使用 HarmonyOS 自动调试签名（本机 .ohos/config 下的 .p12 / .cer / .p7b），仅适用于：

适用	不适用
本机或团队内开发、联调、自测	应用市场上架、对外正式发布
已在 Profile 登记的调试设备上安装运行	未登记设备上的长期分发
快速迭代 HAP、验证权限与功能	生产合规发布、企业 MDM 大规模下发

调试证书与 Profile 会过期；签名失败时请在 DevEco 中重新「自动签名」并更新 build-profile.json5 中的材料路径。勿将含密码的签名配置提交到公共仓库；对外交付需使用华为 发布证书 与对应 Profile。

嵌入 OpenDesk 应用代码

仓库默认不包含内嵌 app 仓的完整代码。构建前须补全目录 ohos_hap/web_engine/src/main/resources/resfile/resources/app，或通过 --use-opendesk-root 从本地 OpenDesk 主仓注入。

本地调试（推荐）：使用已完成上文第 4–5 节的 OpenDesk 主仓路径，构建时复制到 HAP 工程并自动打补丁、裁剪，不会修改源 OpenDesk 目录：

cd ohos_hap
python build_hap.py --use-opendesk-root /path/to/OpenDesk

生产 / CI：在内嵌目录克隆 app 仓库并同步到 origin/main 后构建：

cd ohos_hap/web_engine/src/main/resources/resfile/resources
git clone <你的app仓库地址> app
cd app && git checkout main && git pull

cd ../../../../../../..   # 回到 ohos_hap
python build_hap.py

默认构建流程：同步内嵌 app → 应用 patches/*.patch → npm prune + slim → ohpm install --all → hvigor assembleHap。

构建 HAP

在 ohos_hap 目录执行一键构建：

cd ohos_hap
python build_hap.py

分步构建（适合 CI 分 job，或先验证 app 裁剪再反复编 HAP）：

# 阶段一：仅 App 准备（同步/补丁/npm/slim），不执行 ohpm 与 hvigor
python build_hap.py --stop-after-slim

# 阶段二：App 已就绪，仅编 HAP
python build_hap.py --skip-resources-sync --skip-app-prepare

常用参数：

参数	说明
--build-mode release	Release 构建
--product default	指定 product（须与 build-profile.json5 一致）
--skip-resources-sync	跳过内嵌 app 仓库同步
--skip-app-prepare	跳过 app 依赖准备，仅构建 HAP
--stop-after-slim	完成 app 准备后退出（见分步构建）
--use-opendesk-root <路径>	从本地 OpenDesk 主仓注入 app
--devec-root <路径>	指定 DevEco 安装根目录
--persist-env	仅在需要时将环境变量持久化到用户环境

完整参数说明：python build_hap.py -h。

构建产物（默认 product 示例）：

ohos_hap/electron/build/default/outputs/default/

其中 .hap 文件名随模块与签名配置而变化。

定时构建与上传（可选）

面向 CI 或夜间出包，可使用 ohos_hap/daily_build_and_upload.py 按固定时间自动构建并上传归档：

上传后端	说明
ssh	通过 scp 上传到 SSH 服务器（默认）
r2	上传到 Cloudflare R2（S3 兼容）
both	同一次任务同时上传 SSH 与 R2，归档文件名一致

每天 02:30 构建并 SSH 上传：

cd ohos_hap
python daily_build_and_upload.py --time 02:30 --ssh-user <user> --remote-dir /data/hap

每天 02:30 构建并上传到 R2：

python daily_build_and_upload.py --time 02:30 --upload-backend r2 \
  --r2-account-id <ACCOUNT_ID> --r2-access-key-id <KEY_ID> \
  --r2-secret-access-key <SECRET> --r2-bucket <BUCKET> --r2-prefix daily/ohos

SSH + R2 双归档：

python daily_build_and_upload.py --time 02:30 --upload-backend both \
  --ssh-user <user> --remote-dir /data/hap \
  --r2-account-id <ACCOUNT_ID> --r2-access-key-id <KEY_ID> \
  --r2-secret-access-key <SECRET> --r2-bucket <BUCKET> --r2-prefix daily/ohos

仅上传、跳过构建（执行一次）：

python daily_build_and_upload.py --upload-only --once --ssh-user <user>

daily_build_and_upload.py 常用参数：

参数	说明
--time HH:MM	每日触发时间，默认 02:30
--upload-backend {ssh|r2|both}	上传后端，默认 ssh
--build-script	构建脚本路径，默认 ohos_hap/build_hap.py
--hap-file	待上传 HAP 文件路径
--upload-only	仅上传，跳过构建
--once	立即执行一次，不进入每日循环
--remote-name-prefix	归档文件名前缀，默认 ohos_opendesk
--ssh-host、--ssh-port、--ssh-user、--remote-dir	SSH 连接与目标目录
--ssh-key、--ssh-strict-host-key-checking、--ssh-known-hosts-file	SSH 认证与主机校验
--r2-account-id、--r2-access-key-id、--r2-secret-access-key、--r2-bucket、--r2-prefix	R2 凭据与对象前缀

也可通过环境变量配置（未传命令行参数时生效）：

变量	用途
HAP_SSH_HOST、HAP_SSH_PORT、HAP_SSH_USER、HAP_REMOTE_DIR	SSH 上传
HAP_SSH_KEY、HAP_SSH_STRICT_HOST_KEY_CHECKING、HAP_SSH_KNOWN_HOSTS_FILE	SSH 认证
HAP_UPLOAD_BACKEND、HAP_REMOTE_NAME_PREFIX	上传后端与归档前缀
R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET、R2_PREFIX	R2 上传

独立上传到 R2

ohos_hap/r2_upload_file.py 可将已构建的 HAP 单次上传到 Cloudflare R2：

cd ohos_hap
python r2_upload_file.py \
  --hap-file electron/build/default/outputs/default/electron-default-signed.hap \
  --r2-account-id <ACCOUNT_ID> --r2-access-key-id <KEY_ID> \
  --r2-secret-access-key <SECRET> --r2-bucket <BUCKET> --r2-prefix daily/ohos \
  --object-name ohos_opendesk_20260430101500.hap

参数	说明
--artifact-file	待上传构建产物路径（推荐）
--hap-file	兼容参数，等价于 --artifact-file
--r2-account-id、--r2-access-key-id、--r2-secret-access-key、--r2-bucket	R2 必要参数
--r2-prefix	对象前缀（可选）
--remote-name-prefix	未指定对象名时，用于生成 <前缀>_<时间戳>.hap
--object-name	直接指定桶内对象名

HarmonyOS 构建注意事项

• 克隆或 git pull 后若原生库异常，先执行 git lfs pull。
• build-profile.json5 含签名路径与加密字段，仅在本地受控环境维护，勿提交个人调试证书密码。
• 调试签名证书 / Profile 会过期或被重置；签名失败时请在 DevEco 中重新「自动签名」并更新 build-profile.json5。
• 仓库默认不携带 ohos_hap/web_engine/src/main/resources/resfile/resources/app 完整业务代码；须手动补全或通过 --use-opendesk-root 注入，否则同步 / 补丁步骤会失败。
• 生产式构建依赖内嵌 app 仓库可访问 origin/main；离线环境请使用 --skip-resources-sync，且须已本地准备好 app 内容。
• 阶段二构建（--skip-resources-sync --skip-app-prepare）要求 app 目录下已有有效的 dist/ 与裁剪后的 node_modules。
• 首次构建较慢，多为 npm / ohpm 依赖安装；可用 --stop-after-slim 将 app 准备与 HAP 编译拆到不同步骤或 CI job。