企业官网建设流程全解析

• 文档
• 编程语言

cangjie_docs 是仓颉（Cangjie）编程语言官方开发者文档的开源仓库，统一承载开发指南、工具使用指南及中心仓配套资料，是学习仓颉语法、编译构建、工具链使用与生态集成的一站式入口。本文将带你梳理该仓库的文档体系与目录结构、理解各分支与版本的对应关系，并掌握通过 Issue 反馈、在线修改与本地 PR 参与文档共建的完整流程。

仓库定位：仓颉官方开发者文档的开源载体

README.md（中文版见 README_zh.md）开篇即明确了本仓库的定位：仓颉编程语言是一种面向全场景应用开发的通用编程语言，能够兼顾开发效率和运行性能，并提供良好的编程体验。本仓库存放仓颉编程语言的开发者文档，欢迎开发者阅读文档、参与仓颉开发者文档开源项目，共同完善文档内容。

因此，cangjie_docs 并非语言编译器或运行时的源码仓库，而是以"开发者文档"为核心资产的知识型仓库，其姊妹仓库（cangjie_runtime、cangjie_stdx）分别承载标准库与扩展库的实现及 API 参考文档，四者共同构成仓颉语言完整的开发者知识体系。

文档体系：四大类开发者文档

按照 README.md 的"简介"章节，仓颉提供如下四类开发者文档：

其中，开发指南与工具使用指南是可直接在本仓库中阅读的核心内容，而标准库/扩展库 API 属于运行时与扩展库配套文档，README 明确指引开发者前往对应仓库获取，避免了文档内容在多个仓库间的重复维护。

仓库目录结构导航

README 中给出的目录示意为：

. └── docs ├── cmd-tools # 该目录存放仓颉编程语言命令行工具使用指南 └── dev-guide # 该目录存放仓颉编程语言开发指南

需要说明的是，该目录树属于简化示意，实际仓库中docs目录下还包含central-repo（仓颉中心仓相关文档）与tools（工具使用指南）等目录，且工具使用指南的实际存放路径为docs/tools（其下cmd-tools子目录对应 README 所称的cmd-tools）。以下按实际仓库结构给出导航：

开发指南（docs/dev-guide）

文档导航 展示了开发指南的完整章节体系，覆盖从入门到进阶的各个主题：

• 初识仓颉语言：初识仓颉语言、安装仓颉工具链、运行第一个仓颉程序；
• 语言基础：标识符、程序结构、表达式、函数，以及整数/浮点/布尔/字符/字符串/元组/数组/区间/Unit/Nothing 等基础数据类型；
• 进阶语言特性：struct 与枚举、类和接口、泛型、扩展、Collection 类型、包与模块管理、异常处理、并发编程；
• 系统能力：基础 I/O 操作、网络编程（Socket/HTTP/WebSocket）、宏、反射和注解；
• 互操作与编译构建：跨语言互操作（仓颉-C）、跨平台（Java/ObjC 互操作）、cjc使用、cjpm介绍、条件编译、交叉编译、部署和运行；
• 附录：cjc编译选项、cjo 产物说明、Linux 版本工具链安装、runtime 环境变量手册、关键字、操作符、TokenKind 类型、仓颉包兼容性检查等。

从初识仓颉语言一章可以看到仓颉语言的特性定位：多后端支持（CJNative 与 CJVM）、语法简明高效、多范式编程（函数式/命令式/面向对象）、静态强类型与类型推断、自动内存管理与运行时安全检查、用户态轻量化线程的并发模型、与 C 语言的互操作生态，以及基于词法宏的元编程与尾随lambda等利于内嵌式领域专用语言（EDSL）和声明式 UI 开发的特性。

工具使用指南（docs/tools）

工具使用指南 说明：仓颉语言为开发者提供了丰富的命令行工具以及语言服务器工具，涵盖项目管理、命令行调试、代码格式化等功能，在成功安装仓颉工具链后即可根据手册使用（工具链安装见安装仓颉工具链）。

文档导航 列出的工具手册包括：

• 项目管理工具 cjpm 手册：模块初始化、依赖检查与更新、增量/并行编译、单元测试、性能基准、制品打包与发布、项目安装卸载等；
• 调试工具 cjdb 手册、格式化工具 cjfmt 手册、静态检查工具 cjlint 手册、覆盖率统计工具 cjcov 手册、性能分析工具 cjprof 手册、兼容检查工具 cjcompat 手册；
• 语言扩展工具 HLE 及其转换规则（ArkTS 三方模块生成仓颉胶水代码的转换规则、C 语言转换到仓颉胶水代码的规则）；
• 语言服务器工具 LSP 手册、CHIR 反序列化工具、异常堆栈信息还原工具cjtrace_recover，以及库演进规范的兼容性规则文档。

以cjpm为例，项目管理工具手册 给出完整的子命令列表（init、check、update、tree、build、run、test、bench、clean、bundle、publish、install、uninstall），并详细讲解cjpm.toml配置文件中[package]、[workspace]、[dependencies]、[replace]、[ffi.c]、[profile]、[target.*]等各字段的含义与约束，例如模块名必须为合法标识符、cjc-version必须为无多余前缀 0 的三段数字版本号等，可直接作为实际工程的配置参考。

中心仓配套文档（docs/central-repo）

文档导航 显示该目录存放仓颉中心仓相关文档，包括：中心仓制品规格、中心仓官网、中心仓客户端配置与制品包使用/发布、网站协议（用户使用协议、平台安全策略、隐私政策），以及中心仓元数据规格与通信规格等附录。

文档版本与分支说明

README_zh.md 的"文档版本与分支说明"章节解释了 cangjie_docs 仓库各分支的作用。需要注意的是，分支会根据版本发布情况增加或删除，请以实际查询结果为准：

• 主分支main：默认主分支，合入稳定特性文档，是绝大多数用户应阅读的默认分支；
• 版本发布与配套分支：release/1.1为 Cangjie 1.1.0 STS 版本发布分支，release/1.0为 Cangjie 1.0.x LTS 版本发布分支，供使用对应大版本的用户获取与该版本匹配的文档快照；
• OpenHarmony 配套分支：release/OpenHarmony-release-6.0.2为配套 OpenHarmony 6.0.2 版本的仓颉文档。

这种"主分支持续演进 + 版本分支冻结快照"的组织方式，保证了稳定特性文档与已发布版本文档的隔离，避免版本迭代影响存量用户查阅历史文档。

此外，仓库根目录的release-notes目录存放各版本的发布说明文件（如 cangjie-1.1.0.alpha.33-release-notes.md 至 cangjie-1.1.0.alpha.61-release-notes.md），并提供了 cangjie-release-notes-template.md 模板。从模板与现有文件可见，发布说明遵循统一的章节结构：版本介绍、编译器、运行时、标准库、工具链（含 IDE 插件及 cjpm/cjdb/cjfmt/cjlint/cjcov/cjprof/cjtrace-recover/HLE 各工具的变更）、遗留问题与文档变更说明，方便开发者快速定位某个版本中与自己相关的特性变更。

许可证与知识产权

根据 README_zh.md 与 CONTRIBUTING_zh.md，仓颉开发者文档遵循以下许可与版权规则：

• 文档许可证为 Creative Commons License version 4.0，具体参见仓库根目录的 LICENSE（另有 COPYRIGHT 与 COPYRIGHT_zh 版权声明文件）；
• 用户提交的内容、图片必须是原创内容，不得侵犯他人知识产权；
• 仓颉有权根据相关规范修改开发者贡献的内容。

参与文档贡献

README_zh.md 欢迎开发者以各种方式参与文档反馈和贡献，具体操作流程详见贡献文档。贡献方式共有三种，可依据改动规模选择：

1. 反馈文档问题（Issue）

适用于报告文档中的错误、缺失或待改进之处：

1. 在 GitCode 对应仓库中，进入"Issues"页签，单击"新建 Issue"；
2. 在标题栏中描述问题，在编辑框中添加详细问题描述，单击"新建 Issue"完成提交；
3. 耐心等待仓颉文档团队确认问题。

CONTRIBUTING_zh.md 特别强调"高质量反馈"的要点：提供文档的具体位置、名称以及问题的清晰描述，必要时附上截图；解释该问题对用户的影响；若是文档示例错误，请提供具体执行的仓颉版本、环境及报错信息；将问题范围限定在具体内容或任务（例如"XX 开发指南缺少对 XXX 步骤的介绍"就比"文档需要优化"更具可操作性）；提交前先搜索现有问题列表，避免重复。

2. 在线更改（快速修改）

适合对现有文档进行少量内容修改和补充：

1. 在 GitCode 文档页面右上角单击"IDE"按钮，跳转到对应的工程源文件页面；
2. 在源文件页面对应内容处完成更改、修复；
3. 单击页面右上角 Markdown 预览按钮确认修改结果；
4. 确认无误后，在左侧提交面板填写修改意见、补充信息及 Signed-off-by 邮箱信息触发校验，选择合入的分支并提交，例如Signed-off-by: user.name <user.email>（需与 DCO 签署邮箱保持一致）。

3. 本地更改（批量修改 / 新增章节）

适合需要修改或补充较多内容的场景：

1. Fork 项目仓库；
2. Clone 项目到本地，并创建文档变更分支；
3. 本地完成文档更改后提交 PR；
4. 等待门禁验证和仓颉文档团队成员审核，通过后合入。

相关仓库

README.md 最后列出了仓颉生态中的三个相关仓库，分工如下：

• cangjie_docs：本仓库，存放开发者文档；
• cangjie_runtime：仓颉运行时仓库，提供标准库实现及其 API 参考文档（仓颉编程语言标准库 API）；
• cangjie_stdx：仓颉扩展库仓库，提供扩展库实现及其 API 参考文档（仓颉编程语言扩展库 API）。

对开发者而言，学习路径可以概括为：通过 cangjie_docs 中的开发指南掌握语言与编译构建，通过工具使用指南掌握工具链操作，在需要查阅具体 API 签名、参数与示例时，再前往cangjie_runtime与cangjie_stdx获取标准库与扩展库的 API 参考。

• 文档
• 编程语言