从零搭建 CJMP 开发环境并运行到鸿蒙设备——完整实战指南

坚果派

221人浏览 · 2026-09-04 14:45:53

坚果派 · 2026-09-04 14:45:53 发布

从零搭建 CJMP 开发环境并运行到鸿蒙设备——完整实战指南

本文记录了在 macOS 上从零开始搭建 CJMP（仓颉跨平台）开发环境，并将一个 Keels 示例应用成功运行到 HarmonyOS 设备上的完整过程，包括遇到的所有坑和解决方案。

一、背景介绍

CJMP（仓颉跨平台框架）是基于华为仓颉编程语言的跨平台开发框架，支持一套代码编译运行到 Android、iOS 和 HarmonyOS 三端。Keels 是 CJMP 的 UI 引擎项目管理工具，类似于 Flutter 的 flutter create，可以快速初始化跨平台项目。

本文环境：

macOS（Apple Silicon）
DevEco Studio 6.1（26.0.0）
OpenHarmony SDK 26.0.0
CJMP SDK v0.2.2
CJMP DevEco Studio 插件 26.0.0.821

二、环境准备

2.1 安装 DevEco Studio

DevEco Studio 是华为官方的鸿蒙应用开发 IDE，内置了 hvigor 构建工具、ohpm 包管理器和 OpenHarmony SDK。

从 DevEco Studio 官网下载 macOS ARM 版本，安装后打开会自动引导安装 OpenHarmony SDK。

验证安装：

# 检查 OpenHarmony SDK
ls ~/Library/OpenHarmony/Sdk/26.0.0/toolchains/
# 应该能看到 hdc, restool 等工具

2.2 安装 Python 3.8+

CJMP 命令行工具基于 Python 开发，确保已安装 Python 3.8 或更高版本：

python3 --version
# Python 3.14.4（示例）

2.3 下载并配置 CJMP SDK

CJMP SDK 托管在 AtomGit 的 CJMP/OpenSDK 仓库，macOS 版本为 open-sdk-mac-v0.2.2 分支。

# 克隆 SDK（约 1.5GB，需要 Git LFS）
git clone --depth 1 -b open-sdk-mac-v0.2.2 https://atomgit.com/CJMP/OpenSDK.git ~/cjmp-sdk

配置环境变量，在 ~/.zshrc 中添加：

# CJMP 配置
export CJMP_SDK_HOME=$HOME/cjmp-sdk
export PATH=$CJMP_SDK_HOME/cjmp-tools/bin:$PATH

执行 source ~/.zshrc 使配置生效，验证：

keels --version
# Keel project management tool. Version: 0.2.2.

2.4 下载 CJMP DevEco Studio 插件

从 CJMP 文档下载对应平台的插件压缩包。

在 DevEco Studio 中安装：Settings → Plugins → ⚙️ → Install Plugin from Disk → 选择下载的 zip 文件。

关键一步：这个插件包含 hvigor 构建所需的 cangjie-build-support 包和 ohos 平台的仓颉编译工具链（cjpm、cjc 等），后续构建 HAP 时会用到。

三、创建 Keels 项目

3.1 初始化项目

keels create ~/Desktop/cjpm/demo --name demo

生成的项目结构：

demo/
├── project.conf          # 项目配置（name=demo, type=app）
├── lib/                  # 仓颉跨平台逻辑代码
│   ├── main_ability.cj
│   ├── ability_mainability_entry.cj
│   └── cjpm.toml
├── android/              # Android 壳工程
├── ios/                  # iOS 壳工程
├── hos/                  # HarmonyOS 壳工程
├── build.sh              # 构建脚本
└── build.bat             # Windows 构建脚本

lib/ 目录下的 .cj 文件是仓颉语言源码，三端共享同一套业务逻辑。

四、构建 HAP 包

4.1 直接构建（会遇到的问题）

直接执行构建：

cd ~/Desktop/cjpm/demo
keels build hap

会遇到两个关键问题：

问题一：hvigor 不认识 cangjieOptions

hvigor ERROR: 00303038 Configuration Error
Schema validate failed, at file: hos/entry/build-profile.json5
property name must be valid: cangjieOptions

这是因为 hvigor 的 schema 校验不包含 CJMP 特有的 cangjieOptions 字段。hvigor 需要动态加载 @ohos/cangjie-build-support 来扩展 schema，但这个包在命令行构建时找不到。

问题二：找不到 ohos 平台的 cjpm

hvigor ERROR: 01101000 Tools execution failed.
Not Found: /Users/xxx/cjmp-sdk/cjmp-tools/build-tools/tools/bin/cjpm

CJMP SDK 的 macOS 版本只包含 cangjie-android 和 cangjie-ios 工具链，不包含 cangjie-ohos。ohos 的编译工具链在 DevEco Studio CJMP 插件的 harmonyos-cangjie-sdk-mac-arm.zip 中。

4.2 解决方案

第一步：从 CJMP 插件中提取 ohos 构建工具

# 解压插件中的 harmonyos-cangjie-sdk
unzip -o ~/Downloads/devecostudio-cangjie-plugin-mac-arm-26.0.0.821.zip \
  "devecostudio-cangjie-plugin-mac-arm-26.0.0.821/harmonyos-cangjie-sdk-mac-arm.zip" \
  -d /tmp/cjmp-hos-sdk

# 提取 build-tools 和 api 目录
unzip -o /tmp/cjmp-hos-sdk/devecostudio-cangjie-plugin-mac-arm-26.0.0.821/harmonyos-cangjie-sdk-mac-arm.zip \
  "cangjie/build-tools/*" "cangjie/api/*" \
  -d /tmp/cjmp-hos-extract

# 部署到 CJMP SDK 目录
cp -r /tmp/cjmp-hos-extract/cangjie/build-tools ~/cjmp-sdk/cjmp-tools/build-tools
cp -r /tmp/cjmp-hos-extract/cangjie/api ~/cjmp-sdk/cjmp-tools/api

第二步：移除 macOS 隔离属性

xattr -dr com.apple.quarantine ~/cjmp-sdk/cjmp-tools/build-tools/

macOS Gatekeeper 会阻止未签名的动态库加载，必须移除隔离属性。

第三步：设置环境变量启用 CJMP 构建支持

export DEVECO_CANGJIE_PATH=$HOME/cjmp-sdk/cjmp-tools
export DEVECO_CANGJIE_PLUGIN_ENABLED=true

hvigor 的 cangjie-build-support 通过这两个环境变量判断是否启用 CJMP 构建支持。DEVECO_CANGJIE_PATH 指向包含 oh-uni-package.json 的目录。

第四步：重新构建

cd ~/Desktop/cjpm/demo
rm -rf hos/.hvigor  # 清理缓存
keels build hap -v

看到 BUILD SUCCESSFUL 就说明 HAP 构建成功了。

五、部署到鸿蒙设备

5.1 连接设备

确保鸿蒙设备（手机或模拟器）已通过网络或 USB 连接，使用 hdc 检查：

export PATH=$HOME/Library/OpenHarmony/Sdk/26.0.0/toolchains:$PATH
hdc list targets
# 192.168.10.2:42923（示例）

5.2 安装并启动应用

# 安装 HAP
hdc install ~/Desktop/cjpm/demo/hos/entry/build/default/outputs/default/entry-default-signed.hap

# 启动应用
hdc shell aa start -a EntryAbility -b com.example.demo

注意：keels run 命令目前不支持鸿蒙平台（它走的是 Android adb 路径），需要手动用 hdc 安装和启动。

0dc740e2e4440140755bc75c41dc7f2a

六、完整构建脚本

为了避免每次手动设置环境变量，可以将以下内容保存为 build-ohos.sh：

#!/bin/bash
set -e

export CJMP_SDK_HOME=$HOME/cjmp-sdk
export PATH=$CJMP_SDK_HOME/cjmp-tools/bin:$CJMP_SDK_HOME/cjmp-tools/build-tools/tools/bin:$HOME/Library/OpenHarmony/Sdk/26.0.0/toolchains:$PATH
export DEVECO_CANGJIE_PATH=$HOME/cjmp-sdk/cjmp-tools
export DEVECO_CANGJIE_PLUGIN_ENABLED=true

cd "$(dirname "$0")"

echo ">>> 构建 HAP..."
keels build hap -v

echo ">>> 安装到设备..."
HAP_PATH=$(find hos/entry/build -name "entry-default-signed.hap" | head -1)
if [ -z "$HAP_PATH" ]; then
    echo "错误: 未找到 HAP 文件"
    exit 1
fi
hdc install "$HAP_PATH"

echo ">>> 启动应用..."
hdc shell aa start -a EntryAbility -b com.example.demo

echo ">>> 完成！应用已在设备上运行。"

七、踩坑记录

问题	原因	解决方案
hvigor 不认识 `cangjieOptions`	命令行构建时 `@ohos/cangjie-build-support` 无法动态加载	设置 `DEVECO_CANGJIE_PATH` 环境变量
找不到 `cjpm` 二进制文件	macOS SDK 不含 ohos 工具链	从插件的 `harmonyos-cangjie-sdk` 中提取
`libcangjie-runtime.dylib` 加载失败	macOS Gatekeeper 隔离	`xattr -dr com.apple.quarantine`
`keels run` 报 Unsupported platform UNKNOWN	keels run 仅支持 Android adb	改用 `hdc install` + `hdc shell aa start`
ohpm install 删除手动放置的包	ohpm install 会清理 oh_modules	通过环境变量启用，不要手动放包