常见问题
为什么选中的 SDK 版本不对?
请先运行 cjv show active 查看当前选中的工具链及其生效来源,再按以下优先级依次检查:
- 命令行显式参数(全局
+name或--toolchain)。 CJV_TOOLCHAIN环境变量。- 当前目录及父目录中的本机目录覆盖(
cjv override list)和cangjie-sdk.toml。cjv从当前目录逐层向上检查,在同一层目录中目录覆盖优先于项目文件;完整规则见项目工具链。 - 全局默认工具链(
cjv default)。
如果在当前终端中执行过 cjv envsetup,shell 的 PATH 会直接指向具体 SDK 的工具目录,绕过代理选择。打开新终端可恢复代理自动选择,也可以重新加载所需工具链的环境。
项目文件拼错字段后会怎样?
cangjie-sdk.toml 中的未知字段会打印警告,其余已识别字段继续解析。但如果剩余字段没有提供有效的 channel 或 path(或者文件为空、存在 TOML 语法错误),命令会直接报错退出,而不会静默退回默认工具链。需要恢复上级目录或全局默认选择时,请删除该文件。
编译产物提示找不到运行时库怎么办?
编译生成的仓颉程序通常需要动态链接 SDK 或 stdx 中的运行时库。使用 cjv exec 运行程序,即可由 cjv 自动为该子进程配置动态库搜索路径:
cjv exec ./my_binary
你也可以为当前终端会话求值加载 cjv envsetup 的输出。各 shell 的具体写法见运行命令与配置环境。
离线环境怎样安装和使用?
可以根据实际环境选择以下三种方案之一:
- 复用预填充缓存(
--offline) — 在联网机器上执行安装后,将<CJV_HOME>/cache/与cangjie-sdk.toml一起复制到离线环境,加上--offline(或CJV_OFFLINE=1)运行,见自动化与 JSON 接口。 - 使用本地 SDK 归档或目录 — 使用
cjv toolchain import导入归档,或通过cjv toolchain link引用已解压目录,见自定义 SDK。 - 部署企业内部分发源(
dist_server) — 受管终端配置内部分发源,并在系统后备配置中关闭自动补装和自更新检查,见企业与离线部署。
请注意,已安装的工具链可以完全在本地运行,但离线构建项目时还需提前准备好 cjpm 的项目依赖包。
自定义工具链为什么不能用 component add 下载组件?
通过 toolchain import 或 toolchain link 注册的自定义 SDK 没有上游官方发行记录,component add 无法确定其组件制品。替代方式如下:
- 归档安装可自动安装随包附带的
stdx,也可通过cjv component link stdx挂载本地stdx目录。 - 外部目录链接由源 SDK 目录的所有者自行维护,不支持通过
cjv组件命令修改。详见组件与离线文档。
卸载会删除什么?
cjv uninstall <name>删除所选 SDK、附属的交叉编译目标、stdx和离线文档组件,并清理引用它的本机目录覆盖。如果它是当前默认工具链,cjv会尝试改选其他已安装宿主,否则清除默认选择。通过toolchain link或component link引用的外部源目录会完整保留。cjv self uninstall删除整个<CJV_HOME>数据目录及其中所有安装、缓存和历史快照,并清理PATH。命令选项见命令参考。
macOS 下载页为什么让我选架构?
部分浏览器在 Apple Silicon Mac 上仍会报告 Intel(x86_64)User-Agent,导致网页无法始终可靠地判断 Mac 的原生 CPU 架构。如果在终端中运行 install.sh 安装脚本,脚本会在本机自动识别;如果手动下载归档,可在终端运行 uname -m:arm64 对应 Apple Silicon,x86_64 对应 Intel。
nightly 缺少校验和时怎么处理?
cjv 从 nightly.json 读取版本和下载地址。如果某个 SDK 条目暂时没有 sha256 值,cjv 会自动尝试请求 <url>.sha256;如果该 sidecar 文件尚未发布,则会提示完整性限制。企业内网镜像可以直接在 nightly.json 清单中填写完整的 64 位 SHA-256 校验和,详见内部分发源格式。