仓颉编程语言零基础入门终极指南：从环境搭建到提交首个PR的完整实战教程-CSDN博客

仓颉编程语言零基础入门终极指南：从环境搭建到提交首个PR的完整实战教程

【免费下载链接】CangjieCommunity 为仓颉编程语言开发者打造活跃、开放、高质量的社区环境项目地址: https://gitcode.com/Cangjie/CangjieCommunity

仓颉编程语言是面向全场景智能应用开发的新一代编程语言，官方开源社区 CangjieCommunity 汇聚了编译器、运行时、标准库与海量示例资源，是新手入门的第一站。这篇教程不堆砌概念，而是按"真实项目推进"的节奏带你走完全程：装好工具链、跑通第一个程序、用好包管理器，最后亲手向社区提交一份代码，把你的名字写进贡献者名单。

出发之前：先弄清仓颉能为你做什么

这门语言的底气在哪里

仓颉主打四个关键词：原生智能化、天生全场景、高性能、强安全。翻译成大白话就是——它既能写跑在电脑和服务器上的普通应用，也能写鸿蒙原生应用，还能覆盖云端一体化的智能场景，而且编译器、运行时和标准库全部开源，你随时可以钻进源码里看个究竟。

对新手最友好的点在于：你不需要一步到位读懂所有源码。社区仓库里已经整理好了清晰的入口：

你想了解的层面	对应开源仓库	上手难度
语言本身怎么写	cangjie_compiler（编译器源码）	中
程序怎么跑起来	cangjie_runtime（运行时与标准库）	低
日常开发工具	cangjie_tools（包管理、格式化、语言服务）	低
网络与安全能力	cangjie_stdx（通用扩展模块）	中

给自己做个定位自测

每个人的起点不同，别盲目从第一页啃起。先对号入座：

你的身份	建议从哪一章开始	预期收获
完全没接触过仓颉	第二节"装环境"	半小时内让工具链就绪
装过但没写过代码	第三节"第一个程序"	跑通并读懂项目结构
能写简单程序	第四、五节"加速包 + 提交PR"	用上三方库并完成首次贡献

动手装环境：三步让工具链就绪

第 1 步：确认电脑满足最低要求

在开始之前，先花一分钟做个体检，避免装到一半才发现环境不兼容：

操作系统：Windows 10/11、macOS 10.15+、主流 Linux 发行版均可
内存：8GB 起步，推荐 16GB（编译大型项目时更从容）
磁盘：预留 5GB 以上空间
网络：需要稳定的网络下载依赖与工具链

第 2 步：选择你的安装路线

仓颉提供"稳妥版"和"尝鲜版"两条路线，目的不同，选择也不同。

路线 A：通用版本（推荐新手）

这是绝大多数人的首选。社区按稳定性将版本分为三档：长期稳定版 LTS、每半年发布的稳定版 STS、每天更新的 Nightly 尝鲜版。下载安装包后一路跟随向导完成安装即可，仓库根目录的通用版本获取与安装配置.pdf 有完整的图文步骤，遇到问题随时翻阅。

路线 B：开发版本（适合想深度参与的人）

如果你不满足于只当用户，想看看社区到底在做什么，可以先把社区仓库拉到本地：

git clone https://gitcode.com/Cangjie/CangjieCommunity

仓库里除了代码，还沉淀了大量一手资料：贡献流程、团队分工、往期 Workshop 讲稿都在其中，后面几节我们会逐一用到。

第 3 步：验证安装并配置环境变量

安装完成后，打开终端执行下面两条命令，看到版本号输出就说明安装成功：

cj --version
cjpm --version

如果提示"找不到命令"，多半是 PATH 没配置好。手动把工具链路径加进去，然后重新打开一个终端窗口再试：

PATH 添加：/usr/local/cangjie/bin
库路径设置：/usr/local/cangjie/lib

💡 一个小建议：把仓颉工具链的路径放在 PATH 最前面，避免和其他语言工具链的命令重名冲突。

环境自检清单

cj --version 能输出版本号
cjpm --version 能输出版本号
新建终端后命令依然可用（环境变量已持久化）

写出第一个程序：五分钟让"你好，仓颉"跑起来

初始化项目骨架

找一个干净的目录，执行初始化命令生成项目：

cjpm init hello-cangjie
cd hello-cangjie

生成的骨架长这样，结构一目了然：

hello-cangjie/
├── src/           # 源码目录，你的代码都放这里
├── tests/         # 测试代码目录
├── cjpm.toml     # 项目配置文件（依赖、构建选项）
└── README.md      # 项目说明

写代码并运行

在 src 目录下新建一个源文件，敲入下面的内容：

package main

import std.io

func main() {
    io.println("你好，仓颉！")
    io.println("我的第一个仓颉程序跑起来了")
}

保存后依次执行：

cjpm build
cjpm run

看到终端打印出两行问候语，恭喜你，已经正式跨过"环境可用"到"程序可跑"的门槛了。

💡 别急着往下翻，先做个 30 秒的小实验：把引号里的文字改成你自己的名字，再跑一次 cjpm run，感受一下"改代码 → 看结果"的完整回路。

上手加速包：包管理器、示例代码与编辑器

跑通 Hello World 之后，很多人会卡在"接下来写什么"上。这一节给你三样加速工具。

用 cjpm 管理依赖

仓颉的包管理器叫 cjpm，用法和主流包管理器非常接近：

cjpm add 包名@版本号   # 添加依赖
cjpm build            # 构建项目
cjpm test             # 运行测试
cjpm clean            # 清理构建缓存
cjpm update           # 更新依赖版本

依赖声明会自动写进 cjpm.toml，整个项目的依赖关系一目了然。

从官方示例抄作业

与其从零憋代码，不如先"抄作业"。社区维护了一批小而美的示例程序，覆盖趣味算法、桌面工具、鸿蒙应用等场景，每一个都是"带着设计意图"写好的规范样例，非常适合作为仿写对象。看完示例再自己动手改造，成长速度会快得多。

配置编辑器与三方库

日常开发推荐 VSCode + 官方仓颉插件的组合，安装后即可获得语法高亮、代码补全、智能诊断等能力；官方专属 IDE 也正在开发内测中，值得期待。

写业务功能时，先别急着造轮子——社区优质项目清单（见仓库内社区优质开源项目.md）已经按分类整理好了现成轮子：

分类	你能找到什么
开发框架	Web 框架、ORM、依赖注入容器、跨平台 GUI 封装
算法与协议库	图算法、分词器、邮件、YAML/TOML 解析
通用能力	MySQL 驱动、缓存库、支付 SDK、命令行框架
辅助工具	C 头文件转仓颉、JSON 转类结构、大模型代码助手

进阶挑战：向 CangjieCommunity 提交你的第一个 PR

如果说前面的内容让你"学会用"，这一节会让你真正"参与进来"。向开源社区提交 PR 是新手快速提升代码品位的最佳路径——你会被真实评审逼着规范 commit、写清变更说明、打磨代码质量。

先看一遍完整流程

社区的贡献流程在 contribute/contribution.md 里有完整图文说明，核心是七个步骤：

Fork 目标仓库到自己的账号
把 Fork 仓克隆到本地
基于 dev 分支拉出开发分支
修改代码并规范提交
推送到自己的 Fork 仓
创建 PR 并关联 Issue
触发门禁、通过评审、等待合入

本地提交的规范姿势

代码改完后，提交信息要遵循约定式提交规范（Conventional Commits），并且每条 commit 都必须包含 Signed-Off-By 签名：

git add src/你的改动文件
git commit -sm "feat: 添加某个新功能"
git push -f origin 你的分支名

一个高质量的 commit 信息长这样：

feat: 增加日志清理能力

在 xxx 模块中增加按天清理历史日志的功能，
避免日志文件无限增长占用磁盘。

Refs: #12

创建 PR 并关联 Issue

推送成功后，从你的分支向目标仓库的 dev 分支发起 PR。创建成功后，系统会自动回复一份引导说明，其中有两点是硬性要求：

PR 必须关联 Issue：按模板在描述里填入 Issue 的完整链接，否则门禁不会触发
多仓改动要联动：如果一次改动涉及多个仓库（比如同时改编译器和运行时），每个仓库都要建 PR，且全部关联同一个 Issue

回复指令触发门禁

门禁不是自动跑的，需要你在 PR 评论区主动回复指令：

指令	作用	适用场景
`start build`	主要基础检查：commit 格式、静态告警、多平台构建、测试	日常提交（推荐）
`start full build`	更全面的检查，耗时更长	内测中的深度验证

多平台构建会覆盖 Linux、Windows、macOS 三个平台，构建任务和测试任务的状态都可以在"检查"页签里实时看到：

如果是多仓联动的 PR，只需在任意一个 PR 里回复一次指令，门禁通过后所有关联 PR 会同步状态，无需重复触发：

通过评审并等待合入

全部门禁检查通过后，系统会在评论里给出明确结论。这时只差最后一步：满足合入条件后，由协作者回复 start merge 完成合并（注意：不能合并自己创建的 PR）。

合入条件自检清单

门禁检查结果为成功（build-test-passed）
满足最低评审人数（至少 2 位开发者评审 + 1 位 committer 审查）
所有评审意见已解决
每条 commit 均含 Signed-Off-By 信息

⚠️ 请珍惜门禁资源：不要拿线上门禁当本地编译器用，提交前先自行构建验证，建议单次 PR 的门禁触发不超过 3 次。详细的代码合入标准与 committer 名单见 contribute/codemerge.md，门禁机器人支持的指令速查表在 infrastructure/build_command.md。

新手高频踩坑区：五个坑提前绕开

坑 1：commit 缺少签名，门禁直接红灯

很多人第一次提交就挂在"Signed-Off-By"上。记住用 git commit -sm 提交，并保持每条 commit 信息遵循约定式提交规范。

坑 2：PR 没关联 Issue，门禁无法触发

这是最常见的"卡住"原因。创建 PR 时务必按模板填入 Issue 完整链接，并保证一个 Issue 不重复创建。

坑 3：更新代码后门禁不会自动重跑

创建 PR、更新代码、重新打开 PR 都不会自动触发门禁，需要在评论区重新回复指令才会重新构建。

坑 4：想把 Markdown 改动混进代码 PR

Markdown 类修改只触发文档构建测试，不会触发编译测试。文档改动和代码改动分开提交，双方都省事。

坑 5：环境变量失效

装完才发现命令找不到？先手动补 PATH，再重启终端验证，最后确认没有和其他语言的工具链重名。

排查通用套路：构建失败时，按 cjpm clean → cjpm update → 检查网络 → 重新 cjpm build 的顺序依次排除，能解决九成问题。

下一步路线图：从"会用"走向"会贡献、会创造"

提交过第一个 PR，你的仓颉之旅才刚刚开始。社区为不同兴趣的开发者准备了多条成长路径：

你的兴趣方向	可以做什么	资料在哪
听大咖分享	参加每月一次的线上 Workshop，主题涵盖语言设计、编译器实现、应用实战	Workshop/workshop.md
研究语言底层	观看类型推断、并发机制、GC 等技术分享实录	技术分享.md
参与源码共建	按兴趣加入编译器、运行时、标准库、IDE 等方向的小组	team/
做点有趣的项目	报名三方库招募、投稿示例程序、认领开源毕设课题	见 README.md 社区活动章节

给自己定一个 30 天小目标

本周：跑通环境与第一个程序，读完一篇 Workshop 讲稿
第 2 周：用 cjpm 引入一个三方库，做出自己的小工具
第 3 周：在社区仓库找一个 good-first-issue 认领
第 4 周：提交你的第一个 PR 并完成合入

从"下载安装"到"代码合入"，你走过的每一步，社区都为你准备了清晰的文档和热心的伙伴。工具是练出来的，代码是改出来的，现在就从打开终端、敲下第一行命令开始吧。

【免费下载链接】CangjieCommunity 为仓颉编程语言开发者打造活跃、开放、高质量的社区环境项目地址: https://gitcode.com/Cangjie/CangjieCommunity

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考