Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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_64cjv_linux_amd64.tar.gz
Linux ARM64cjv_linux_arm64.tar.gz
macOS Apple Siliconcjv_darwin_arm64.tar.gz
macOS Intelcjv_darwin_amd64.tar.gz
Windows x86_64cjv_windows_amd64.zip
鸿蒙 x86_64cjv_openharmony_amd64.tar.gz
鸿蒙 ARM64cjv_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 按以下顺序从高到低选择工具链,并采用第一个指定的来源:

  1. 命令行中显式指定的工具链,例如全局 +name 简写(如 cjv +nightly show)或子命令支持的 --toolchain 参数。
  2. CJV_TOOLCHAIN 环境变量。
  3. 从当前工作目录向文件系统根目录逐层向上查找:在每一层目录中,先检查本机目录覆盖,再检查 cangjie-sdk.toml,找到第一个匹配项后立即停止。
  4. 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] 表下:

字段类型说明
channelstring通道名、版本选择器或已注册的自定义工具链名称
pathstring外部 SDK 目录的绝对路径,与 channel 互斥
componentsstring[]需要的附加组件(stdx、docs、stdx-docs),默认为空
targetsstring[]需要的交叉编译 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 支持以下两种归档结构:

  1. 裸 SDK 归档(.tar.gz 或 .zip):直接包含一个完整的 cangjie/ SDK 顶层目录(内含 bin/、lib/、tools/、runtime/ 等内容)。
  2. cangjie-build CI 外层打包 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_updatecheck(仅提示更新);另支持 enable、disablecjv set auto-self-update <value>
auto_installtrue(自动补齐所选工具链的缺失项)cjv set auto-install <true|false>
home数据目录路径,默认为 ~/.cjvcjv 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_modehardlink 或 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_install0 禁止、1 允许自动补装;不写入设置文件
CJV_OFFLINE无恰好为 1 时禁止 cjv 发起网络请求,允许读取本地安装与缓存
CJV_DIST_SERVER无覆盖工具链分发根地址
CJV_ALLOW_INSECURE_MANIFEST无为 1 时允许非回环主机通过明文 http:// 提供清单
CJV_MAX_RETRIES3下载失败后的最大重试次数(非负整数)
CJV_DOWNLOAD_TIMEOUT180HTTP 下载超时秒数(正整数)
CJV_NO_PATH_SETUP无恰好为 1 时跳过自动 PATH 配置
CJV_LOGwarn输出到 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_proxyhttps:// 请求使用的代理服务器
HTTP_PROXY / http_proxyhttp:// 请求使用的代理服务器
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 之前,会先查询系统级后备配置文件:

系统默认文件
WindowsC:\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)。

发布顺序

向内部分发源发布新版本时,请按以下顺序操作,确保客户端不会读到指向缺失文件的清单:

  1. 镜像并校验所有批准版本的宿主 SDK、交叉 SDK 与组件归档。
  2. 计算每个 SDK 的 SHA-256;组件归档也建议计算并写入清单。
  3. 先上传发布所有归档文件,并用普通终端账户验证 HTTPS GET 可正常访问。
  4. 分别生成 versions.json 与 nightly.json,并保留项目工具链文件仍在引用的全部精确版本。
  5. 原子替换对应的清单文件;确认该版本的所有制品齐全后再推进清单中的 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 查看当前选中的工具链及其生效来源,再按以下优先级依次检查:

  1. 命令行显式参数(全局 +name 或 --toolchain)。
  2. CJV_TOOLCHAIN 环境变量。
  3. 当前目录及父目录中的本机目录覆盖(cjv override list)和 cangjie-sdk.toml。cjv 从当前目录逐层向上检查,在同一层目录中目录覆盖优先于项目文件;完整规则见项目工具链。
  4. 全局默认工具链(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 校验和,详见内部分发源格式。