前言

仓颉编程语言是华为推出的面向全场景智能应用开发的现代编程语言，主打原生智能化、强类型安全和高性能运行。随着HarmonyOS生态的不断发展，使用仓颉语言开发鸿蒙应用正逐渐成为开发者关注的热点。

本文将带你从零开始，完成仓颉开发HarmonyOS的环境搭建，并成功运行第一个Hello World程序。文中会重点说明两个极易踩坑的地方：插件安装方式和项目配置文件，并特别针对 DevEco Studio 6.1.1 Release 版本给出精确的解决方案。

本文基于 DevEco Studio 6.1.1 Release（内部版本号 #6.1.1.300） + Cangjie Plugin 6.1.1 Beta1 环境实测。

一、前置条件

在开始之前，请确保：

1. 申请仓颉公测权限：目前仓颉插件仍处于开发者预览阶段，需要先到华为开发者联盟申请仓颉Beta内测资格，审核通过后才能获取插件下载权限。
2. DevEco Studio版本：本文使用 6.1.1 Release（API 24）。如果你使用其他版本，请务必确保仓颉插件版本与IDE版本严格匹配（详见第二部分）。
3. HarmonyOS SDK：确保已安装 HarmonyOS SDK 6.1.1.125（API 24 Release）或更高。

二、安装仓颉插件（重点！）

⚠️ 千万不要手动下载离线包安装！

很多初学者会去官网下载仓颉插件的离线压缩包，然后通过 Install Plugin from Disk 方式安装。但这样做极易翻车——官方下载的插件版本往往和本地 DevEco Studio 版本不匹配，导致插件无法使用或编译报错。

以 DevEco Studio 6.1.1 Release 为例，它对应 API 24，必须配套安装 DevEco Studio-Cangjie Plugin 6.1.1 Beta1。如果使用了不匹配的版本安装会失败。

✅ 正确做法：通过IDE内置插件市场自动安装

Step 1：进入Settings页面

按照如下所示，打开File->Settings页面。

Step 2：进入Cangjie(Experiment) 页面

跳转至Languages & Frameworks->Cangjie(Experiment) 页面。

Step 3：下载插件

在下载安装仓颉插件前，需要完成登录。请通过如下页面引导，报名申请使用仓颉插件并通过审核。

单击Cangjie勾选框，按照页面引导开始下载仓颉插件。

Step 4：重启IDE

等待下载安装完成后，按照提示重启 DevEco Studio。

Step 5：验证安装

重启后，检查 File → Settings → Plugins 中已安装列表是否存在 `Cangjie 插件，并确认版本号与IDE版本匹配（例如 6.1.1.x）。

为什么推荐自动安装？

插件市场会自动提供与当前 IDE 大版本兼容的最新版本插件，系统会自动处理兼容性问题。手动下载离线包，版本对不上就会直接导致开发环境不可用——这是很多新手遇到的第一个坑。

三、创建仓颉工程

插件安装成功后，重启 DevEco Studio，新建项目时就会多出一个 [Cangjie] Empty Ability 的选项。

1. 点击 File → New → Create Project
2. 选择 [Cangjie] Empty Ability 模板
3. 填写项目名称、包名等信息（注意包名需符合规范）
4. 点击 Finish 完成创建

四、配置 build-profile.json5（又一个重点！）

⚠️ 不配置这个，编译运行会报错！

创建完项目后，千万不要急着运行。你需要先在项目级的 build-profile.json5 文件中添加 buildModeSet 配置。

为什么要配置？

仓颉工程默认编译架构为 arm64-v8a。如果你使用的是 x86_64 架构的模拟器（比如 Windows 上的模拟器），就必须显式指定支持 x86_64 架构，否则会报 code:9568347 错误。此外，如果不配置 cangjieOptions，也可能触发 C++ 接口不匹配等编译问题。

具体配置步骤

打开项目根目录下的 build-profile.json5 文件，在 app 节点下添加 buildModeSet 配置：

{
  "app": {
    // ... 其他已有配置
    "buildModeSet": [
      {
        "name": "debug",
        "buildOption": {
          "cangjieOptions": {
            "path": "./cjpm.toml",
            "abiFilters": ["arm64-v8a", "x86_64"]
          }
        }
      },
      {
        "name": "release"
      }
    ]
  }
}

配置说明

字段	说明
buildModeSet	构建模式集合，定义不同构建模式下的配置
name	构建模式名称，默认为 debug 和 release
buildOption.cangjieOptions.path	cjpm 配置文件路径，提供仓颉构建配置
buildOption.cangjieOptions.abiFilters	自定义仓颉编译架构，默认仅为 arm64-v8a，根据你的模拟器/真机架构添加

注意：这段配置要写在项目级（根目录）的 build-profile.json5 中，而不是模块级（entry 目录下）的配置文件。写错位置会导致配置不生效。

配置完成后，点击右上角的 Sync Now 同步项目。

五、编写 Hello World

5.1 找到仓颉代码目录

在 entry/src/main/ 目录下，你会看到一个 cangjie 文件夹，里面有几个.cj文件。

5.2 编写代码

在src/main/cangjie/index.cj中包括以下代码：

package ohos_app_cangjie_entry

import kit.ArkUI.LengthProp
import kit.ArkUI.Column
import kit.ArkUI.Row
import kit.ArkUI.Text
import kit.ArkUI.CustomView
import kit.ArkUI.CJEntry
import kit.ArkUI.loadNativeView
import kit.ArkUI.FontWeight
import kit.ArkUI.SubscriberManager
import kit.ArkUI.ObservedProperty
import kit.ArkUI.LocalStorage
import ohos.arkui.state_macro_manage.Entry
import ohos.arkui.state_macro_manage.Component
import ohos.arkui.state_macro_manage.State

@Entry
@Component
class EntryView {
    @State
    var message: String = "Hello World"

    func build() {
        Row {
            Column {
                Text(this.message)
                    .fontSize(50)
                    .fontWeight(FontWeight.Bold)
                    .onClick ({
                        evt => this.message = "Hello Cangjie"
                    })
            }.width(100.percent)
        }.height(100.percent)
    }
}

5.3 运行项目

1. 启动模拟器（确保模拟器架构与 abiFilters 中配置的一致，例如 x86_64 模拟器需要包含 x86_64）
2. 点击工具栏的 Run 按钮（或使用快捷键 Shift+F10）
3. 等待编译构建完成
4. 在模拟器上查看运行效果，或在 Log 面板查看控制台输出

六、常见问题排查

Q1：安装插件后找不到 [Cangjie] 模板？

检查 DevEco Studio 版本是否与插件兼容。目前已知 6.1.1 需要配套 6.1.1 Beta1 插件，其他版本类似。如果版本不匹配，模板不会出现。建议通过插件市场自动安装。

Q2：编译报错 `ccode:9568347

error: install parse native so failed.
In the module named entry, the Abi type supported by the device does not match the Abi type configured in the C++ project.？

仓颉工程默认编译架构为arm64-v8a，因此在使用x86模拟器时（即，当前开发环境为Windows/x86_64或macOS/x86_64时），仓颉工程及三方库需要编译出x86_64版本的so，请在配置文件build-profile.json5的cangjieOptions/abiFilters值中增加"x86_64"。

Q3：模拟器运行白屏或闪退？

• 检查模拟器的系统版本是否不低于项目的 compatibleSdkVersion（应设置为 "6.1.1(24)"）。
• 确认 abiFilters 中包含了模拟器对应的架构（x86_64 模拟器需要包含 "x86_64"）。
• 检查仓颉代码中是否有未捕获的异常，可在 Logcat 中查看详细错误日志。

Q4：编译成功但控制台无输出？

确保仓颉代码中使用了 console.info() 或 console.log()，并且日志级别未被过滤。在 Logcat 中筛选 Hello 关键词即可看到输出。

七、总结

本文带你完成了仓颉开发 HarmonyOS 的入门全流程，重点强调了两个最容易踩坑的地方：

1. 插件安装：务必通过 DevEco Studio 内置插件市场自动安装，不要手动下载离线包，避免版本不匹配。特别是 DevEco Studio 6.1.1 必须配套 6.1.1 Beta1 插件。
2. 项目配置：务必在项目级 build-profile.json5 中添加 buildModeSet，指定 cangjieOptions 的 path 和 abiFilters，避免架构不匹配或 C++ 接口错误。

避开这两个坑，你的仓颉 HarmonyOS 开发之旅就成功了一大半！

---

📌 参考文档：华为开发者联盟 - 仓颉开发指南

---

如果你在实践过程中遇到其他问题，欢迎在评论区留言讨论！