企业官网建设流程全解析

• 开发工具
• 代码编辑器
• 调试器

本文以 vscode_cangjie 仓库中的《编译构建》文档（docs/source_zh_cn/compilation_and_building.md）为主体骨架，深入讲解如何在 VSCode 中借助仓颉插件完成仓颉工程的编译、构建、测试、安装与三方库导入。读者将掌握命令面板、终端、运行按钮、锤子按钮四种编译入口的使用方式，理解cjpm.toml与cjpm_build_args.json两个核心配置文件的含义，并能在 UI 界面中可视化地维护编译参数与外部依赖。

一、编译构建能力概览与前置条件

VSCode 中可视化方式提供的仓颉编译构建能力全部依赖cjpm 工具。cjpm 要求所打开的仓颉工程模块内必须包含规范的cjpm.toml文件；如果工程中没有该文件，仍想执行编译构建，则只能退回到终端使用cjc命令完成。

围绕 cjpm，插件在 VSCode 中提供了四种编译构建方式：

1. 在命令面板执行编译相关命令（F1 或 Ctrl + Shift + P 打开，macOS 为 Command + Shift + P，输入分类词Cangjie即可过滤出全部编译命令）；
2. 在终端面板直接执行 cjpm 命令；
3. 单击.cj文件编辑区的运行按钮运行整个工程；
4. 单击.cj文件编辑区的锤子按钮编译整个工程。

从源码实现看，这四类入口最终都汇聚到同一个命令注册中心：插件的工具模块在 launch-tools.ts 中实例化CjpmBuildCollection与CjpmInstallCollection，由这两个类统一注册cangjie.build.*、cangjie.test.*、cangjie.install.*等命令，并映射到对应的 cjpm 命令行参数。命令的完整清单可以在根目录 package.json 的contributes.commands中查阅，每个命令都声明了标题、分类与图标。

二、方式一：在命令面板执行编译构建命令

按下 F1（或 Ctrl + Shift + P，macOS 为 Command + Shift + P）打开命令面板，输入分类词Cangjie，即可看到全部编译相关命令。命令的实际底层参数定义在 cjpm-build-collection.ts 的BuildArgsCollection枚举中。

2.1 基础编译命令（cjpm build 系列）

Parallelled Build：理解编译产物目录

执行并行编译后，工程文件夹下会生成target目录，其下有一个release文件夹，release文件夹内包含三个目录：

• .build-logs目录：存放编译日志；
• bin目录：存放可执行文件（只有cjpm.toml的output-type为executable时才会生成）；
• 与工程名同名的目录：存放编译的中间产物。

编译是否成功的信息会打印在 Output 面板上。

Build With Alias：指定输出名

按下回车后会弹出一个输入栏，需要为编译结果赋予一个新名字。该命令只对cjpm.toml的output-type为executable时有效。对应源码中通过输入框收集别名后拼接为cjpm build -o <alias>执行（见 cjpm-build-collection.ts）。

Build With CustomizedOption：条件透传

使用该选项需要先在cjpm.toml中配置customized-option字段。随后在命令面板执行该命令，回车后可以选择需要的参数（参数可以多选），选择完毕再次回车即可。若未在cjpm.toml中配置customized-option字段就执行该命令，插件会提示开发者先配置该字段。

实现层面，插件调用Utility.getCustomizedOptions()读取profile.customized-option中的条件名，去重后拼成cjpm build --cfg1 --cfg2 ...形式执行（见 utils.ts 与 cjpm-build-collection.ts）。

Build With TargetDir：指定产物输出路径

执行后可以指定编译产物的输出路径；若默认不做输入操作，则采用cjpm.toml中target-dir字段的值作为路径。当输入的路径与cjpm.toml中的target-dir字段不一致时，会弹出提示询问是否覆盖cjpm.toml中的target-dir字段；选择 Yes 则把该字段覆盖为输入值。命令成功后会在指定路径下生成编译产物（对应源码见 cjpm-build-collection.ts）。

Build With Jobs：自定义最大并发度

支持在编译前自定义最大并发度，输入参数为任意数字，取值范围为(0, CPU 核数 * 2]。当输入非数字时，操作终止并提示“Invaild input! The input should be number.”；当输入超出范围时，默认采用 CPU 核数并弹出超出可选范围的告警。对应源码在 cjpm-build-collection.ts 的registerBuildOrTestJobs中，先通过os.cpus().length获取 CPU 核数，再对输入进行isNaN与范围双重校验。

Build With CodeCheck：静态代码检查

执行编译时会对当前工程进行 CodeCheck 静态代码检查：检查到【要求】级别的代码规范违规则编译失败；检查到【建议】级别的违规仅告警，编译正常完成。底层命令为cjpm build --lint，并且终端执行该命令后会联动触发 cjlint 检查（见 ternimal-helper.ts）。

Build With MultiParameter：多参数叠加编译

仓颉工程的编译可以叠加多个参数。搜索到Build With MultiParameter命令后，会弹出多选界面（见下图），其中：

• --target参数根据cjpm.toml的target字段决定是否显示，未配置则隐藏；
• --<customized-option>参数根据cjpm.toml的customized-option字段决定是否显示，未配置则隐藏。

勾选想叠加的参数后按回车或单击 OK 按钮，也可单击界面中的向左箭头重新选择编译参数。叠加参数时：

• 若选择了cjpm build --output=<name>（即-o），需要输入一个别名字符串后回车执行；
• 若选择了cjpm build --target=<name>，可以进一步选择一个想要交叉编译的平台；
• 若选择了cjpm build --<customized-option>，可以选择透传参数。

叠加命令的编译结果就是这些命令分别执行的总和。该交互由multiParamsBuild()实现，选项按顺序经过「选择参数 → 输入别名 / 输入并发度 → 选择交叉编译平台 → 选择条件选项」的向导式多步流程（见 multi-step-select.ts）。

Update Cjpm.toml 与配置管理命令

在修改完cjpm.toml文件后，需要执行Cangjie: Update Cjpm.toml（cjpm update）来更新cjpm.lock文件；如果是通过 UI 界面修改的cjpm.toml，则无需手动执行。此外还有Cangjie: Clean Build Result（清除 build 目录）与Cangjie: Check Circular Dependencies（检测文件依赖）两个辅助命令。

2.2 单元测试命令（cjpm test 系列）

Test With MultiParameter 详细流程：选择该命令后，首先可以指定包路径、模块或成员执行单元测试——注意只有打开了工作空间，才显示成员选择选项（对应cjpm.toml中存在workspace字段时才会出现Specify a test member，见 multi-step-select.ts）。

• 选择Specify the test paths后，可输入指定待测试的包路径，不需要指定则直接按 Enter 键；输入多个包路径并用空格分隔，可实现多包并发单元测试；
• 选择Specify the test modules后，可输入指定待测试的模块，多个模块同样以空格分隔，实现多模块单元测试；
• 选择Specify a test member后，可输入指定待测试的成员。

随后进入参数叠加界面：若选择了--filter=<value>参数，则需要输入对应的过滤测试子集的表达式（正则），最终生成完整的cjpm test命令，执行结果在 Output 面板输出。若在cjpm.toml中配置了target和customized-option，可选参数会额外包含--target=<name>（选择后需挑选平台）与--<customized-option>（选择后需挑选条件选项）。整体流程由multiParamsTest()与specifyOneTest()等函数串联（见 multi-step-select.ts）。

2.3 安装与卸载命令（cjpm install / cjpm uninstall 系列）

安装命令的底层参数定义在 cjpm-install-collection.ts 的InstallArgsCollection枚举中：

要点说明：

• Install With RootPath / Uninstall With Root：不配置自定义路径时，Linux 与 macOS 下默认为$HOME/.cjpm，Windows 下默认为%USERPROFILE%/.cjpm，与输入框的 placeholder 提示一致（见 cjpm-install-collection.ts）；
• Install With Alias：实现上会先执行cjpm build -o <name>再执行cjpm install --name <name>，保证先编译出指定名称的产物再安装（见 cjpm-install-collection.ts）；
• Install With Git：输入远端 git url 后回车，可进一步选择代码仓的branch / tag / commit信息，也可以选择自定义输入 branch / tag / commit 号（见 cjpm-install-collection.ts）；
• Install With CustomParameter：需要先在 VSCode 设置中配置Cangjie: Cjpm Install: Custom（对应配置项Cangjie.CjpmInstall.Custom，声明于 package.json）。配置入口：单击 VSCode 页面左下角齿轮图标选择设置，或右键单击插件选择 Extension Settings，在搜索栏输入Cangjie并选择侧边栏的 Cangjie Language Support，在该页面的输入框Cangjie: Cjpm Install: Custom中填入cjpm install相关的命令选项（如-V -g --name \<value\>），之后执行Install With CustomParameter命令即可把输入框内容带入cjpm install（实现见 cjpm-install-collection.ts）；
• Install With CustomizedOption：同样要求先在cjpm.toml中配置customized-option字段，参数可多选。

三、方式二：在终端执行 cjpm 命令

开发者可以直接在 VSCode 的终端面板使用 cjpm 编译构建命令对仓颉工程进行编译构建。初次使用需要重新启动 VSCode，插件会在启动时通过Utility.configTerminalcjpmEnv()自动配置终端环境变量（如 Linux/macOS 的CANGJIE_PATH、LD_LIBRARY_PATH与 Windows 的 PATH 等，见 utils.ts），随后即可在终端中直接执行cjpm操作。

命令面板中的各类编译命令最终也是通过TerminalHelper.execCommand()在名为cangjie的终端中发送命令执行的——该终端会先sourceSDK 的envsetup.sh/envsetup.bat完成环境初始化（见 ternimal-helper.ts）。

四、方式三：单击运行按钮运行工程

开发者可以单击.cj文件编辑区的运行按钮（即编辑器标题栏上的运行图标）来运行整个仓颉工程。

• 若整个工程中配置的output-type为executable，则会在终端面板打印运行结果；
• 否则只会显示编译的结果。

从源码看，运行按钮对应cangjie.run命令：先自动保存当前文件，然后读取package.output-type——为executable时执行cjpm run，否则执行cjpm build（见 cjpm-build-collection.ts）。注意，运行按钮执行的编译过程是结合当前的cjpm.toml和cjpm_build_args.json的配置进行的：getCjpmRunCmd()会把cjpm_build_args.json中的 alias 转为--name=、debug 转为-g，其余构建参数以--build-args="..."形式透传给cjpm run（见 cjpm-build-collection.ts）。

五、方式四：单击锤子按钮编译工程

开发者可以单击.cj文件编辑区的锤子按钮来编译整个仓颉工程（对应cangjie.build命令）。锤子按钮执行的编译过程与运行按钮一致，同样是结合当前的cjpm.toml和cjpm_build_args.json的配置进行的。两者的区别在于：若output-type为executable，运行按钮在编译完成后再运行整个工程，而锤子按钮只编译工程，无后续运行动作（见 cjpm-build-collection.ts）。

六、可视化配置编译构建参数（Edit Configuration (UI)）

编译构建过程中需要配置工程目录下的两个文件：cjpm.toml与.vscode/cjpm_build_args.json。有三种修改方式：

1. 直接修改cjpm.toml和cjpm_build_args.json文件；
2. 按 F1 或 Ctrl + Shift + P（macOS 为 Command + Shift + P）打开命令面板，执行Cangjie: Edit Configuration (UI)打开可视化编辑的 UI 界面；
3. 单击.cj文件编辑区右上角的画笔按钮跳转到可视化编辑的 UI 界面。

6.1 cjpm_build_args.json：编译参数的复选框配置

.vscode/cjpm_build_args.json存放的是构建参数（位于工程.vscode目录下），UI 界面通过复选框或输入框的形式确定编译要使用的参数，修改后会同步写回cjpm_build_args.json。该文件在插件激活时由Utility.gencjpmBuildArgsJSON()自动生成，默认字段及默认值定义于 constant-num.ts：

{ "debug": false, "verbose": false, "coverage": false, "increment": false, "codeCheck": false, "alias": "", "cross": "", "condition": "", "job": "", "features": "" }

字段与 cjpm 参数的映射关系（cjpmBuildReplace，见 constant-num.ts）为：debug → -g、verbose → -V、coverage → --coverage、codeCheck → --lint、alias → -o、cross → --target、increment → -i、condition → --、job → -j、features → --enable-features。UI 前端页面 setting.html 中逐个渲染了这些复选框与输入框。

6.2 cjpm.toml：模块配置的可视化编辑

对于工程中cjpm.toml文件的配置，开发者在 UI 输入框中输入内容并将光标移至输入框外，即可生效到cjpm.toml文件中。

注意：当仓颉工程中的cjpm.toml文件和参数配置界面同时在 VSCode 的编辑区显示时，对cjpm.toml文件的修改不会同步到 UI 界面上。

构建参数：cross-compile-configuration

在cross-compile-configuration下单击Add Configuration按钮添加选项；在 key 和 compile-option 处填写对应内容，单击对勾按钮或按回车键即可与cjpm.toml保持同步。删除某条配置则单击该条选项的叉号按钮。

若添加配置时不填写第一个字段 key 就直接提交，会出现"必须填写第一个字段"的提示，且该场景下提交的内容不会同步到cjpm.toml；UI 界面目前不会直接删除该条配置，刷新 UI 后会自动删除，内容与cjpm.toml保持一致。

package-configuration：包级配置

package-configuration的添加和修改方式与cross-compile-configuration一致。其中output-type字段为下拉框选项，可选类型有executable、static、dynamic和null四种；新添加配置的output-type初始化类型为null（见 config-set-by-ui.ts），开发者可按需选择。当选择为null时，该字段同步到cjpm.toml后会删除该字段（见 setting-provider.ts）。

customized-option：条件编译选项

customized-option的添加修改方式与cross-compile-configuration一致，配置内容写入profile.customized-option（见 setting-provider.ts）。

注意：customized-option的条件不能设置内置条件，例如@When[os == "Linux"]不能作为customized-option的条件，即"cfg1" : "--cfg =\"os=Linux\""是不允许的，只能添加开发者自定义条件。这一点与源码中的builtinConditions = new Set(['os', 'backend', 'debug', 'cjc-version'])定义相互印证（见 constant-num.ts）。

转义规则（重要）

• 在 UI 界面配置cjpm.toml时，只有customized-option参数中配置的--cfg路径里的=需要转义，其他符号不需要添加转义符。例如：
  • --cfg路径中包含=时：--cfg="D:/projects/cang\=jie"；
  • package-configuration的 p1 配置compile-option中，--link-options不需要转义，只加引号即可：--link-options="-rpath=xxx"。
• 直接在cjpm.toml中填写时，符号都需要加转义符号。例如：
  • customized-option的--cfg路径中所有符号都需要转义：--cfg=\"D:/projects/cang\\=jie\"；
  • package-configuration的 p1 配置compile-option时：--link-options=\"-rpath=xxx\"。

七、三方库便捷导入

7.1 导入方式

在仓颉工程中可以导入外部三方库，并在cjpm.toml中配置。插件资源管理器视图栏中的CANGJIE LIBRARY栏提供了便捷的图形化导入入口。

注意：三方库便捷导入仅适用于当前打开的仓颉工程的主模块；如果其他子模块需要便捷导入三方库，可以单独以工程的方式打开使用。

cjpm.toml中的相关字段说明：

• dependencies：当前仓颉模块依赖的项目，包含构建所需其它模块的配置信息（版本号和路径两个选项必须全部配置，否则执行失败并报错）。日常使用中优先使用此方式导入项目依赖；
• dev-dependencies：格式与dependencies一致，用于指定仅在开发过程中使用的依赖项（例如仅在测试中使用的依赖），库作者应将下游用户不需要的依赖放在此字段中；
• bin-dependencies：非特殊需求场景下建议使用dependencies方式导入依赖。目前仓颉插件仅支持本地的bin-dependencies配置。

bin-dependencies 的两种导入形式

当前仓颉模块依赖已编译好的package，有两种导入形式。以下述目录结构为例（导入pro0模块的xoo、yoo包与pro1模块的zoo包）：

test ├── pro0 │ ├── libpro0_xoo.so │ ├── xoo.cjo │ ├── libpro0_yoo.so │ └── yoo.cjo ├── pro1 │ ├── libpro1_zoo.so │ └── zoo.cjo ├── src │ └── main.cj └── cjpm.toml

方式一：通过package-option导入（map 结构，key 为包名，value 为 .cjo 前端文件的路径）：

[target] [target.x86_64-w64-mingw32] [target.x86_64-w64-mingw32.bin-dependencies] [target.x86_64-w64-mingw32.bin-dependencies.package-option] pro0_xoo = "./test/pro0/xoo.cjo" pro0_yoo = "./test/pro0/yoo.cjo" pro1_zoo = "./test/pro1/zoo.cjo"

package-option中pro0_xoo名称作为 key，与libpro0_xoo.so相对应；前端文件 .cjo 的路径作为 value。与 .cjo 对应的.a和.so需放置在相同路径下，且对应的 .cjo 模块文件必须与模块名来源文件放在相同的文件夹下，该文件夹下不能有任何其他文件或文件夹。

方式二：通过path-option导入（字符串数组结构，每个元素代表待导入的路径名称）：

[target] [target.x86_64-w64-mingw32] [target.x86_64-w64-mingw32.bin-dependencies] path-option = ["./test/pro0", "./test/pro1"]

cjpm会自动导入该路径下所有符合规则的仓颉库包，合规性是指库名称格式为模块名_包名；库名称不满足该规则的包只能通过package-option导入。

优先级：如果同时通过package-option和path-option导入相同的包，则package-option字段的优先级更高。

ffi：外部 C 库依赖

ffi表示当前仓颉模块外部依赖 C 库，配置了依赖该库所需的信息（包含名称和路径字段）。资源管理器的CANGJIE LIBRARY视图栏可以方便地添加这几类外部库：

• 工程初始化后，单击分类栏的加号按钮添加对应的三方库；
• 单击三方库上的减号删除对应的库；
• 单击视图栏的编辑按钮，打开三方库导入的可视化界面来导入或删除三方库。

以上删除和添加操作均同步到工程的cjpm.toml文件中（源码中通过RequiresActionController读取所选路径并回写 TOML，见 require-action-controller.ts）。

7.2 导入限制与注意事项

• 项目中需要链接动态库（C 库和仓颉库）时，需自行设置LD_LIBRARY_PATH，执行export LD_LIBRARY_PATH=xxx:$LD_LIBRARY_PATH；
• 在cjpm.toml中修改内容不会直接影响 treeView 和 UI 界面，需要单击 treeView 或 UI 界面进行手动更新；
• 在 treeView 的库分类处添加外部库时，若此时库分类目录是关闭状态，添加后需要打开目录才能查看；
• UI 界面的字段暂不支持 hover 显示内容的功能；
• UI 界面非开发者添加的外部库，其路径与cjpm.toml保持一致；开发者添加的库和 treeView 均显示绝对路径。

八、总结

仓颉 VSCode 插件把 cjpm 的编译、测试、安装、卸载能力以命令面板、终端、运行按钮、锤子按钮四种形态接入 IDE，并用cjpm.toml+cjpm_build_args.json双配置文件配合 UI 可视化编辑器，显著降低了编译构建参数与三方库依赖的管理成本。理解每个命令背后的底层 cjpm 参数（见 cjpm-build-collection.ts 与 cjpm-install-collection.ts），掌握customized-option、target、package-configuration、bin-dependencies等字段的配置与转义规则，即可在 VSCode 中高效完成仓颉工程的完整构建链路。

• 开发工具
• 代码编辑器
• 调试器