目录

一、安装仓颉工具链

macOS安装步骤

00-前置要求

01-安装依赖

02-下载仓颉工具链

步骤1：进入仓颉官网

步骤2：选择合适的安装包

03安装步骤

二、环境配置

临时环境配置

永久环境配置

三、卸载与更新

更新仓颉工具链

更新仓颉工具链

四、第一个仓颉程序

在VScode中创建仓颉项目

五、第一个仓颉应用

开发环境准备

IDE下载与安装

创建仓颉项目

步骤一：新建项目

步骤二：配置项目信息

项目签名配置

签名问题解决

签名步骤：

仓颉UI API位置

仓颉工程目录结构

项目结构概览

关键文件说明

应用级配置文件

模块级配置文件

构建工具配置

六、安装仓颉时遇到的问题

问题：配置环境变量错误

学习资源汇总

官方学习资源：

社区资源：

---

一、安装仓颉工具链

在开发仓颉程序时，必用的工具之一是仓颉编译器，它可以将仓颉源代码编译为可运行的二进制文件，但现代编程语言的配套工具并不止于此，实际上，仓颉为开发者提供了编译器、调试器、包管理器、静态检查工具、格式化工具和覆盖率统计工具等一整套仓颉开发工具链，同时提供了友好的安装和使用方式，基本能做到“开箱即用”。

目前仓颉工具链已适配部分版本的 Linux、macOS 和 Windows 平台，但是仅针对部分 Linux 发行版做了完整功能测试，详情可参阅附录Linux 版本工具链的支持与安装章节，在暂未进行过完整功能测试的平台上，仓颉工具链的功能完整性不受到保证。此外，当前 Windows 平台上的仓颉编译器基于 MinGW 实现，相较于 Linux 版本的仓颉编译器，功能会有部分欠缺。

macOS安装步骤

00-前置要求

• 系统版本：macOS 12.0 及以上版本
• 架构支持：aarch64 (Apple Silicon M1/M2)
• 包管理器：Homebrew（推荐）

01-安装依赖

使用 macOS 版本前需要安装相应的依赖软件包，可以通过执行以下命令安装：

brew install libffi

Last login: Wed Oct 15 18:38:27 on ttys003
lijiajun@Mac ~ % brew install libffi 
==> Fetching downloads for: libffi
==> Downloading https://ghcr.io/v2/homebrew/core/libffi/manifests/3.5.2
######################################################################### 100.0%
==> Fetching libffi
==> Downloading https://ghcr.io/v2/homebrew/core/libffi/blobs/sha256:e53361765ab
######################################################################### 100.0%
==> Pouring libffi--3.5.2.arm64_sequoia.bottle.tar.gz
==> Caveats
libffi is keg-only, which means it was not symlinked into /opt/homebrew,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

For compilers to find libffi you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/libffi/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/libffi/include"
==> Summary
🍺  /opt/homebrew/Cellar/libffi/3.5.2: 18 files, 812.2KB
==> Running `brew cleanup libffi`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
==> `brew cleanup` has not been run in the last 30 days, running now...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
Removing: /Users/lijiajun/Library/Caches/Homebrew/portable-ruby-3.4.5.arm64_big_sur.bottle.tar.gz... (11.6MB)
Removing: /Users/lijiajun/Library/Caches/Homebrew/bootsnap/6f30e8f1ffb9fa828f346a2fa6bfae5823a79041589f6940ac6a872a061c3c33... (630 files, 5.1MB)
Removing: /Users/lijiajun/Library/Logs/Homebrew/openssl@3... (64B)
Removing: /Users/lijiajun/Library/Logs/Homebrew/ca-certificates... (64B)
Removing: /Users/lijiajun/Library/Logs/Homebrew/ruby... (64B)
lijiajun@Mac ~ % 

02-下载仓颉工具链

仓颉官网

步骤1：进入仓颉官网

步骤2：选择合适的安装包

操作系统	文件名称	版本	架构
Windows	cangjie-sdk-windows-x64-1.0.3.zip	1.0.3	x86_64
Mac	cangjie-sdk-mac-aarch64-1.0.3.tar.gz	1.0.3	aarch64
Linux	cangjie-sdk-linux-aarch64-1.0.3.tar.gz	1.0.3	aarch64

03安装步骤

cd /Users/lijiajun

# 解压下载的安装包（以 macOS 为例）
tar xvf cangjie-sdk-mac-aarch64-1.0.3.tar.gz

解压完成，可以在当前工作路径下看到一个名为 cangjie 的目录，其中存放了仓颉工具链的全部内容，请执行如下命令完成仓颉工具链的安装配置：

# 配置仓颉工具链环境变量
source cangjie/envsetup.sh

cjc -v

lijiajun@Mac ~ % cjc -v
Cangjie Compiler: 1.0.3 (cjnative)
Target: aarch64-apple-darwin
lijiajun@Mac ~ % 

如果看到类似的版本信息输出，说明仓颉工具链已成功安装！

——————————————————————————————————————————

二、环境配置

临时环境配置

上述 envsetup.sh 脚本仅在当前 shell 环境中生效。如果需要在新的终端窗口中使用仓颉工具链，需要重新执行配置脚本。

永久环境配置

为了让仓颉工具链在每次启动终端时自动可用，可以将配置命令添加到 shell 初始化文件中：

对于 zsh（macOS 默认）：

# 编辑 ~/.zshrc 文件
echo 'source /path/to/cangjie/envsetup.sh' 					>> ~/.zshrc

对于 bash：

# 编辑 ~/.bashrc 文件
echo 'source /path/to/cangjie/envsetup.sh' 					>> ~/.bashrc

实际示例：

# 假设仓颉工具链解压在 cd /Users/lijiajun/cangjie 目录下

cd /Users/lijiajun/cangjie 

echo 'source /Users/lijiajun/cangjie/envsetup.sh' 		>> ~/.zshrc

配置完成后，重新启动终端或执行 source ~/.zshrc 即可生效。

——————————————————————————————————————————

三、卸载与更新

更新仓颉工具链

rm -rf /path/to/cangjie

# 编辑 ~/.zshrc 或 ~/.bashrc，删除相关的 source 命令行

vim ~/.zshrc

source ~/.zshrc

更新仓颉工具链

更新仓颉工具链需要先卸载当前版本，然后重新安装最新版本：

1. 按照上述步骤卸载当前版本
2. 从官网下载最新版本的安装包
3. 按照安装步骤重新安装

——————————————————————————————————————————

四、第一个仓颉程序

首先，请在适当目录下新建一个名为 hello.cj 的文本文件，并向文件中写入以下仓颉代码：

// hello.cj
main() {
    println("你好，仓颉")
}

在这段代码中，使用了仓颉的注释语法，可以在 // 符号之后写单行注释，也可以在一对 /* 和 */ 符号之间写多行注释，这与 C/C++ 等语言的注释语法相同。注释内容不影响程序的编译和运行。

然后，请在此目录下执行如下命令：

cjc hello.cj 

这里仓颉编译器会将 hello.cj 中的源代码编译为此平台上的可执行文件 hello，在命令行环境中运行此文件，将看到程序输出了如下内容：

你好，仓颉

注意：

以上编译命令是针对 Linux 和 macOS 平台的，如果使用 Windows 平台，只需要将编译命令改为 cjc hello.cj -o hello.exe 即可。

在VScode中创建仓颉项目

1.打开仓颉官网https://cangjie-lang.cn/download

2.选择打开

3.安装完成后正确显示

4.新建一个文件夹拖入VScode

5.MAC快捷键command+shift+P搜索cangjie

       1.创建仓颉项目Create Cangjie Project

        2.选择第一个（创建仓颉项目）

        3.选择第一个（选择可执行输出的仓颉项目）

        4.选择位置

        5.输入项目名称

        6.自动生成main文件

        7.运行，输出结果

——————————————————————————————————————————

五、第一个仓颉应用

开发环境准备

前提已经申请通过，官网才会显示可以下载cangjie dev

IDE下载与安装

在开始开发之前，需要先准备开发环境：

1. 下载DevEco Studio IDE

• 访问华为开发者官网下载最新版本的DevEco Studio
• 如果没有开发者账号，需要先申请注册

1. 安装仓颉插件

• 下载完成后，从本地安装IDE插件
• 确保插件版本与IDE版本兼容

1. 重启IDE

• 安装成功后需要重启IDE以确保插件生效
• 重启后可以在新建项目时看到仓颉相关模板

创建仓颉项目

步骤一：新建项目

1. 启动DevEco Studio

• 若首次打开DevEco Studio，请单击Create Project创建工程
• 如果已经打开了一个工程，请在菜单栏选择File > New > Create Project来创建一个新工

        2.选择项目模板

• 选择Application应用开发
• 选择模板[Cangjie] Empty Ability
• 单击Next进行下一步配置

步骤二：配置项目信息

1. 配置工程参数

• 进入配置工程界面，可以修改工程名称和存储路径等工程的基本信息
• 也可以保持默认设置
• 确保项目名称符合命名规范

1. 完成项目创建

• 单击Finish，工具会自动生成示例代码和相关资源
• 等待工程创建完成

项目签名配置

签名问题解决

创建项目后，如果直接运行会遇到签名错误：

错误原因：鸿蒙应用需要签名才能安装到设备上。

签名步骤：

1.点击项目结构

2.选择签名配置

3.跳转到华为帐号登录页

4.登录成功后点击允许

5.返回客户端

6.点击Apply进行同步

7.点击OK

8.再次运行项目，正常启动

点击Apply，项目会重新构建

点击OK

再次运行代码

仓颉UI API位置

分享一个小点，希望能帮助到大家，就是我在仓颉的官网里，未找到仓颉UI的API，但是在DEV中找到了，具体操作方法，将鼠标放到刚才的index.cj文件中的任意黄色高亮点击 Show in API Reference

仓颉工程目录结构

项目结构概览

仓颉工程目录结构如下所示：

cangjiedemo
├── 📁 AppScope
│   ├── 📁 resources
│   │   └── 📁 base
│   └── 📄 app.json5
├── 📁 entry
│   ├── 📁 src
│   │   └── 📁 main
│   ├── 📄 .gitignore
│   ├── 📄 build-profile.json5
│   ├── 📄 hvigorfile.ts
│   └── 📄 oh-package.json5
├── 📁 hvigor
│   ├── 📄 cangjie-build-support-3.1.132.tgz
│   └── 📄 hvigor-config.json5
├── 📄 .gitignore
├── 📄 build-profile.json5
├── 📄 code-linter.json5
├── 📄 hvigorfile.ts
├── 📄 oh-package-lock.json5
└── 📄 oh-package.json5

关键文件说明

应用级配置文件

• AppScope > app.json5：应用的全局配置信息，包括应用名称、版本号、权限等
• build-profile.json5：应用级配置信息，包括签名、产品配置等
• hvigorfile.ts：应用级编译构建任务脚本
• oh-package.json5：主要用来描述全局配置，如依赖覆盖、依赖关系重写和参数化配置等

模块级配置文件

• entry：仓颉工程模块，编译构建生成一个HAP包

• • src > main > cangjie：用于存放仓颉源码
  • src > main > cangjie > cjpm.toml：仓颉的包管理配置文件
  • src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等
  • src > main > module.json5：stage模块配置文件，主要包含HAP的配置信息、应用在具体设备上的配置信息以及应用的全局配置信息
  • build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等
  • hvigorfile.ts：模块级编译构建任务脚本
  • oh-package.json5：用来描述包名、版本、入口文件（类型声明文件）和依赖项等信息

构建工具配置

• hvigor：用于存放当前工程使用的hvigor

• • cangjie-build-support-x.y.z-cj.x.tgz：仓颉指定的hvigor任务包
  • hvigor-config.json5：指定工程全局使用的hvigor以及hvigor参数配置

• oh_modules：用于存放三方库依赖信息，包含应用/服务所依赖的第三方库文件

六、安装仓颉时遇到的问题

问题：配置环境变量错误

解决办法：配置环境变量错误，导致系统无法正确识别cjc命令，一定要正确的找到cangjie的下载路径，再进行操作，才可以正确的完成配置值环境变量。

注：如果不知道怎么找具体的路径，可以找到下载的文件夹，然后把文件夹拖动到终端，这样就不用担心输错安装路径了。

———————————————————————————————————————————

学习资源汇总

官方学习资源：

资源名称	链接	描述
仓颉官网	https://cangjie-lang.cn/	官方文档和下载
仓颉 GitCode	https://gitcode.com/cangjie	官方代码仓库
仓颉三方库	https://gitcode.com/cangjie-tpc	第三方库生态
仓颉 SIG	https://gitcode.com/cangjie-sig	特别兴趣小组

社区资源：

资源名称	链接	描述
优质开源项目	社区项目列表	社区优秀项目展示
坚果派社区	https://www.nutpi.net/	技术交流和学习

学习仓颉语言：https://gitcode.com/nutpi/gitbook_cangjie/tree/main/chapter1

参与仓颉共学创作营的价值：https://gitcode.com/nutpi/gitbook_cangjie/blob/main/chapter1/07.仓颉技术创作训练营.md

仓颉开发鸿蒙权限申请：https://developer.huawei.com/consumer/cn/activityDetail/cangjie-beta/

仓颉官方文档和学习资料：https://cangjie-lang.cn/docs

华为开发者学堂（仓颉编程语言入门教程&仓颉UI开发入门课程）：https://developer.huawei.com/consumer/cn/training/result?type2List=101718934342810217&courseType=5