cjv 用户手册
Warning
cjv 已转入维护模式,不再开发新功能,后续仅处理安全修复。
你仍可继续使用 cjv,但不保证其能正常工作。
cjv 是仓颉 SDK 的版本管理器,可以在本机安装多套工具链,并为不同项目选择各自需要的版本。配置好命令路径后,cjc、cjpm 等命令会通过 cjv 调用所选 SDK。
开始使用
首次使用请先安装 cjv,然后按快速上手检查工具链、配置项目和运行命令。
安装向导会根据当前平台查询可用通道。cjv 支持的平台与仓颉 SDK 的发布范围可能不同,具体版本可以通过 cjv toolchain list-remote 查询。
配置项目与管理 SDK
工具链与版本说明通道、固定版本和名称格式。在团队项目中,可以提交 cangjie-sdk.toml,统一声明版本、组件和目标 SDK。
扩展库和离线文档见组件,其他目标平台的 SDK 见交叉编译。已有的 SDK 目录或归档也可以注册为自定义工具链。
运行编译产物或配置当前 shell 时,参见运行命令与配置环境。
配置与参考
配置和环境变量说明用户设置与临时覆盖。网络代理适用于需要代理访问上游的环境;内部分发源、受管终端和完全离线安装见企业与离线部署。
版本固定校验、CI 隔离、离线缓存、更新回退和 JSON 输出见自动化与 JSON 接口。参与开发请阅读开发指南。
安装 cjv
cjv 是独立分发的单文件程序,安装前不需要仓颉 SDK。安装后,cjv 及 cjc、cjpm 等 SDK 工具的代理入口位于 <CJV_HOME>/bin,默认路径为 Unix 上的 ~/.cjv/bin 和 Windows 上的 %USERPROFILE%\.cjv\bin。
使用安装脚本
安装脚本支持 Linux、macOS、Windows 和鸿蒙 HiShell。
在 Linux、macOS 或鸿蒙 HiShell 中执行:
curl -sSf https://cjv.zxilly.com/install.sh | sh
在 Windows PowerShell 中执行:
irm https://cjv.zxilly.com/install.ps1 | iex
安装脚本会自动识别当前操作系统与 CPU 架构,下载并校验 cjv 可执行文件的 SHA-256 校验和,随后运行 cjv init。在交互式终端中,cjv init 会显示安装向导;当标准输入不是终端时,则会直接使用默认选项完成初始化。
非交互与自动化安装参数
两个安装脚本都支持传入命令行参数,以便在 CI 流水线或自动化脚本中跳过交互提示,或者先只安装 cjv 本体(后续再由项目的 cangjie-sdk.toml 按需选择并安装 SDK):
curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- -y --default-toolchain none
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Yes -DefaultToolchain none
Unix 安装脚本(install.sh)自身消费 --mirror 和 --version 两个参数,并将其余参数原样转发给 cjv init。PowerShell 安装脚本(install.ps1)则提供对应的 -Mirror、-Version、-Yes、-DefaultToolchain 和 -NoModifyPath 参数。cjv init 支持的全部选项见命令参考。
固定 cjv 本体版本
在需要严格复现构建环境的自动化场景中,可以指定要安装的 cjv 发布标签(包括预发布版本):
curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- --version v0.4.1 -y --default-toolchain none
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Version v0.4.1 -Yes -DefaultToolchain none
请将示例中的 v0.4.1 替换为实际需要的版本标签。两个脚本也会读取 CJV_VERSION 环境变量,但命令行显式传入的版本参数优先级更高;两者都未指定时,默认下载最新稳定版。
--version / CJV_VERSION 选择的是 cjv 管理器本体的版本,而 --default-toolchain / -DefaultToolchain 选择的是仓颉 SDK 工具链,两者彼此独立。此外,显式设置的下载地址变量(CJV_UPDATE_ROOT、CJV_GITHUB_ROOT、CJV_GITCODE_ROOT)优先于版本参数;如果使用企业内部制品源,应将地址直接指向所选版本的制品目录。
初始化时的 SDK 选择规则
默认情况下,cjv init 会查询当前主机平台可用的发布通道,并按 lts、sts、nightly 的顺序自动选择第一个可用通道。你可以使用 --default-toolchain <name> 明确指定要安装的工具链,或者使用 --default-toolchain none 只安装 cjv 本体。
如果初始化过程中下载或安装 SDK 失败,命令会返回非零退出码,但已安装好的 cjv 本体会被保留下来。错误输出中会直接给出带程序绝对路径的重试命令(无需先刷新 PATH 即可运行),你也可以运行 cjv toolchain list-remote 查询当前分发源提供的可用版本。
使用 GitCode 镜像
当所处网络环境访问 GitHub 不稳定时,可以加上 --mirror(或 -Mirror)从 GitCode 镜像源安装:
curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- --mirror
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Mirror
镜像构建默认使用 GitCode 获取仓颉版本清单和 cjv 自更新。如果在企业内网自建制品库,请参阅企业与离线部署。
手动下载归档安装
如果不希望在终端直接运行在线脚本,也可以从 GitHub Releases 下载对应平台的归档文件,解压后将 cjv(Windows 为 cjv.exe)放入 PATH 目录,再运行 cjv init:
| 平台 | 发布归档文件名 |
|---|---|
| Linux x86_64 | cjv_linux_amd64.tar.gz |
| Linux ARM64 | cjv_linux_arm64.tar.gz |
| macOS Apple Silicon | cjv_darwin_arm64.tar.gz |
| macOS Intel | cjv_darwin_amd64.tar.gz |
| Windows x86_64 | cjv_windows_amd64.zip |
| 鸿蒙 x86_64 | cjv_openharmony_amd64.tar.gz |
| 鸿蒙 ARM64 | cjv_openharmony_arm64.tar.gz |
GitCode Releases 提供前缀为 cjv-mirror_ 的对应镜像归档。此外,官方网站下载页还提供 cjv-init(及 cjv-init.exe)独立安装器,运行后会直接启动安装向导。
从源码编译安装
如果本机已安装满足仓库 go.mod 版本要求的 Go 工具链,可以直接从源码编译安装:
go install github.com/Zxilly/cjv/cmd/cjv@latest
cjv init
Go 会将编译出的程序放入 GOBIN(未配置时为 $(go env GOPATH)/bin);将该目录加入 PATH 或运行 cjv init 即可。关于自定义构建标签与跨平台编译,请参阅开发指南中的从源码构建。
PATH 配置与安装验证
SDK 代理命令(cjc、cjpm 等)位于 <CJV_HOME>/bin,默认路径为 ~/.cjv/bin。运行 cjv init 会自动配置 PATH(Windows 写入当前用户注册表 PATH,Unix 写入对应的 shell 配置文件)。即使跳过 init 直接安装 SDK,首次工具链安装也会自动尝试配置 PATH。
安装完成后,打开一个新终端并运行以下命令验证:
cjv --version
如果希望自行管理 PATH,可以在运行 cjv init 时传入 --no-modify-path(PowerShell 安装脚本传入 -NoModifyPath),或者设置环境变量 CJV_NO_PATH_SETUP=1。接下来请继续阅读快速上手安装并切换工具链。
快速上手
完成安装 cjv后,可以检查工具链、设置默认版本、配置项目版本,以及更新和卸载工具链。
检查安装状态
如果已经完成了安装向导,请打开一个新终端(使更新后的 PATH 生效),然后检查当前选中的工具链并运行编译器:
cjv show
cjc --version
cjv show 会列出当前默认主机平台、本机已安装的所有工具链以及当前激活的工具链。如果终端提示找不到 cjc,请检查 <CJV_HOME>/bin(默认路径为 ~/.cjv/bin)是否已经在 PATH 中;命令路径的配置方式见安装说明。
选择默认工具链
如果在安装 cjv 时跳过了 SDK,可以先查询当前平台的可用通道,再将其设为全局默认工具链。下面以 lts 通道为例:
cjv toolchain list-remote --channel lts
cjv default lts
cjc --version
如果指定的官方工具链尚未安装,cjv default 会自动先下载并安装它,再保存默认选择。如果当前平台没有发布 LTS SDK,可以改查 sts 或 nightly 通道并替换为可用通道;你也可以重新运行 cjv init,由安装向导帮你选择可用通道。
全局默认工具链用于所有没有项目声明(cangjie-sdk.toml)且没有设置目录覆盖的目录。随时运行 cjv show active 即可查看当前生效的工具链及其选择来源。关于通道与版本号的完整语法,请参阅工具链与版本。
为项目选择版本
使用 cangjie-sdk.toml
在团队协作项目中,可以在项目根目录创建 cangjie-sdk.toml 并提交到版本控制,从而让所有成员和 CI 自动使用相同的工具链与组件:
[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]
示例中的 lts-1.0.5 请替换为项目实际需要且分发源提供的版本(或者直接运行 cjv pin lts 自动解析并写入完整版本名)。
此后在该目录中运行 cjpm build 或 cjc 时,cjv 会使用文件声明的工具链。默认开启的自动安装功能会在首次调用时补齐缺失的 SDK 和组件;已安装的工具链不会因每次运行代理命令而自动升级。
设置本机目录覆盖
如果只想在自己的机器上临时切换某个目录使用的工具链,而不修改项目仓库中的配置文件,可以使用目录覆盖:
cjv override set sts
cjv show active
cjv override unset
目录覆盖保存在你个人的 ~/.cjv/settings.toml 设置文件中,而 cangjie-sdk.toml 则可以随代码提交到版本控制。两者的优先级关系见项目工具链。
临时使用其他版本运行命令
使用 cjv exec 临时选择工具链,不修改默认设置或目录配置:
cjv exec +sts cjc --version
cjv exec 可运行 SDK 工具或自己的程序,并配置 SDK、运行时和 stdx 动态库路径,按 auto_install 补齐缺失项。cjv run sts cjc --version 保留为显式工具链兼容写法。详见运行命令与配置环境。
查看工具链状态
查看本机工具链状态:
cjv show active
cjv which cjc
cjv toolchain list
cjv show active— 显示当前激活的工具链名称及其选择来源(如项目文件、目录覆盖或全局默认)。cjv which cjc— 显示当前激活 SDK 中cjc编译器的实际文件系统路径。cjv toolchain list— 列出宿主和交叉 SDK 的安装名称、实际发行版与跟踪/固定/自定义类型。show installed保留为隐藏兼容入口。
更新与卸载
更新工具链与 cjv 本体
检查可用更新并更新已安装的跟踪通道:
cjv check
cjv update
cjv check 只查询已安装 SDK 和 cjv 本体的可用更新,不执行安装。cjv update 会更新所有已安装的跟踪通道(lts、sts、nightly),而固定版本(如 lts-1.0.5)和自定义工具链保持原样不变。
执行全量 cjv update 时是否同时检查或更新 cjv 本体,由 auto_self_update 设置控制(默认为 check)。你也可以随时手动更新 cjv 本体:
cjv self update
卸载工具链
要移除不再需要的工具链并释放磁盘空间:
cjv uninstall sts
卸载宿主工具链会同时移除它附属的组件、交叉编译目标和离线文档。更多命令参数与选项请参阅命令参考。
运行命令与配置环境
<CJV_HOME>/bin 中的 cjc、cjpm 等程序是 SDK 工具的代理入口。代理按项目工具链规则选择 SDK,准备环境变量和动态库路径,并转发命令行参数和子进程退出码。
运行 SDK 工具与自己的程序
除了直接运行 cjc、cjpm 等代理命令外,cjv 还提供了 cjv run 和 cjv exec 两个子命令,用于在独立的子进程环境中执行命令:
cjc --version
cjv exec +sts cjc --version
cjv exec ./my_binary arg1 arg2
cjv exec +nightly ./my_binary
理解两者的定位可以帮助你快速选择合适的命令:
cjv run [--install] <toolchain> <command> [args...]— 保留显式工具链位置参数的兼容入口,可执行任意程序。它与exec使用相同运行环境和auto_install补装策略;--install显式开启补装,--install=false关闭补装,显式开启与--no-auto-install互斥。cjv exec [+toolchain] <command> [args...]— 推荐入口,使用当前项目选择或指定工具链,配置 SDK、运行时及 stdx 库路径,并按auto_install补齐缺失需求。显式指定工具链时使用该选择;当前项目中的组件和目标声明在使用项目选择时生效。
run 和 exec 都只改变子进程的运行环境,不会污染当前终端会话,并且会原样转发标准输入、标准输出、标准错误和退出码。
如果待运行的命令名称本身以 + 开头,请在命令名前加上 --,避免它被当作 +toolchain 选择器解析:
cjv exec -- +command
which 只读取工具路径(省略工具名时读取 SDK 根目录),不安装缺失项,也不要求补齐无关的项目组件或目标。
使用 envsetup 配置当前 shell
在与外部构建系统(如 Makefile、CMake 或自定义脚本)配合时,有时需要将 SDK 的工具路径和环境变量直接导入当前交互式终端会话。cjv envsetup 会向标准输出打印一段环境配置脚本,在当前 shell 中求值执行即可生效:
# Bash 或 Zsh
eval "$(cjv envsetup)"
# Fish
cjv envsetup | source
# Windows PowerShell
cjv envsetup | Invoke-Expression
你可以运行 cjv envsetup +nightly 显式指定工具链版本,或者传入 --shell=bash|fish|powershell|cmd 指定输出脚本的语法格式。省略 --shell 时,cjv 会自动检测当前 shell;如果检测失败,会在 stderr 打印提示并回退到 POSIX shell 格式。此外,运行 cjv --json envsetup 可以输出结构化的环境变量 JSON 数据,供编辑器插件或自动化脚本读取(详见自动化与 JSON 接口)。
envsetup 只读取已安装 SDK 并验证项目声明的组件和目标;缺失时给出显式安装命令,不会触发自动补装。它只接受至多一个 +toolchain 位置参数,多余参数会报错。
设置的环境变量
无论是通过代理命令、cjv run、cjv exec 还是 cjv envsetup,cjv 都会为所选 SDK 配置以下环境信息:
CANGJIE_HOME— 指向所选 SDK 安装的根目录。PATH— 将 SDK 的编译器与工具目录前置加入PATH。- 运行时动态库路径 — 按宿主操作系统设置动态库搜索路径:Linux 与鸿蒙使用
LD_LIBRARY_PATH,macOS 使用DYLD_LIBRARY_PATH,Windows 使用PATH。 stdx扩展库路径 — 如果该工具链已安装stdx组件,cjv会自动注入CANGJIE_STDX_PATH_DYNAMIC和CANGJIE_STDX_PATH_STATIC,分别指向组件的dynamic/与static/目录。
切换项目与恢复代理选择
请注意,在当前终端中求值执行 envsetup 的输出后,当前会话的 PATH 会直接指向某个具体 SDK 的工具目录(排在 <CJV_HOME>/bin 之前)。此时在该终端中切换到其他项目目录,将不再按 cangjie-sdk.toml 自动切换编译器。
如果需要恢复按项目自动选择工具链,打开一个新终端;或者在当前终端再次执行 envsetup 切换到目标工具链。
交叉 SDK 环境
进行跨平台交叉编译时,可以通过 cjv envsetup --target 加载已安装交叉编译 SDK 的工具路径与库环境:
cjv install sts --target ohos
eval "$(cjv envsetup +sts --target=ohos)"
--target 会使用所选宿主工具链同一发行版下已安装的交叉 SDK 路径和库环境。它不会自动安装缺失的目标 SDK,也不提供模拟器或跨平台程序直接运行能力。
目标平台所需的编译器参数、系统库与运行条件请参阅对应仓颉 SDK 文档;使用 cjv 安装和管理交叉编译目标的方法见交叉编译。
工具链与版本
工具链是一份仓颉 SDK 安装,包含编译器(cjc)、包管理器(cjpm)、构建工具和运行时库。cjv 将工具链安装在 <CJV_HOME>/toolchains/ 下,将可选组件(stdx 和离线文档)存放在独立目录中。
cjv 支持多种类型的工具链:最常见的是跟踪官方发布通道(lts、sts 和 nightly)的工具链,同时也可以安装官方清单中的特定固定版本、其他主机平台的工具链,以及来自本机目录或归档文件的自定义工具链。
通道与名称
标准发布通道与版本工具链的名称遵循以下格式:
[<channel>-]<version>[-<host>]
<channel>[-<date>][-<host>]
<channel> = lts|sts|nightly
<version> = <major.minor>|<major.minor.patch>|<nightly-version>
<date> = YYYY-MM-DD
<host> = <os>-<arch>
下表展示了不同工具链选择器的具体含义:
| 名称 | 含义 |
|---|---|
lts | 跟踪长期支持通道(Long-Term Support) |
sts | 跟踪短期支持通道(Short-Term Support) |
nightly | 跟踪已发布清单中的每日开发构建通道 |
lts-1.0.5 | 固定通道中的具体发行版本 |
1.0.5 | 省略通道前缀,由 cjv 在稳定通道中查找匹配版本 |
sts-1.2、1.2 | 选择该次版本系列中的最新稳定补丁版本 |
nightly-2026-10-04 | 选择该日期发布的最新 nightly 构建 |
my-sdk | 使用 cjv toolchain link 创建的自定义工具链 |
表中的版本号和日期仅用于演示名称语法。要查询当前分发源为你的平台实际发布了哪些版本,请运行 cjv toolchain list-remote:
cjv toolchain list-remote --channel lts
cjv toolchain list-remote --channel nightly --limit 10
官方通道名称不区分大小写。自定义工具链名称不能与官方通道或版本格式冲突,不能包含路径分隔符或以 + 开头,也不能是 .、.. 或空字符串。
跟踪通道与固定版本
当你分别安装通道名 lts 和具体版本 lts-1.0.5 时,cjv 会将它们作为两个完全独立的安装实例管理:
cjv install lts
cjv install lts-1.0.5
之后运行 cjv update lts(或 cjv update)时,cjv 只会将跟踪通道 lts 更新到该通道的最新版本,而固定的 lts-1.0.5 保持原样不变;两者的附属组件和交叉编译目标也分别独立管理。日常运行 cjc 时始终使用本机已安装的版本,已有安装只有显式执行 cjv update 时才会升级;install 保留现有发行版。
toolchain list 同时显示安装名称、实际发行版和类型。例如 lts → lts-1.0.5 标为跟踪通道,独立的 lts-1.0.5 标为固定版本;相同发行版可以有不同的更新生命周期。
次版本简写(如 sts-1.2)和日期简写(如 nightly-2026-10-04)在安装时会被解析为具体的发行版并固定安装。如果需要团队成员与 CI 使用完全一致的发行版,请在 cangjie-sdk.toml 中写入完整版本名(或运行 cjv pin 自动解析写入)。
Nightly 通道与组件兼容性
由于 nightly 构建发布频繁,有时最新一次 nightly 构建可能尚未包含某个可选组件(如 stdx、docs)或交叉编译 SDK。
首次安装或显式更新 nightly 通道时,cjv 会综合考虑你请求的(或该通道上已安装的)组件与交叉 SDK 集合,自动在 nightly.json 保留的历史记录中查找最新的兼容版本。默认情况下,cjv 不会将已安装的 nightly 降级到更旧的版本;如果允许选择更旧的兼容 nightly 构建,可以传入 --allow-downgrade。其他安装与更新策略详见命令参考。
主机平台
你可以在工具链名称末尾附加主机平台后缀,例如 sts-linux-x64 或 sts-1.2.0-darwin-arm64。不同主机平台作为独立工具链安装;显式写出当前机器默认主机平台的名称(例如在 Linux x86_64 机器上写 lts-linux-x64),与省略平台后缀的名称(lts)指向同一个安装实例。
请注意,安装其他操作系统的宿主 SDK 并不能让该平台的程序直接在本机运行。如果需要在当前机器上为其他平台编译代码,请通过交叉编译目标管理将交叉 SDK 附加到当前宿主工具链上。交叉编译 SDK 依附于宿主工具链,不能单独设为全局默认或当前活跃工具链。
自定义 SDK
对于自行编译仓颉 SDK 或处于离线环境的开发者,cjv 支持管理本机 SDK 目录与归档文件。要链接本机已解压的 SDK 目录,可以运行:
cjv toolchain link my-sdk /path/to/local/sdk
cjv default my-sdk
目录链接直接引用你自行维护的已有 SDK 目录;运行 cjv uninstall my-sdk 只会移除 cjv 中的链接记录,保留你的源目录不变。
如果需要 cjv 托管独立的 SDK 副本,或者为自定义 SDK 挂载本地 stdx,请使用 cjv toolchain import <name> <archive|url>,详见自定义 SDK。自定义工具链不会通过 update 更新,也不能通过 component add 下载官方组件。
运行 cjv toolchain list 可以查看本机安装的所有工具链,运行 cjv show active 可以查看当前激活的工具链及其选择来源。完整选择规则见项目工具链。
项目工具链
运行 cjc、cjpm 等代理命令时,cjv 按当前目录选择工具链。在项目根目录提交 cangjie-sdk.toml,可以为开发者和 CI 声明 SDK 版本、组件和交叉编译目标:
[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]
示例中的 lts-1.0.5 仅作演示;支持的所有通道与版本名称格式见工具链与版本。
除了手动编写外,你也可以在项目根目录直接运行 cjv pin lts 自动写入解析后的具体发行版名称,或运行不带参数的 cjv pin 固定当前激活的工具链选择,文件中已有的 components 与 targets 列表会被完整保留。在 CI 环境中,可以运行 cjv pin --check 验证当前目录的项目文件是否已经固定了具体发行版(不修改文件也不访问网络),详见自动化与 JSON 接口。
选择顺序
有多种方式可以控制和覆盖当前使用的工具链。cjv 按以下顺序从高到低选择工具链,并采用第一个指定的来源:
- 命令行中显式指定的工具链,例如全局
+name简写(如cjv +nightly show)或子命令支持的--toolchain参数。 CJV_TOOLCHAIN环境变量。- 从当前工作目录向文件系统根目录逐层向上查找:在每一层目录中,先检查本机目录覆盖,再检查
cangjie-sdk.toml,找到第一个匹配项后立即停止。 cjv default设置的全局默认工具链。
请特别留意第 3 步向上遍历目录树时的就近原则:目录覆盖和 cangjie-sdk.toml 都优先采用离当前工作目录更近的配置。因此在同一层目录中,本机目录覆盖优先于该目录的 cangjie-sdk.toml;但子目录中的 cangjie-sdk.toml 优先于父目录的本机目录覆盖。不同目录层级的 cangjie-sdk.toml 文件不会合并。
要验证当前目录选中的工具链及其生效来源,运行:
cjv show active
注意:cjv run <toolchain> <command> 始终使用命令参数中的 <toolchain>。当命令行显式选择或 CJV_TOOLCHAIN 环境变量优先于项目文件生效时,cangjie-sdk.toml 中声明的组件和目标要求不会附加到该选择上。
字段说明
cangjie-sdk.toml 采用 TOML 格式,所有配置字段均位于 [toolchain] 表下:
| 字段 | 类型 | 说明 |
|---|---|---|
channel | string | 通道名、版本选择器或已注册的自定义工具链名称 |
path | string | 外部 SDK 目录的绝对路径,与 channel 互斥 |
components | string[] | 需要的附加组件(stdx、docs、stdx-docs),默认为空 |
targets | string[] | 需要的交叉编译 SDK 后缀(例如 ohos),默认为空 |
工具链配置项详解
channel 与 path
每个 cangjie-sdk.toml 必须且只能指定 channel 和 path 中的一个:
channel指定官方通道(lts、sts、nightly)、版本选择器(lts-1.0.5、1.2、nightly-2026-10-04)或通过toolchain import/toolchain link注册的自定义工具链名称。path使用绝对路径直接指向本机已解压的外部 SDK 目录:
[toolchain]
path = 'C:\SDKs\cangjie'
由于 path 直接引用外部 SDK 目录,其组件由该 SDK 目录的所有者自行维护,因此使用 path 时 components 与 targets 不会触发自动安装。
组件与目标 SDK(components 与 targets)
当 channel 选中受管工具链时,可以声明项目所需的组件和交叉编译目标 SDK:
[toolchain]
channel = "sts"
components = ["stdx", "docs"]
targets = ["ohos", "android"]
在 targets 中请只写目标后缀(如 ohos、android),不要写 linux-x64-ohos 这样的完整宿主-目标平台名。cjv 会自动规范化大小写和下划线、展开逗号分隔项并去除重复项;空字符串目标会报错。
当该文件选中当前活跃工具链时,这一声明会自动准备宿主 SDK、宿主组件和目标 SDK。编译时如何加载目标 SDK 环境见交叉编译。
自动安装
auto_install 设置默认开启(true)。当运行 cjc、cjpm 等代理命令时,cjv 会自动下载并补齐所选 cangjie-sdk.toml 中声明的缺失项。
如果希望缺少依赖时直接报错而不是自动下载,可以在用户设置中关闭 auto_install:
cjv set auto-install false
如果只想对单次调用关闭自动补装而不修改配置文件,可以使用 cjv --no-auto-install exec cjc --version,或为代理命令设置环境变量 CJV_AUTO_INSTALL=0。显式执行的 cjv install 不受该选项影响。
项目文件错误
cangjie-sdk.toml 中如果包含未知键名,cjv 会向 stderr 打印警告并继续解析已识别字段。但如果存在 TOML 语法错误、未知组件名称、文件内容为空,或缺少有效的 channel / path,命令会直接报错退出,而不会退回默认工具链。要恢复上级目录或全局默认选择,请删除该文件。
本机目录覆盖
使用 cjv override 可以在不修改项目文件的情况下,为本机的某个目录指定专用的工具链覆盖。设置后,在该目录及其子目录中运行 cjc 或 cjpm 都会调用覆盖指定的工具链:
cjv override set nightly
cjv override set lts --path /path/to/project
cjv override list
cjv override unset
cjv override unset --nonexistent
目录覆盖保存在用户设置文件 settings.toml 中。cjv override unset --nonexistent 可以清除磁盘上已不存在目录的残留覆盖。
组件与离线文档
组件是附属于工具链的可选扩展库和离线文档。组件按工具链分别存放,并随所属工具链一同卸载:
| 组件 | 内容 | 相对 CJV_HOME 的位置 |
|---|---|---|
stdx | 动态与静态扩展库 | stdx/<tc>/{dynamic,static} |
docs | 仓颉语言、标准库和工具文档 | docs/<tc>/main/ |
stdx-docs | 扩展库(stdx)文档 | docs/<tc>/stdx/ |
当所选工具链安装了 stdx 后,代理命令(cjc、cjpm)、cjv exec 和 cjv envsetup 会自动向运行环境注入 CANGJIE_STDX_PATH_DYNAMIC 与 CANGJIE_STDX_PATH_STATIC。文档组件(docs 与 stdx-docs)供 cjv doc 打开阅读,不会修改运行时环境变量。
安装与移除
你可以在安装工具链时通过 -c(--component)参数一并安装组件,也可以随时通过 cjv component 子命令为已安装的工具链增删组件:
cjv install nightly -c stdx,docs
cjv component add stdx docs --toolchain lts
cjv component list --toolchain lts
cjv component list --installed -q
cjv component remove stdx-docs
- 未指定
--toolchain时,命令默认作用于当前激活的工具链。 - 传入
--target <suffix>时,命令作用于该宿主工具链下已安装的交叉编译目标 SDK(例如cjv component add stdx --toolchain sts --target ohos)。 - 组件名可以传入多个参数,也可以用逗号分隔(如
stdx,docs)。 cjv component add默认跳过已安装的组件;加上--reinstall可以重新下载安装。
实际可下载的组件制品取决于所选通道、版本和平台。自定义工具链没有上游官方清单记录,因此无法通过 cjv component add 下载官方组件。在团队项目中,也可以在 cangjie-sdk.toml 中声明 components,由自动安装按需补齐。
component list --names-only 单列打印名称;全局 --quiet / -q 只关闭进度,在命令前后含义相同。旧 add --force 和 link --force 分别保留为 --reinstall 和 --replace 的隐藏兼容标志。
更新行为
运行 cjv update 升级跟踪通道(lts、sts、nightly)时,cjv 会将宿主 SDK 和已选组件作为同一事务一并更新;固定版本(如 lts-1.0.5)的组件保持不变。通过 component link 挂载的本地 stdx 在通道更新后仍保留原本地链接。
链接本地 stdx
如果你在本机编译了 stdx 或有现成的本地目录,可以使用 cjv component link 将其挂载到指定工具链:
cjv component link stdx /path/to/local/stdx --toolchain lts --replace
指定的源目录必须同时包含 dynamic/ 和 static/ 子目录。--replace 用于替换该工具链上已有的 stdx 组件;运行 cjv component remove stdx 移除链接时,只会删除 cjv 内部管理的链接记录,保留你的本地源目录不变。注意 docs 和 stdx-docs 不支持本地目录链接。
自定义 SDK 的组件管理
组件修改要求目标 SDK 位于 cjv 管理的真实目录中。通过 cjv toolchain link <name> /path/to/sdk 直接引用的外部解压目录由该目录的所有者维护,不支持通过 cjv component 命令修改。
如果需要让 cjv 为自定义 SDK 管理组件(例如挂载本地 stdx),请先从本地归档或 URL 安装该自定义 SDK:
cjv toolchain import my-sdk ./cangjie-sdk.zip
cjv component link stdx /path/to/local/stdx --toolchain my-sdk
打开离线文档(cjv doc)
安装好 docs 或 stdx-docs 组件后,使用 cjv doc(或命令别名 cjv docs)即可在默认浏览器中打开本地 HTML 文档:
cjv doc
cjv doc std
cjv doc dev-guide
cjv doc tools
cjv doc stdx --toolchain nightly
cjv doc --path
你可以指定要打开的文档主题:
- 省略主题(
cjv doc) — 优先打开主体文档首页(docs);若仅安装了扩展库文档,则打开stdx-docs首页。 std— 打开标准库 API 参考文档(需安装docs)。dev-guide(或别名book)— 打开仓颉开发指南(需安装docs)。tools— 打开 SDK 工具指南(需安装docs)。stdx— 打开扩展库参考文档(需安装stdx-docs)。
传入 --path 或 --json 时,命令只向标准输出返回本地文件路径而不启动浏览器。如果缺少对应的文档组件,cjv 会提示安装命令。
自定义 SDK:目录、归档与 URL
cjv toolchain link 引用已解压的 SDK 目录;cjv toolchain import 从本地 .zip / .tar.gz 归档或 HTTP(S) URL 创建受管安装:
cjv toolchain link local-sdk /path/to/sdk
cjv toolchain import archive-sdk ./cangjie-sdk.zip
cjv toolchain import remote-sdk https://example.com/cangjie-sdk.tar.gz
这三条命令使用各自独立的名称,可以分别执行。注册自定义工具链不会修改当前的全局默认工具链;如果需要将其设为默认,请运行 cjv default <name>,或者在项目的 cangjie-sdk.toml 中配置 channel = "<name>"。
指定的名称必须符合自定义工具链命名规则,不能使用 lts、sts、nightly 等官方名称。
目录与归档的区别
根据传入的是已解压目录还是归档/URL,cjv 对文件的管理方式有所不同:
| 来源 | 安装方式 | 卸载行为(cjv uninstall) |
|---|---|---|
| 已解压目录 | 建立轻量目录引用;要求存在 bin/cjc(Windows 为 cjc.exe) | 只删除 cjv 中的链接记录,保留源 SDK 目录不变 |
| 本地归档或 URL | 解包到 <CJV_HOME>/toolchains/ 下由 cjv 管理的真实目录 | 删除受管的安装副本及附属组件,保留本地源归档文件 |
这一区别也直接决定了组件管理行为:
- 目录链接的内容由源 SDK 目录的所有者自行维护,
cjv的组件命令(cjv component)不能修改它。 - 归档或 URL 安装位于
cjv受管目录中,因此既可以自动安装随包附带的stdx,也可以通过cjv component link stdx挂载本地stdx目录。
归档选项
cjv toolchain import 支持以下归档选项:
| 参数 | 作用 |
|---|---|
--sha256 <hex> | 解包前校验归档内容,值为预期的 64 位十六进制 SHA-256 摘要 |
--replace | 替换已存在的同名自定义工具链 |
--no-stdx | 解包外层打包归档时跳过随包附带的 stdx |
这三个选项仅适用于本地归档或 URL,与已解压目录参数一起使用会报错。如果未提供 --sha256,cjv 不会比对特定内容哈希,但仍会验证归档格式与 SDK 目录布局。
旧版 toolchain link 的归档和 URL 用法仍可执行,并提示迁移到 import;旧替换标志 --force 对应 import --replace。
支持的归档
cjv toolchain import 支持以下两种归档结构:
- 裸 SDK 归档(
.tar.gz或.zip):直接包含一个完整的cangjie/SDK 顶层目录(内含bin/、lib/、tools/、runtime/等内容)。 cangjie-buildCI 外层打包 ZIP:外层 ZIP 内部包含一个 SDK 归档和一个可选的stdx归档:
cangjie-sdk-<sdk_name>-<version>.<tar.gz|zip>
cangjie-stdx-<sdk_name>-<version>.<stdxver>.<tar.gz|zip> # 可选
其中内层 stdx 归档包含平台目录下的 dynamic/ 与 static/。只要外层包中存在随包 stdx 且未指定 --no-stdx,cjv 就会自动一并安装;如果 stdx 安装失败,已成功安装的 SDK 本体仍会保留。
请注意,归档安装要求 SDK 的目标操作系统与当前机器匹配。如果需要跨平台交叉编译,请安装可在当前宿主上运行的交叉编译目标 SDK,而不是直接安装其他操作系统的普通宿主 SDK。
安装完成后,可以使用常规命令查看组件或卸载该自定义工具链:
cjv component list --toolchain archive-sdk
cjv uninstall archive-sdk
交叉编译
宿主工具链运行在主机平台(如 linux-x64)上,默认编译该平台的程序。交叉 SDK 运行在同一主机上,提供面向其他目标平台(如 ohos 或 android)的编译工具和目标库。
cjv 将交叉 SDK 作为宿主工具链的附加安装进行管理:交叉 SDK 的发行版本必须与所依附的宿主工具链完全一致,可用目标列表由分发清单决定。
安装和查询
你可以在安装宿主工具链时通过 --target(-t)参数一并安装交叉目标,也可以稍后通过 cjv target add 为已安装的宿主工具链补装目标:
cjv install sts --target ohos
cjv target list --toolchain sts
cjv target add android --toolchain sts
cjv target list --toolchain sts --installed
cjv target add— 为宿主工具链当前已安装的版本补齐目标 SDK,不会升级宿主本身。cjv target list— 查询分发清单中为该宿主发行版发布的所有可用目标,并标出哪些已安装。cjv target list --installed— 只读取本地安装状态,支持完全离线执行。
指定目标参数(或在 cangjie-sdk.toml 中配置 targets)时,请只写目标后缀,例如 ohos、android 或 ohos-arm32,不要写 linux-x64-ohos 这样的完整宿主-目标平台名。安装命令支持重复传入 --target 或传入逗号分隔列表(如 --target ohos,android)。
使用目标 SDK
默认情况下,<CJV_HOME>/bin 中的 cjc、cjpm 代理命令仍选择宿主 SDK 环境。需要调用交叉 SDK 中的编译工具和目标库时,请在当前 shell 中通过 cjv envsetup 加载目标环境:
eval "$(cjv envsetup +sts --target=ohos)"
cjc --version
在 Windows PowerShell 中执行:
cjv envsetup +sts --target=ohos | Invoke-Expression
请注意,安装目标 SDK 或在 cangjie-sdk.toml 中声明 targets 只负责在磁盘上准备好交叉 SDK 文件,不会自动把普通的 cjpm build 转换为目标平台构建。后续编译参数、系统库(sysroot)和链接器配置由目标 SDK 及项目构建脚本决定;终端会话环境的切换与恢复详见运行命令与配置环境。
组件、更新和移除
每个交叉 SDK 独立管理自己的组件,宿主工具链的组件不会自动充当目标平台的组件。安装好目标 SDK 后,给 cjv component 命令加上 --target <suffix> 即可管理该交叉目标的组件:
cjv component add stdx --toolchain sts --target ohos
cjv component list --toolchain sts --target ohos
cjv target remove ohos --toolchain sts
运行 cjv update 更新跟踪通道(lts、sts、nightly)时,cjv 会先一并准备好新的宿主 SDK、已跟踪目标和已选组件,全部就绪后再统一原子发布。默认情况下,如果新版本缺少所需的目标或组件制品,cjv 会阻止更新并保留原有可用安装(nightly 通道会自动在已发布历史中查找满足全部目标和组件的兼容版本)。如果希望允许跳过并移除未发布的可选目标或组件,请传入 --allow-missing;具体规则见命令参考。
运行 cjv target remove 会移除所选交叉 SDK 及其目标组件,同时保留宿主工具链。交叉 SDK 依附于宿主工具链,不能直接设为全局默认或当前活跃工具链。
配置
cjv 的用户设置默认保存在 ~/.cjv/settings.toml(Windows 上为 %USERPROFILE%\.cjv\settings.toml)。你可以通过命令行选项 --config <path> 或环境变量 CJV_CONFIG_FILE 为当前进程指定另一个设置文件,其中命令行选项优先。请注意,CJV_HOME 和设置中的 home 字段只改变数据目录(toolchains/、cache/ 等)的位置,不会移动 settings.toml 本身。
典型的 settings.toml 文件如下:
version = 1
default_toolchain = "lts"
auto_self_update = "check"
auto_install = true
[overrides]
"/home/me/project-a" = "sts"
设置项
大多数日常设置可以通过 cjv 子命令(cjv default、cjv set、cjv override)查询和修改,高级分发源选项则可以直接编辑 settings.toml:
| 字段 | 默认值或作用 | 修改方式 |
|---|---|---|
version | 设置格式版本号,由 cjv 维护 | 自动写入与迁移 |
default_toolchain | 全局默认工具链 | cjv default <name>;传入 none 可清除 |
auto_self_update | check(仅提示更新);另支持 enable、disable | cjv set auto-self-update <value> |
auto_install | true(自动补齐所选工具链的缺失项) | cjv set auto-install <true|false> |
home | 数据目录路径,默认为 ~/.cjv | cjv set home <path> |
default_host | 默认主机平台,默认自动检测 | cjv set default-host <goos-goarch> |
manifest_url | 默认 LTS/STS 清单地址;nightly 使用同目录的 nightly.json | 编辑 settings.toml |
dist_server | 同时提供 versions.json 和 nightly.json 的根地址 | 编辑 settings.toml |
link_mode | hardlink 或 copy,默认 hardlink | 编辑 settings.toml |
overrides | 目录路径到工具链名称的映射表 | cjv override set / cjv override unset |
自动更新
auto_self_update 仅在执行未指定工具链名称且未带全局 +name 的全量 cjv update 时生效:
check(默认) — 查询是否有新版本cjv并打印提示,但不自动替换。enable— 在更新工具链的同时自动下载并更新cjv本体。disable— 在cjv update时跳过cjv本体的更新检查。
本地开发构建(版本号为 dev)会自动跳过发行检查。无论该项如何配置,你都可以随时运行 cjv self update 手动更新 cjv 本体,或者通过 cjv update --no-self-update 在单次更新中跳过检查。
数据目录与主机平台
运行 cjv set home <path> 时,cjv 会先将相对路径转换为绝对路径再写入设置文件。运行 cjv set home "" 可以显式恢复默认数据目录 ~/.cjv。
default_host 使用 linux-amd64、darwin-arm64 这样的 Go 平台命名格式,这与工具链名称中的 linux-x64 写法不同。
继承与临时覆盖
在配置了系统级设置的机器上,用户设置文件(~/.cjv/settings.toml)会按字段逐项覆盖系统后备配置(Unix 为 /etc/cjv/settings.toml,Windows 为 C:\ProgramData\cjv\settings.toml)。用户文件中未设置的字段会继续继承系统后备配置;而显式写入的 false 和空字符串 "" 都属于明确的用户值,会覆盖后备配置。
运行 cjv set 只会将本次指定的字段写入用户文件,不会把其他继承自系统后备配置的值一并写入。要恢复某个字段对系统后备配置的继承,只需从用户 settings.toml 中删除该字段即可。
各路径、分发源与临时覆盖的优先级规则如下:
- 数据目录优先级:
CJV_HOME环境变量 > 合并设置中的home>~/.cjv。 - 分发源优先级:
CJV_DIST_SERVER环境变量 > 合并设置中的dist_server>manifest_url。环境变量属于临时覆盖,不会因运行cjv set而被持久化到文件中。 - 自定义设置文件(
--config):--config <path>(或CJV_CONFIG_FILE)只替换用户设置文件;系统后备配置、项目工具链文件和环境变量仍然正常生效。 - 单次自动补装覆盖:
--no-auto-install仅在本次命令调用中关闭自动补装;CJV_AUTO_INSTALL=0或1临时覆盖auto_install。这些选项不会写入设置文件,并会传递给通过cjv启动的子进程。
设置文件中的未知键会打印警告;无法解析的语法错误和高于当前支持范围的格式版本号(version)会报错退出。
数据布局
cjv 将所有已安装的工具链、组件、缓存和历史快照统一组织在 <CJV_HOME> 下:
<CJV_HOME>/
bin/ # cjv 与 SDK 代理命令入口(cjc、cjpm 等)
toolchains/<tc>/ # 已安装的宿主 SDK 与交叉编译目标 SDK
stdx/<tc>/ # dynamic/ 与 static/ 扩展库
docs/<tc>/main/ # 主体离线文档
docs/<tc>/stdx/ # 扩展库(stdx)离线文档
downloads/ # 安装暂存与可断点续传的部分下载文件
cache/ # 缓存的版本清单与已验证的归档
history/<tc>/ # 跟踪通道更新前保存的完整组快照
设置文件只有在使用默认数据目录(~/.cjv)时才与上述目录位于同一处。运行 cjv show home 可以随时查看当前实际生效的数据目录及其配置来源。
下载缓存
带有 SHA-256 校验和的下载如果因网络故障失败或中断,会在 downloads/ 中保留可续传的部分文件,下次继续下载完成后校验整个归档。成功的操作会自动清理本次使用的暂存下载;当不带参数的全量 cjv update 全部成功时,还会顺带清理 downloads/ 中残留的历史下载文件。
与此同时,cache/ 目录独立保留版本清单和带 SHA-256 的已验证归档,在成功安装后仍可复用。归档按来源 URL 和 SHA-256 摘要索引,每次复用前都会重新校验摘要(没有校验和的归档不会进入可复用缓存)。
传入 --offline 或设置 CJV_OFFLINE=1 会禁止 cjv 发起任何网络请求,仅使用本地安装和 cache/ 缓存。缓存的清单以下载时的内容为准,不保证包含上游最新发布的版本;如果所需的清单或归档不在缓存中,离线命令会直接报错。
可以使用 cjv cache 子命令管理可复用缓存:
cjv cache dir— 查看缓存目录路径。cjv cache list— 查看当前缓存的清单与归档列表。cjv cache prune --max-age 720h— 删除超过指定时长的缓存条目。cjv cache clean— 清空全部可复用缓存。
清理缓存绝不会删除任何已安装的 SDK。更多 CI 缓存用法见自动化与 JSON 接口。
SDK 文件复用
默认的 link_mode = "hardlink" 会对具有相同发行版、平台和 SHA-256 摘要的 SDK 安装尝试通过硬链接复用内容相同的普通文件。安装元数据和组件目录保持独立;如果底层文件系统不支持硬链接,会自动回退并保留复制文件。
由于硬链接共享同一份底层文件内容,手动原地编辑 <CJV_HOME>/toolchains/ 中的某份 SDK 文件可能会同时影响其他共享该文件的安装。如果需要完全独立的副本以便原地修改文件,请在 settings.toml 中设置 link_mode = "copy"(它只影响后续新安装,不会拆开已有的硬链接)。cjv update 更新工具链时始终通过替换整个目录树发布,不会原地改写共享文件。
自动化与 JSON 接口
本页说明在 CI、构建脚本和编辑器集成中使用 cjv 的方法,包括版本固定与校验、配置隔离、离线缓存、只读诊断、更新回退和 --json 输出。
固定项目版本
在项目目录中运行 cjv pin lts,会将解析后的完整发行版名称(例如 lts-1.0.5)写入当前目录的 cangjie-sdk.toml,同时保留文件中原有的 components、targets 和其他自定义键值(注释和排版会重新生成)。省略名称直接运行 cjv pin 时,会固定当前激活的工具链选择;如果本机已安装对应的跟踪通道,cjv pin 会优先使用本机已安装的发行版,不会触发下载。
pin 只写项目配置,不创建固定版本安装。lts 与 lts-1.0.5 是独立的安装身份:如果只装过 lts,固定后首次运行工具时仍会按 auto_install 设置安装 lts-1.0.5,也可以提前运行 cjv install lts-1.0.5。之后更新或卸载 lts 不会影响项目固定的 1.0.5。默认的 link_mode = "hardlink" 会在发行版、平台、校验和及文件内容匹配时复用普通 SDK 文件,安装元数据和组件仍然独立。
将生成的 cangjie-sdk.toml 提交到版本控制,即可让所有项目成员和 CI 选择完全相同的 SDK 版本:
cjv pin lts
cjv pin --check
cjv pin --check 检查当前目录的 cangjie-sdk.toml 是否固定了具体发行版,不修改文件也不发起网络请求。制品校验和来自分发清单或上游校验和文件,不保存在项目文件中;校验和的可用性见内部分发源。
配置与网络
隔离 CI 目录与设置文件
在 CI 任务中,通常建议为作业指定独立的数据目录和用户设置文件,避免读取或污染构建机宿主的主目录:
export CJV_HOME="$PWD/.cjv-data"
export CJV_CONFIG_FILE="$PWD/ci-settings.toml"
cjv install lts
cjv --offline --no-auto-install exec cjc --version
CJV_HOME 必须为绝对路径。请注意,--config 和 CJV_CONFIG_FILE 只替换用户设置文件,系统后备配置、项目选择与其他环境变量仍然生效;如果需要同时隔离或覆盖系统后备配置,请另行设置 CJV_FALLBACK_SETTINGS。
离线缓存与网络控制标志
要在离线环境中使用 --offline(或 CJV_OFFLINE=1)执行安装,需要事先在相同分发源配置下下载好对应的版本清单、SDK 归档和组件归档。联网安装成功后,cjv 会将已验证 SHA-256 的归档保留在 <CJV_HOME>/cache/ 中(无校验和的归档不会保留在可复用缓存中)。你可以通过 cjv cache list --json 检查缓存内容,并将填充好的 cache/ 目录与项目工具链文件一起提供给离线环境。
如果缓存目录中存在损坏记录、孤立归档或未完成的临时文件,cjv cache list --json 会通过可选的 problem 字段标出问题条目,同时正常列出其余有效条目。运行 cjv cache clean 可以清理这些由 cjv 管理的缓存文件,cjv cache prune --max-age <duration> 则按年龄筛选清理。如果联网查询成功但无法写入可选缓存,cjv 会向 stderr 发出警告,查询结果本身仍可正常使用。
--no-auto-install— 禁止代理、run、exec和默认选择操作隐式补装;显式cjv install仍正常执行。查询与envsetup本身不会自动安装。--offline— 约束cjv自身的网络请求,但不会限制子进程(通过run、exec或代理命令启动的程序)自身的联网行为。
检查与修复
在自动化脚本或故障排查中,可以使用以下命令执行只读诊断、更新预演或重装修复:
cjv doctor --json
cjv update --dry-run --json
cjv install lts --reinstall
cjv doctor— 只读检查设置文件、当前选中的 SDK、<CJV_HOME>/bin代理入口、安装记录以及关键 SDK 文件是否存在,并在发现问题时给出具体修复建议和返回非零退出码(1)。它不会对整个 SDK 逐文件计算哈希摘要。cjv update --dry-run— 解析兼容版本、阻塞原因和全量更新涉及的本体检查/更新策略,不下载归档、不修改安装或刷新缓存。cjv install <name> --reinstall— 重装同名 SDK 的当前发行版并保留组件和目标。普通install保留已有发行版,update推进通道;--allow-missing允许跳过并移除不可用附加项,旧--force仍可兼容使用。
更新历史与回退
当跟踪通道(lts、sts、nightly)的宿主 SDK 或既有交叉目标更新到不同的发行版或摘要时,cjv 会在 <CJV_HOME>/history/ 下保存更新前的完整工具链组快照(包含宿主 SDK、跟踪目标、离线文档和 stdx)。
每个跟踪通道默认自动保留最近 2 份快照。首次安装、同一发行版的 --reinstall 修复,以及单独补装目标或组件不会生成快照。固定版本安装(如 lts-1.0.5)独立保留,不参与通道更新历史。
cjv toolchain history list lts
cjv toolchain rollback lts
cjv toolchain history prune lts --keep 1
cjv toolchain rollback <channel> [snapshot]— 省略快照 ID 时默认选择最新一份快照,也可传入<snapshot>ID 指定恢复某份历史记录。回退前会在本地完整校验整组快照内容,并将回退前的当前组保存为快照,以便再次撤销回退。cjv toolchain history prune [channel] [--keep N]— 清理历史快照。由于每份快照都是独立文件副本(已链接组件的目标内容也会复制保存),会占用额外磁盘空间,且cjv cache clean不会删除历史快照。运行history prune --keep 0可清空历史并保留当前安装。--keep只控制当次清理操作,不改变后续更新时默认自动保留 2 份快照的规则。历史记录由cjv内部维护,请勿直接手动修改<CJV_HOME>/history/中的文件。
损坏快照的处理规则
cjv toolchain history 在 snapshots 数组中保留可读快照记录,并通过可选的 invalid_snapshots 数组报告损坏记录及其原因。
当 history prune 使用非零 --keep 参数时,cjv 会保留指定数量的可读快照,并留下损坏记录供排查;传入 --keep 0 则会一并清理损坏记录。如果最新的一份快照已损坏,省略快照 ID 的 cjv toolchain rollback <channel> 会要求你显式指定一个有效的 <snapshot> ID,而不会静默退到更早的版本。任何被选中的快照在恢复前都必须通过完整内容校验。
JSON 兼容规则
支持 --json 的命令输出单个结构化文档,日志和警告写入 stderr。run、exec、init 和 completion 不支持 JSON:执行入口保留子进程输出,初始化使用交互流程,补全直接输出 shell 脚本。
裸 cjv --json 与 cjv show --json 返回同一状态结构。安装列表条目包含 name、实际发行版 release 和类型 kind(tracking、pinned、custom)。set --json 返回 key、value、changed;未改变设置时也返回 changed: false。override list --json 的 overrides 始终是数组,set 返回目录与工具链,unset 返回已移除目录数组。SDK 和本体卸载在非交互或 JSON 模式下均需显式 --yes。
迁移旧版裸命令 JSON 客户端时,请将原 active 字符串和 installed 名称数组调整为 show 状态结构:active 是包含名称、来源和安装状态的对象,安装列表位于 installed.toolchains。原 show --json 结构保持不变。
编写解析 --json 输出的客户端时,请遵循以下兼容约定:
- 按命令定义成功字段:成功对象的字段按各命令独立定义;客户端应忽略未知字段和不依赖的枚举值。
- 带
schema_version的对象:在同一schema_version版本内保留现有字段的含义和类型。新增可选字段不改变版本号;不兼容变更必须递增schema_version。 - 无版本号的既有命令:保留原有输出结构,请勿假设其与其他命令拥有相同的顶层字段。
- 集合与可选字段:必选集合始终使用数组(空集合为
[]);标为可选的字段可以缺省或为null,消费方应按具体命令兼容处理。 - 机器可读错误处理:自动化脚本应使用进程退出码和错误
code判断结果,不要匹配可能随语言变化的message文本。
例如,空缓存时 cjv cache list --json 的输出为:
{"schema_version":1,"path":"/home/user/.cjv/cache","entries":[]}
下面的 JSON Schema 描述了 cjv cache list --json 的稳定字段(允许后续新增可选字段):
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["schema_version", "path", "entries"],
"properties": {
"schema_version": {"const": 1},
"path": {"type": "string"},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": ["key", "kind", "url", "size", "updated"],
"properties": {
"key": {"type": "string"},
"kind": {"type": "string", "examples": ["metadata", "artifact"]},
"url": {"type": "string"},
"sha256": {"type": "string"},
"size": {"type": "integer", "minimum": 0},
"updated": {"type": "string", "format": "date-time"}
}
}
}
}
}
错误对象与自动补装失败原因
命令执行失败时,stdout 返回 {"error":{"code":"...","message":"...","details":{}}},且进程退出码非零。后续版本可能新增错误码,客户端应保留未知错误码的处理分支;details 内的字段取决于具体的错误码。
cjv doctor --json 是特殊情况:当发现诊断问题时,它仍返回包含 checks 的正常诊断报告对象,将 ok 设为 false 并以退出码 1 结束,不会外包一层 error 对象。
当自动补装失败时,顶层错误码仍保持为 TOOLCHAIN_NOT_INSTALLED 或 COMPONENT_NOT_INSTALLED,而 details.cause 保留底层实际失败的 code、message 和 details:
OFFLINE_CACHE_MISS—--offline模式下所需的版本清单或归档不在缓存中。CHECKSUM_MISMATCH— 下载或缓存的归档未通过 SHA-256 校验。HTTP_ERROR与NETWORK_ERROR— 分别表示 HTTP 响应状态码异常和底层网络传输错误。CANCELED或DEADLINE_EXCEEDED— 表示操作被信号取消或下载超时。
当关闭了自动补装(--no-auto-install、CJV_AUTO_INSTALL=0 或 auto_install = false)时,缺失安装错误没有 details.cause,因为并未尝试执行自动安装。
环境变量
在启动 cjv 前设置环境变量,可以对当前进程及其子进程的配置进行临时覆盖,而不会修改磁盘上的设置文件:
CJV_LOG=debug cjv show active
在 Windows PowerShell 中:
$env:CJV_LOG = "debug"
cjv show active
变量速查表
| 变量 | 默认值 | 作用 |
|---|---|---|
CJV_HOME | ~/.cjv,或设置中的 home | 数据目录(必须为绝对路径);不改变用户设置文件位置 |
CJV_CONFIG_FILE | ~/.cjv/settings.toml | 用户设置文件(--config 优先);保留系统后备配置和项目选择 |
CJV_FALLBACK_SETTINGS | 系统配置路径 | 指定自定义的系统后备设置文件 |
CJV_TOOLCHAIN | 无 | 指定工具链名或 SDK 绝对路径;优先于目录覆盖、项目文件和默认设置 |
CJV_AUTO_INSTALL | 设置中的 auto_install | 0 禁止、1 允许自动补装;不写入设置文件 |
CJV_OFFLINE | 无 | 恰好为 1 时禁止 cjv 发起网络请求,允许读取本地安装与缓存 |
CJV_DIST_SERVER | 无 | 覆盖工具链分发根地址 |
CJV_ALLOW_INSECURE_MANIFEST | 无 | 为 1 时允许非回环主机通过明文 http:// 提供清单 |
CJV_MAX_RETRIES | 3 | 下载失败后的最大重试次数(非负整数) |
CJV_DOWNLOAD_TIMEOUT | 180 | HTTP 下载超时秒数(正整数) |
CJV_NO_PATH_SETUP | 无 | 恰好为 1 时跳过自动 PATH 配置 |
CJV_LOG | warn | 输出到 stderr 的日志级别:debug、info、warn、error(未知值回退为 warn) |
CJV_LANG | 系统区域设置 | 覆盖 CLI 界面语言,如 zh、en、ja |
详细行为说明
- 路径与配置文件隔离(
CJV_HOME、CJV_CONFIG_FILE、CJV_FALLBACK_SETTINGS) —CJV_HOME指定工具链、组件、缓存和历史快照的数据目录,必须为绝对路径。它不会移动用户的settings.toml。隔离 CI 用户设置时,还需设置CJV_CONFIG_FILE或传入--config <path>。继承与优先级规则见配置。 - 工具链选择与自动补装(
CJV_TOOLCHAIN、CJV_AUTO_INSTALL) — 设置CJV_TOOLCHAIN会覆盖本机目录覆盖、cangjie-sdk.toml和全局默认工具链(仅次于命令行显式+name或--toolchain)。CJV_AUTO_INSTALL=0或1用于在当前进程树中临时关闭或开启自动补装。 - 网络、重试与 HTTPS 限制(
CJV_OFFLINE、CJV_DIST_SERVER、CJV_MAX_RETRIES、CJV_DOWNLOAD_TIMEOUT、CJV_ALLOW_INSECURE_MANIFEST) — 如果CJV_MAX_RETRIES或CJV_DOWNLOAD_TIMEOUT设置了非法值,会自动回退到默认值(3次和180秒)。由于版本清单同时提供制品 URL 与 SHA-256 校验和,默认强制要求使用https://;本地回环测试服务器(localhost、127.0.0.1、::1)不受该限制,在测试内网明文源时可设置CJV_ALLOW_INSECURE_MANIFEST=1。 - 注入 SDK 运行环境的变量(
CANGJIE_HOME、CANGJIE_STDX_PATH_*) — 安装stdx组件后,cjv会为所选 SDK 的运行环境自动注入CANGJIE_STDX_PATH_DYNAMIC和CANGJIE_STDX_PATH_STATIC,分别指向组件的dynamic/与static/目录,通常无需手动设置。详见运行命令与配置环境。 - 网络代理与安装脚本变量(
HTTPS_PROXY、CJV_VERSION、CJV_UPDATE_ROOT) — HTTP(S) 和 SOCKS5 代理变量见网络代理。两个安装脚本(install.sh与install.ps1)会读取CJV_VERSION来选择cjv本体的发布标签(命令行--version/-Version优先)。CJV_UPDATE_ROOT(以及CJV_GITHUB_ROOT、CJV_GITCODE_ROOT)用于选择cjv本体的首次下载地址,优先于版本选择,但它不会覆盖已安装cjv的自更新源。具体用法见安装 cjv。
网络代理
cjv 通过标准代理环境变量配置网络访问。代理设置适用于版本清单、SDK 归档、组件和自更新请求。
在终端中配置代理
请在启动 cjv 前设置对应的环境变量:
- 在 Linux、macOS 或鸿蒙 HiShell(Bash 或 Zsh)中:
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,artifacts.corp.example
cjv install lts
- 在 Windows PowerShell 中:
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,artifacts.corp.example"
cjv install lts
- 在 Windows 命令提示符(
cmd.exe) 中:
set HTTPS_PROXY=http://proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,artifacts.corp.example
cjv install lts
支持的代理变量与协议
| 变量 | 用途 |
|---|---|
HTTPS_PROXY / https_proxy | https:// 请求使用的代理服务器 |
HTTP_PROXY / http_proxy | http:// 请求使用的代理服务器 |
NO_PROXY / no_proxy | 逗号分隔的直连主机名、域名或 IP 列表 |
代理地址支持 http://、https:// 和 socks5:// 协议。
注意:
cjv不读取ALL_PROXY/all_proxy。如果你的终端环境只配置了ALL_PROXY,请在启动cjv前改为显式设置上表中的HTTPS_PROXY或HTTP_PROXY。
企业 TLS 证书与慢速连接
- 企业私有 CA 证书 — 当企业 TLS 代理使用自签名或私有 CA 拦截 HTTPS 流量时,请将该 CA 根证书加入操作系统的受信任证书存储区。
- 内网镜像直连 — 当内网同时部署了内部分发源并且需要直连访问时,请将内部分发源的主机名加入
NO_PROXY。 - 调整重试与超时 — 在慢速或高延迟连接下,可以调大
CJV_MAX_RETRIES和CJV_DOWNLOAD_TIMEOUT,详见环境变量。
企业与离线部署
企业可以根据开发终端和 CI 构建机的网络边界策略,选择最合适的部署方案:
- 允许通过代理访问上游 — 配置网络代理与企业根证书即可。
- 仅允许访问企业内网 — 将经批准的 SDK、组件和版本清单放入内部分发源,并将
dist_server指向该内网地址。 - 完全离线(物理隔离) — 使用
toolchain import导入归档,或通过toolchain link引用已有目录。
请注意,dist_server 仅控制仓颉 SDK 和组件的分发,不控制 cjv 本体升级,也不配置 cjpm 的项目依赖仓库;后两者需要分别安排。
部署客户端
可以通过企业软件分发系统直接安装 cjv,或者在内网托管安装脚本与发布归档:
$env:CJV_UPDATE_ROOT = "https://artifacts.corp.example/cjv/releases/latest/download"
& ([scriptblock]::Create((irm https://artifacts.corp.example/cjv/install.ps1))) `
-Yes -DefaultToolchain none -NoModifyPath
CJV_UPDATE_ROOT 只选择安装脚本下载 cjv 本体的地址,该目录需要提供对应平台的归档和 checksums.txt。-NoModifyPath(Unix 为 --no-modify-path)适合由终端管理系统统一设置 PATH 的环境。
在自动化部署中,建议按“先安装 cjv、再下发系统后备设置、最后安装 SDK”三步分别执行,以便独立检查每一步的退出码。
系统后备配置
cjv 在读取用户个人的 ~/.cjv/settings.toml 之前,会先查询系统级后备配置文件:
| 系统 | 默认文件 |
|---|---|
| Windows | C:\ProgramData\cjv\settings.toml |
| Linux / macOS | /etc/cjv/settings.toml |
也可以通过 CJV_FALLBACK_SETTINGS 环境变量指定其他文件。典型的系统后备配置如下:
version = 1
dist_server = "https://artifacts.corp.example/cjv/dist"
default_toolchain = "lts-1.0.5"
auto_self_update = "disable"
auto_install = false
请将示例版本替换为企业批准的发行版。关闭自动安装(auto_install = false)后,项目缺少 SDK 或组件时会立即报错,统一由受管部署流程补齐。多用户机器上请为每个用户账户分配独立的 CJV_HOME。
后备设置仅提供默认初始值,用户设置文件仍可逐字段覆盖,环境变量也能在运行时改变分发源(见配置)。如需强制执行来源和版本合规策略,请结合网络 ACL、终端文件权限及软件分发流程共同实施。
安装批准版本
在连接内部分发源的受管终端上,安装并验证批准版本:
cjv install lts-1.0.5 -c stdx
cjv default lts-1.0.5
cjv which cjc
cjc --version
项目的 cangjie-sdk.toml 应使用同一个完整版本名(lts-1.0.5)。如果使用 nightly,同样应固定完整的 nightly 版本号,并在内部分发源中保留该版本及其组件。
完全离线
在无内网 HTTP 服务的完全离线终端上,使用本地归档或目录完成注册:
cjv toolchain import corp-sdk ./cangjie-sdk.zip --sha256 <approved-sha256>
cjv component link stdx /opt/corp/cangjie-stdx --toolchain corp-sdk
cjv default corp-sdk
如果有批准的 SHA-256 哈希,请给归档安装传入 --sha256 <approved-sha256>。你也可以直接链接已有的只读 SDK 目录(cjv toolchain link corp-sdk /opt/corp/sdk),但这种方式下组件由外部 SDK 所有者直接维护。项目文件使用 corp-sdk 这样的自定义名称,项目构建依赖也需预先准备。
支持的归档格式见自定义 SDK。docs 和 stdx-docs 不支持本地目录链接,可在断网前通过分发源安装(或随预置 CJV_HOME 一起下发)。
发布和验收
更新内部分发源时,请务必先上传并校验所有制品归档,再原子替换清单文件并推进 latest。nightly 的 latest 位于 nightly.json 顶层,客户端可能根据组件和交叉目标需求在清单中选择历史兼容版本。请保留被项目固定的所有历史版本。
验收时请分别使用普通研发用户账户和实际 CI 服务账户检查以下事项:
- LTS/STS 和 nightly 分别读取
versions.json、nightly.json,且所有制品 URL 均在批准的内网范围内。 - 批准版本及组件能正常安装,
cjv which cjc和cjc --version指向预期 SDK。 - 断网后,已准备好工具链及依赖的项目仍能正常离线构建。
- 企业私有 CA、代理和
NO_PROXY正常生效,缺失项在关闭自动补装时按预期报错。
关闭自动自更新(auto_self_update = "disable")后,由企业软件分发系统统一升级 cjv 本体。显式执行 cjv self update 仍会使用编译时注入的上游更新源,网络边界限制应与企业部署策略保持一致。
内部分发源
配置中的 dist_server 字段(或 CJV_DIST_SERVER 环境变量)指定工具链制品与版本清单的根地址。假设配置为:
dist_server = "https://artifacts.corp.example/cjv/dist"
cjv 会按通道在该根地址下读取两个独立的清单文件:
https://artifacts.corp.example/cjv/dist/versions.json # LTS / STS
https://artifacts.corp.example/cjv/dist/nightly.json # nightly
- LTS 和 STS 操作只读取
versions.json;nightly 操作只读取nightly.json。 cjv check与cjv update仅根据本机已安装的通道按需加载对应文件。- 清单中相对路径形式的 SDK 与组件
url以分发根(dist_server)为基准解析,绝对 URL 则完全按清单中的原值请求。
分发源优先级依次为:CJV_DIST_SERVER > 合并设置中的 dist_server > manifest_url。CI 流水线可以使用 CJV_DIST_SERVER 环境变量临时选择测试分发源。
文件布局
建议在企业制品库中按以下结构组织工具链分发目录(dist/)与 cjv 本体发布目录(releases/):
企业制品库
└── cjv/
├── dist/ # dist_server 指向这里
│ ├── versions.json # LTS / STS 及其组件
│ ├── nightly.json # nightly 及其组件
│ ├── sdk/
│ ├── components/
│ └── nightly/
└── releases/ # cjv 本体归档和 checksums.txt
分发端点只需通过 HTTPS GET 向受管终端提供机器可读的只读访问;网络白名单、设备证书或企业反向代理均可用于实施访问控制。
versions.json
versions.json 的顶层是 channels 对象,包含 lts 与 sts 两个通道:
{
"channels": {
"lts": {
"latest": "1.0.5",
"versions": {
"1.0.5": {
"linux-x64": {
"name": "cangjie-sdk-linux-x64-1.0.5.tar.gz",
"url": "sdk/cangjie-sdk-linux-x64-1.0.5.tar.gz",
"sha256": "<64 位十六进制 SHA-256>"
}
}
}
},
"sts": {
"latest": "1.1.0",
"versions": {
"1.1.0": {
"linux-x64": {
"name": "cangjie-sdk-linux-x64-1.1.0.tar.gz",
"url": "sdk/cangjie-sdk-linux-x64-1.1.0.tar.gz",
"sha256": "<64 位十六进制 SHA-256>"
}
}
}
}
}
}
nightly.json
nightly.json 直接在顶层表示一个通道,包含 latest、versions 和可选的 components(请不要将 nightly 内容包裹在 channels.nightly 下):
{
"latest": "1.2.0-alpha.20260822010101",
"versions": {
"1.2.0-alpha.20260822010101": {
"linux-x64": {
"name": "cangjie-sdk-linux-x64-1.2.0-alpha.20260822010101.tar.gz",
"url": "nightly/20260822/cangjie-sdk-linux-x64-1.2.0-alpha.20260822010101.tar.gz",
"sha256": "<64 位十六进制 SHA-256>"
}
}
},
"components": {
"1.2.0-alpha.20260822010101": {
"docs": {
"name": "cangjie-docs-html-1.2.0-alpha.20260822010101.tar.gz",
"url": "nightly/20260822/cangjie-docs-html-1.2.0-alpha.20260822010101.tar.gz",
"sha256": "<64 位十六进制 SHA-256>"
}
}
}
}
每个 SDK 条目包含 name、url 和 sha256。上游 nightly 的 sha256 在刚发布时可能暂时为空,此时 cjv 会自动请求 <url>.sha256;而在企业内网镜像中,建议直接计算并填入完整的 64 位校验和。组件条目同样支持可选的 sha256 字段,建议一并填写以便客户端校验完整性并写入可复用离线缓存。
versions 中的版本键决定工具链名称,url 则精确定位下载归档。nightly 首次安装或显式更新以 latest 为起点,并根据所需的交叉目标和组件在清单历史中查找兼容版本(默认不降级);固定完整版本名时则直接选用对应版本。
组件格式
每个通道对象的 components 字段按版本号索引。docs 与 stdx-docs 在每个版本下各对应一个归档对象;stdx 则进一步按组件平台标识索引:
{
"components": {
"1.0.5": {
"stdx": {
"linux-x64": {
"name": "stdx-linux-x64.tar.gz",
"url": "components/stdx-linux-x64.tar.gz",
"sha256": "<64 位十六进制 SHA-256>"
}
},
"docs": { "name": "docs.tar.gz", "url": "components/docs.tar.gz" },
"stdx-docs": { "name": "stdx-docs.tar.gz", "url": "components/stdx-docs.tar.gz" }
}
}
}
以上是通道对象的片段,实际文件中需与同一通道的 latest、versions 合并。交叉编译 SDK 位于 versions[版本][平台] 下(例如 linux-x64-ohos),其对应的 stdx 则使用组件平台标识(例如 ohos-aarch64)。
发布顺序
向内部分发源发布新版本时,请按以下顺序操作,确保客户端不会读到指向缺失文件的清单:
- 镜像并校验所有批准版本的宿主 SDK、交叉 SDK 与组件归档。
- 计算每个 SDK 的 SHA-256;组件归档也建议计算并写入清单。
- 先上传发布所有归档文件,并用普通终端账户验证
HTTPS GET可正常访问。 - 分别生成
versions.json与nightly.json,并保留项目工具链文件仍在引用的全部精确版本。 - 原子替换对应的清单文件;确认该版本的所有制品齐全后再推进清单中的
latest。
客户端验收检查项见企业与离线部署。
命令参考
cjv 内置了完整的命令行帮助系统;你可以随时运行 cjv help 或 cjv <command> --help 查看本机已安装版本的详细参数。版本名称格式见工具链与版本,工具链选择顺序见项目工具链。
全局选项
| 选项 | 作用 |
|---|---|
--json | 将结构化 JSON 写入 stdout;run、exec、init、completion 不支持 |
--quiet、-q | 隐藏进度输出,参数位置不改变含义;单列组件名称使用 component list --names-only |
--verbose | 未设置 CJV_LOG 时在 stderr 启用 debug 日志,与 --quiet 互斥 |
--offline | 禁止 cjv 联网,只使用本地安装和可复用缓存 |
--config <path> | 选择用户设置文件,仍保留系统后备配置和项目选择 |
--no-auto-install | 仅在本次调用中禁止自动补装缺失项 |
--help、-h | 显示命令帮助 |
--version、-v | 显示 cjv 版本号 |
+name | 放在子命令前,为支持选择工具链的命令显式指定 SDK |
子命令的显式 --toolchain 参数优先于前置的全局 +name。exec 和 envsetup 也接受跟在子命令名称后的 +name。子进程参数由 run、exec 原样透传,退出码也会完整保留。
安装、更新与卸载
install
cjv install [toolchain]... [-t target]... [-c component]... [--allow-missing] [--allow-downgrade] [--reinstall]
install 确保所选工具链存在,默认保留已安装发行版,只补齐新增目标或组件;升级已有通道请运行 update。省略名称时使用当前选择,多个名称按顺序处理。-t(--target)和 -c(--component)可重复传入或使用逗号分隔:
cjv install lts sts
cjv install nightly -c stdx,docs
安装与更新策略
| 策略 | 行为 |
|---|---|
| 默认 | 保留所需组件和交叉目标;缺少制品时阻止更新,其中 nightly 可在已发布历史中查找兼容版本 |
--allow-missing | 允许跳过并移除不可用的可选组件或目标,不会重装未变化的 SDK |
默认 install | 保留已有宿主发行版,只补齐新增目标或组件 |
install --reinstall | 重新安装当前已有的发行版并保留组件和目标,用于修复损坏的 SDK |
--allow-downgrade | 允许 nightly 安装或更新选择更旧的兼容 nightly 构建 |
没有新增组件或交叉目标需求时,对已安装工具链运行 cjv install 可完全离线完成。--force 是 --allow-missing 的已弃用兼容标志;install --no-update 仍可使用,但保留版本已是默认行为。--allow-downgrade 影响需要解析发行版的操作,不会让普通 install 推进或降级已有通道。
update
cjv update [toolchain]... [--allow-missing] [--allow-downgrade] [--no-self-update] [--dry-run]
update 指定名称时只处理列出的工具链;省略名称时优先使用全局 +name,否则更新所有已安装的跟踪通道(lts、sts、nightly)。固定版本保持不变,自定义工具链没有官方更新源。只有不带名称且不带 +name 的全量更新才会按 auto_self_update 检查或更新 cjv 本体;传入 --no-self-update 可跳过该检查。
通道升级会先在暂存区准备好宿主 SDK、已跟踪目标和组件,全部准备完成后再原子替换安装;若失败则保留或恢复原安装,固定版本独立保留。
cjv update lts
cjv update --no-self-update
第一条命令只更新 lts;第二条更新所有已跟踪通道,并跳过 cjv 本体的更新检查。
--dry-run 只解析更新计划,报告最新发行版、实际兼容版本与阻塞原因;全量更新还按当前策略报告 cjv 本体的检查或更新计划。它不下载归档、不修改安装也不写入缓存,配合 --json 可供 CI 使用。显式指定未安装工具链的 update 仍会安装该工具链。
uninstall
cjv uninstall <toolchain>... [-y]
uninstall 会清理指定 SDK、附属交叉 SDK、组件、离线文档和引用它的目录覆盖。移除当前默认工具链时,会改选其他已安装宿主或清空默认选择。交互终端请求确认;非交互输入或 --json 模式必须显式传入 -y(--yes)。输出格式不代表确认删除。toolchain uninstall 保留为隐藏兼容入口。
check
cjv check
check 查询已安装 SDK 和 cjv 本体的可用更新,不执行安装或写入缓存;前置 +name 将 SDK 查询限制到该工具链。它采用与更新相同的组件和目标兼容规则。dev 构建跳过本体版本比较。doctor 检查本机状态,pin --check 只验证项目是否固定具体发行版,二者不查询可用更新。
更新历史与回退
cjv toolchain history list [toolchain]
cjv toolchain history prune [toolchain] [--keep 2]
cjv toolchain rollback <toolchain> [snapshot]
历史快照整组保存宿主、目标和组件,默认保留最近 2 份。查询或清理省略名称时使用前置 +name,否则处理所有历史组;省略 list 仍作为兼容简写。--keep 0 清空快照并保留安装。回退前会校验快照并保存当前组,以便撤销。详见更新历史与回退。
doctor 与缓存
cjv doctor
cjv cache dir
cjv cache list
cjv cache clean
cjv cache prune [--max-age 720h]
doctor 只读检查配置、代理命令入口及 SDK 完整性,发现问题时返回非零退出码。cache 子命令管理 <CJV_HOME>/cache/ 下已验证 SHA-256 的下载归档和版本清单;清理缓存绝不会删除已安装 SDK。JSON 约定和离线用法见自动化与 JSON 接口。
查询工具链
| 命令 | 作用 |
|---|---|
cjv、cjv show | 显示同一份当前工具链、默认主机和安装报告,JSON 结构相同 |
cjv show active | 显示当前激活工具链及其选择来源 |
cjv toolchain list | 列出宿主和附加目标,显示实际发行版以及跟踪、固定或自定义类型 |
cjv show home | 显示实际生效的数据目录及其配置来源 |
cjv which [command] [--toolchain <tc>] | 显示 SDK 工具路径;省略 [command] 时返回 SDK 根目录 |
查询命令不会自动安装缺失的 SDK 或组件。show installed 是 toolchain list 的隐藏兼容入口。
toolchain list-remote
cjv toolchain list-remote [--channel all|lts|sts|nightly] [-t suffix] [--all-platforms] [--limit N]
远程列表默认查询所有通道在当前主机平台下的可用版本。--all-platforms 按所有平台分组显示,--limit 0 不限制每组显示的版本数,-t(--target)按交叉目标后缀过滤。
运行命令与配置环境
run
cjv run [--install] <toolchain> <command> [args...]
使用显式工具链运行任意命令,与 exec 一样准备 SDK 和运行时库,并按 auto_install 补装缺失项。--install 显式启用补装,须放在工具链参数前,且与 --no-auto-install 互斥:
cjv run --install sts cjc --version
exec
cjv exec [+toolchain] <command> [args...]
使用当前激活工具链(或 +name 指定工具链)的运行环境启动命令。当编译产物需要链接仓颉运行时库或 stdx 动态库时,推荐这样运行:
cjv exec ./my_binary
cjv exec +nightly ./my_binary
如果被调用的命令名本身以 + 开头,请使用 cjv exec -- +command。run 和 exec 都会原样透传子进程参数并保留退出码。
envsetup
cjv envsetup [+toolchain] [--target=SUFFIX] [--shell=TYPE]
输出用于配置当前 shell 的脚本,支持 bash、fish、powershell 和 cmd。--target 要求交叉 SDK 已安装;--json 模式返回结构化环境数据。
输出脚本需在当前 shell 中求值执行(如 eval "$(cjv envsetup)")才会生效。envsetup 只读取已安装 SDK,并验证项目需求;缺失时提示显式安装,不会自动补装。各 shell 写法与恢复项目代理选择的方法见运行命令与配置环境。
自定义工具链
cjv toolchain link <name> <directory>
cjv toolchain import <name> <archive|url> [--sha256 <hash>] [--replace] [--no-stdx]
link 引用已有目录,源目录内容由其所有者维护;import 将本地归档或 HTTP(S) URL 解包为受管安装。--sha256、--replace、--no-stdx 分别校验摘要、替换同名安装、跳过随包 stdx。旧 link 的归档和 URL 用法保留兼容并提示迁移,旧替换标志仍为 --force。详见自定义 SDK。
交叉编译目标
cjv target list [--toolchain <tc>] [--installed]
cjv target add <suffix>... [--toolchain <tc>]
cjv target remove <suffix>... [--toolchain <tc>]
target add 保留宿主当前版本并补装目标;target remove 移除交叉 SDK 及其组件并保留宿主安装。target list --installed 支持离线查询。详见交叉编译。
组件
cjv component add <name>... [--toolchain <tc>] [--target <suffix>] [--reinstall]
cjv component link <name> <path> [--toolchain <tc>] [--target <suffix>] [--replace]
cjv component remove <name>... [--toolchain <tc>] [--target <suffix>]
cjv component list [--toolchain <tc>] [--target <suffix>] [--installed] [--names-only]
组件命令的 --target 只选择已安装的交叉 SDK,不会自动安装该目标 SDK。
组件名支持 stdx、docs、stdx-docs,接受多个参数或逗号分隔。component add --reinstall 重装组件,component link --replace 替换组件;旧 --force 保留为隐藏兼容标志。list --names-only 单列打印名称,-q 始终只关闭进度。只有 stdx 支持目录链接,源目录需有 dynamic/ 和 static/。外部 SDK 目录链接不能通过组件命令修改。详见组件与离线文档。
离线文档
cjv doc [topic] [--path] [--toolchain <tc>]
支持的主题为 std、dev-guide(别名 book)、tools、stdx;省略主题时打开文档首页。--path 和 --json 只返回本地路径,其他情况在默认浏览器中打开文档。cjv docs 是命令别名,使用前需先安装对应文档组件。
选择与设置
pin
cjv pin [toolchain] [--check]
写入当前目录的 cangjie-sdk.toml,固定具体发行版并保留已有的 components 和 targets。--check 只验证项目文件是否固定了具体发行版,不修改文件。详见自动化与 JSON 接口。
default
cjv default [toolchain]
省略参数时显示全局默认选择,传入 none 时清除。选择未安装的官方 SDK 通常会先安装;--no-auto-install 则要求 SDK 已安装。安装或验证失败保留原选择,交叉 SDK 不能设为默认。
override
cjv override set <toolchain> [--path <dir>]
cjv override unset [--path <dir>] [--nonexistent]
cjv override list
目录覆盖默认作用于当前工作目录,--nonexistent 清理已不存在目录的残留记录。覆盖写入所选用户设置文件(默认 ~/.cjv/settings.toml),不随 CJV_HOME 改变。详见项目工具链和配置。
set
cjv set auto-self-update <enable|disable|check>
cjv set auto-install <true|false>
cjv set default-host <goos-goarch>
cjv set home <path>
修改所选用户设置文件(默认 ~/.cjv/settings.toml)。各字段默认值、系统后备继承规则和环境变量覆盖见配置。
初始化与自管理
init
cjv init [-y] [--default-toolchain <name>] [-c component]... [--no-modify-path]
init 安装 cjv 命令入口并配置 PATH。它会查询当前平台的可用通道,按 lts、sts、nightly 的顺序自动选择第一个可用通道。交互式菜单只列出当前平台可用的通道;如果无法确认任何可用通道,初始化会报错退出。
| 选项 | 作用 |
|---|---|
--default-toolchain <name> | 明确指定默认工具链 |
--default-toolchain none | 只安装 cjv 本体,跳过 SDK |
-c、--component | 安装初始 SDK 时一并安装指定组件 |
-y、--yes | 跳过交互确认 |
--no-modify-path | 保留现有 PATH 配置 |
非终端输入会自动采用非交互模式。当初始工具链安装失败时,命令返回非零退出码并保留已安装的 cjv 本体;错误信息中会给出保留组件选项的重试命令和查询兼容版本的命令,两者都使用已安装程序的绝对路径,无需先刷新 PATH 即可执行。
self update / self uninstall
cjv self update
cjv self uninstall [-y]
self update 检查并更新 cjv 本体。self uninstall 删除整个 <CJV_HOME>、所有工具链、组件、缓存和快照,并清理 PATH;非交互输入或 --json 必须显式加 -y,与 SDK 卸载一致。
Shell 补全
cjv completion <bash|zsh|fish|powershell>
输出对应 shell 的命令行补全脚本,加载方法见 cjv completion <shell> --help。
常见问题
为什么选中的 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 校验和,详见内部分发源格式。