cjv 用户手册

cjv 是仓颉 SDK 的版本管理器，可以在本机安装多套工具链，并为不同项目选择各自需要的版本。配置好命令路径后，cjc、cjpm 等命令会通过 cjv 调用所选 SDK。

开始使用

首次使用请先安装 cjv，然后按快速上手检查工具链、配置项目和运行命令。

安装向导会根据当前平台查询可用通道。cjv 支持的平台与仓颉 SDK 的发布范围可能不同，具体版本可以通过 cjv toolchain list-remote 查询。

配置项目与管理 SDK

工具链与版本说明通道、固定版本和名称格式。在团队项目中，可以提交 cangjie-sdk.toml，统一声明版本、组件和目标 SDK。

扩展库和离线文档见组件，其他目标平台的 SDK 见交叉编译。已有的 SDK 目录或归档也可以注册为自定义工具链。

运行编译产物或配置当前 shell 时，参见运行命令与配置环境。

配置与参考

配置和环境变量说明用户设置与临时覆盖。网络代理适用于需要代理访问上游的环境；内部分发源、受管终端和完全离线安装见企业与离线部署。

查阅具体参数时使用命令参考，排查常见问题时使用常见问题。

安装 cjv

cjv 是单文件程序，不需要预装仓颉 SDK。

安装脚本

Linux / macOS / 鸿蒙 HiShell：

curl -sSf https://cjv.zxilly.dev/install.sh | sh

Windows PowerShell：

irm https://cjv.zxilly.dev/install.ps1 | iex

脚本检测平台、下载并校验 cjv，再运行 cjv init。交互终端会显示向导，非交互输入使用默认选项。自动化安装可以显式跳过确认，或先只安装 cjv：

curl -sSf https://cjv.zxilly.dev/install.sh | sh -s -- -y --default-toolchain none

& ([scriptblock]::Create((irm https://cjv.zxilly.dev/install.ps1))) -Yes -DefaultToolchain none

Unix 脚本将 --mirror 以外的参数传给 cjv init。PowerShell 脚本提供对应的 -Yes、-DefaultToolchain、-NoModifyPath 等参数。

SDK 选择

cjv init 默认查询当前平台的可用通道，按 lts、sts、nightly 的顺序选择。可以用 --default-toolchain <name> 指定工具链，或用 --default-toolchain none 只安装 cjv。

SDK 安装失败时，命令返回非零退出码，已安装的 cjv 会保留。可以按错误信息中的命令重试，或用 cjv toolchain list-remote 查询可用版本。

GitCode 镜像

curl -sSf https://cjv.zxilly.dev/install.sh | sh -s -- --mirror

& ([scriptblock]::Create((irm https://cjv.zxilly.dev/install.ps1))) -Mirror

镜像版使用 GitCode 的默认版本清单和 cjv 自更新源。内部制品库的配置见企业部署。

手动下载

从 GitHub Releases 下载归档，解压后把 cjv 或 cjv.exe 放入 PATH，再运行 cjv init。

GitCode Releases 提供前缀为 cjv-mirror_ 的对应归档。下载页提供的 cjv-init 程序在启动时直接进入安装向导。

从源码安装

安装满足仓库 go.mod 要求的 Go 后执行：

go install github.com/Zxilly/cjv/cmd/cjv@latest
cjv init

Go 将程序放入 GOBIN，未配置时为 $(go env GOPATH)/bin；该目录需要加入 PATH。

PATH 与验证

SDK 代理命令位于 <CJV_HOME>/bin，默认是 ~/.cjv/bin。init 会配置 PATH；跳过初始化而直接安装 SDK 时，首次工具链安装也会尝试配置。Windows 写入用户 PATH，Unix 修改 shell 配置。打开新终端后检查：

cjv --version

自行管理 PATH 时，给 init 传 --no-modify-path，PowerShell 脚本用 -NoModifyPath。CJV_NO_PATH_SETUP=1 也可跳过自动配置。继续阅读快速上手安装工具链。

快速上手

检查安装

如果已经完成安装向导，打开新终端后检查当前工具链：

cjv show
cjc --version

如果找不到 cjc，检查 <CJV_HOME>/bin 是否在 PATH 中，默认路径为 ~/.cjv/bin。命令路径的配置方式见安装说明。

选择默认工具链

如果安装时跳过了 SDK，先查询可用通道，再设置默认工具链。下面以 LTS 为例：

cjv toolchain list-remote --channel lts
cjv default lts
cjc --version

default 会安装缺失的工具链。所选平台没有 LTS SDK 时，可查询 STS 或 nightly，并将命令中的通道替换为可用通道。也可以运行 cjv init，由向导选择可用通道。

默认工具链用于没有项目声明或覆盖设置的目录。运行 cjv show active 可以查看选择及来源。

为项目选择版本

在项目根目录创建 cangjie-sdk.toml：

[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]

这里的版本是示例，请替换为项目需要且分发源提供的版本。在该目录运行 cjpm build 时，cjv 使用文件声明的工具链。默认开启的自动安装会补齐缺失的 SDK 和组件；已有工具链不会因每次运行命令而自动升级。

只想在本机切换某个目录时，可使用目录覆盖：

cjv override set sts
cjv show active
cjv override unset

目录覆盖写入用户设置，项目文件可以提交到版本控制。两者的优先级见项目工具链。

临时使用其他版本

cjv run --install sts cjc --version

run 明确指定工具链，--install 允许安装缺失的版本。要运行自己的编译产物，用 cjv exec ./my_binary 配置该进程的运行时库路径。

查看工具链状态

cjv show active
cjv which cjc
cjv toolchain list

这三条命令分别显示当前工具链及来源、编译器路径和已安装工具链列表。

更新与卸载

cjv check
cjv update

check 只查询 SDK 和 cjv 的可用更新。update 更新已跟踪的通道，固定版本和自定义工具链保留原样。全量更新是否检查或更新 cjv 本身，由 auto_self_update 设置控制。

手动更新 cjv 本身：

cjv self update

移除不再需要的工具链：

cjv uninstall sts

卸载工具链会同时移除它的组件和文档。更多选项见命令参考。

运行命令与配置环境

安装后，<CJV_HOME>/bin 中的 cjc、cjpm 等命令入口会通过 cjv 调用所选 SDK。cjv 按项目工具链的规则选择版本、配置环境并转发参数和退出码。

SDK 工具与自己的程序

cjc --version
cjv run --install sts cjc --version
cjv exec ./my_binary arg1 arg2
cjv exec +nightly ./my_binary

run 明确指定工具链，先查 SDK 工具，再查该环境的 PATH；只有加 --install 才会安装缺失版本。exec 按当前选择或 +name 准备 SDK 环境，适合运行需要仓颉动态库的编译产物。这两个命令只改变子进程环境，并透传标准流和退出码。

如果命令名以 + 开头，用 cjv exec -- +command 避免它被当作工具链选择器。

配置当前 shell

envsetup 输出环境脚本，需要在当前 shell 中执行：

# Bash / Zsh
eval "$(cjv envsetup)"

cjv envsetup | source

cjv envsetup | Invoke-Expression

可以用 cjv envsetup +nightly 指定版本，或用 --shell=bash|fish|powershell|cmd 指定输出格式。省略 --shell 时自动检测，检测失败时提示并回退到 POSIX 格式。cjv --json envsetup 输出结构化环境数据。

设置的环境变量

环境包含 CANGJIE_HOME、SDK 工具路径和运行时库路径。Linux 使用 LD_LIBRARY_PATH，macOS 使用 DYLD_LIBRARY_PATH，Windows 使用 PATH。已安装的 stdx 会提供 CANGJIE_STDX_PATH_DYNAMIC 和 CANGJIE_STDX_PATH_STATIC。

切换项目

执行 envsetup 的输出后，当前会话的 PATH 会指向具体 SDK。需要重新按项目选择工具链时，可打开新终端；也可以再次执行 envsetup 切换当前会话。

交叉 SDK 环境

cjv install sts --target ohos
eval "$(cjv envsetup +sts --target=ohos)"

--target 使用已安装交叉 SDK 的路径与库环境，目标必须属于所选宿主的相同发行版。它不会自动安装该目标，也不提供模拟器或跨平台程序执行能力。SDK 的编译参数和目标设备运行条件见对应仓颉 SDK 文档；cjv 的安装方式见交叉编译。

工具链与版本

一个工具链是一份仓颉 SDK，包含编译器、构建工具和运行时库。cjv 可以同时保存多份 SDK，安装在 <CJV_HOME>/toolchains/ 下；组件和离线文档另行存放。

通道与名称

表中的版本和日期仅用于展示名称格式。用以下命令查询当前分发源：

cjv toolchain list-remote --channel lts
cjv toolchain list-remote --channel nightly --limit 10

通道名不区分大小写。自定义名不能与官方名称冲突，不能包含路径分隔符或以 + 开头，也不能是 .、.. 或空字符串。

跟踪通道与固定版本

cjv install lts
cjv install lts-1.0.5

这会创建两个独立安装。cjv update lts 更新跟踪通道，固定的 lts-1.0.5 保留原样；两者的组件也分别管理。运行 cjc 时使用已安装版本，更新需要执行 install 或 update。

次版本和日期简写安装为解析后的具体版本。需要团队使用相同版本时，在 cangjie-sdk.toml 中写入完整版本名。

nightly 安装会考虑所需组件和交叉 SDK，在清单保留的历史版本中选择兼容版本；默认不降级。--allow-downgrade 允许选择更旧的兼容 nightly。其他安装策略见命令参考。

主机平台

sts-linux-x64、sts-1.2.0-darwin-arm64 可以指定主机平台。不同主机平台独立安装，当前默认平台的显式名称与省略平台的名称指向同一安装。安装其他平台的 SDK 不会让该平台的程序自动具备本机运行能力。

交叉编译 SDK 通过目标管理附加到宿主工具链，不能设为默认或活跃工具链。

自定义 SDK

cjv toolchain link my-sdk /path/to/local/sdk
cjv default my-sdk

目录链接直接引用已有 SDK，源目录由你维护；卸载只移除链接。需要由 cjv 管理副本或添加本地 stdx 时，可改用归档安装。自定义工具链不会通过 cjv update 更新，也没有可供 component add 下载的官方组件。

用 cjv toolchain list 查看安装，用 cjv show active 查看当前选择及来源。选择规则见项目工具链。

项目工具链

把 cangjie-sdk.toml 放在项目根目录并提交到版本控制，即可让项目成员使用同一套工具链声明：

[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]

版本是示例；完整名称格式见工具链与版本。

选择顺序

1. 命令中显式指定的工具链，例如全局 +name 或命令支持的 --toolchain。
2. CJV_TOOLCHAIN 环境变量。
3. 从当前目录向根目录逐层查找：每层先检查目录覆盖，再检查 cangjie-sdk.toml。找到后停止。
4. cjv default 设置的默认工具链。

因此，同一目录的覆盖优先于项目文件，子目录的项目文件优先于父目录的覆盖。不同目录的文件不会合并。cjv show active 显示最终选择及来源。

cjv run <toolchain> <command> 始终使用参数中的工具链。显式选择或环境变量生效时，项目文件中的组件和目标要求不会附加到该选择。

字段

channel 和 path 必须且只能指定一个。直接引用外部 SDK 时，组件由 SDK 所有者维护，components 与 targets 不参与自动安装：

[toolchain]
path = 'C:\SDKs\cangjie'

组件与目标 SDK

targets 只接受后缀，不接受 linux-x64-ohos 这样的完整平台名。大小写和下划线会被规范化，逗号分隔项会展开，重复项会去重；空目标会报错。

[toolchain]
channel = "sts"
components = ["stdx", "docs"]
targets = ["ohos", "android"]

这个声明准备宿主 SDK、宿主组件和目标 SDK。编译时怎样选择目标环境见交叉编译。

自动安装

auto_install 默认开启。运行 cjc、cjpm 等代理命令时，cjv 会补齐所选项目文件声明的缺失项。关闭后，缺失项会让命令报错：

cjv set auto-install false

项目文件错误

未知键会打印警告，已识别字段继续解析。TOML 语法错误、未知组件，以及缺少有效 channel 或 path 都会报错。空文件也会报错；要恢复上级目录或默认选择，请删除文件。

本机目录覆盖

cjv override set nightly
cjv override set lts --path /path/to/project
cjv override list
cjv override unset
cjv override unset --nonexistent

覆盖保存在用户设置中，适用于指定目录及其子目录。--nonexistent 清除已不存在目录的覆盖。

组件与离线文档

组件按工具链分别安装，卸载工具链时一起清理：

安装与移除

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。组件名可重复或逗号分隔。component add 跳过已安装项，加 --force 可重新安装。

可用制品取决于所选通道、版本和平台。自定义工具链没有官方组件下载源。项目也可在 cangjie-sdk.toml 中声明所需组件，由自动安装补齐。

更新行为

跟踪通道升级时，SDK 和所选组件一起更新，固定版本的组件不变。本地链接的 stdx 保留原来源。

链接本地 stdx

cjv component link stdx /path/to/local/stdx --toolchain lts --force

源目录必须包含 dynamic/ 和 static/。--force 替换已有组件；移除链接只删除 cjv 管理的条目，保留源目录。docs 和 stdx-docs 不支持本地链接。

自定义 SDK 的组件

组件修改要求 SDK 位于 cjv 管理的真实目录中。通过 toolchain link 引用的外部 SDK 目录不支持组件修改；需要 cjv 管理组件时，先从本地归档或 URL安装 SDK：

cjv toolchain link my-sdk ./cangjie-sdk.zip
cjv component link stdx /path/to/local/stdx --toolchain my-sdk

stdx 安装后，代理、exec 和 envsetup 会提供 CANGJIE_STDX_PATH_DYNAMIC 与 CANGJIE_STDX_PATH_STATIC。文档组件不修改运行环境。

打开文档

cjv doc
cjv doc std
cjv doc dev-guide
cjv doc tools
cjv doc stdx --toolchain nightly
cjv doc --path

doc 在浏览器中打开本地 HTML；--path 或 --json 只返回路径。book 是 dev-guide 的别名。不带主题时优先打开主体文档，否则尝试扩展库文档；缺少文档时会提示安装对应组件。

自定义 SDK：目录、归档与 URL

cjv toolchain link 接受已有 SDK 目录、本地 .zip / .tar.gz 归档或 HTTP(S) URL：

cjv toolchain link local-sdk /path/to/sdk
cjv toolchain link archive-sdk ./cangjie-sdk.zip
cjv toolchain link remote-sdk https://example.com/cangjie-sdk.tar.gz

这三条命令使用不同名称，可以分别执行。它们不会修改默认工具链；需要时执行 cjv default <name>。

目录与归档的区别

目录链接的内容由源 SDK 所有者维护，cjv 的组件命令不能修改它。归档安装可使用随包 stdx，或通过 component link 添加本地 stdx。

名称必须是自定义工具链名，不能使用 lts、sts、nightly 等官方名称。

归档选项

这些选项仅适用于本地归档或 URL，与目录参数一起使用会报错。未提供 SHA-256 时不做预期内容哈希校验，仍会验证归档与 SDK 布局。

支持的归档

裸 SDK 归档包含一个完整 SDK 顶层目录。cangjie-build 的 CI 外层 ZIP 也受支持，其内部包含：

cangjie-sdk-<sdk_name>-<version>.<tar.gz|zip>
cangjie-stdx-<sdk_name>-<version>.<stdxver>.<tar.gz|zip>  # 可选

内层 SDK 包含 cangjie/ 目录及其 bin/、lib/、tools/、runtime/ 等内容。stdx 包含平台目录下的 dynamic/ 与 static/。存在随包 stdx 且未指定 --no-stdx 时自动安装；stdx 安装失败会保留已成功安装的 SDK。

归档安装要求 SDK 的操作系统与本机匹配。交叉编译使用宿主可运行的目标 SDK，不通过安装其他操作系统的普通 SDK 实现。

cjv component list --toolchain archive-sdk
cjv toolchain uninstall archive-sdk

交叉编译

交叉 SDK 在当前宿主上提供面向其他平台的编译工具。cjv 把它作为宿主工具链的附加安装管理，版本必须与宿主一致，可用目标由分发清单决定。

安装和查询

cjv install sts --target ohos
cjv target list --toolchain sts
cjv target add android --toolchain sts
cjv target list --toolchain sts --installed

target add 为宿主已安装的版本补齐目标，不升级宿主。target list --installed 只读本地状态，可以离线执行；普通列表会查询该发行版的可用目标。

目标参数只写后缀，如 ohos、android、ohos-arm32，不要写 linux-x64-ohos。安装时可重复 --target 或传入逗号分隔列表。

使用目标 SDK

默认的 cjc、cjpm 代理仍使用宿主 SDK。需要调用交叉 SDK 中的工具时，在当前 shell 中加载它的环境：

eval "$(cjv envsetup +sts --target=ohos)"
cjc --version

PowerShell 使用：

cjv envsetup +sts --target=ohos | Invoke-Expression

后续编译参数、系统库和链接器配置由目标 SDK 及项目决定。安装目标或在项目文件中声明 targets 只负责准备 SDK，不会自动把普通 cjpm build 转为目标平台构建。

组件、更新和移除

cjv component add stdx --toolchain sts --target ohos
cjv component list --toolchain sts --target ohos
cjv target remove ohos --toolchain sts

component --target 管理交叉 SDK 自己的组件，要求目标已安装。宿主组件不会自动充当目标组件。

更新跟踪通道时，cjv 一起准备宿主、已跟踪目标和组件，成功后统一发布。默认情况下，缺少所需制品会阻止更新；nightly 可以选择清单中的兼容版本。--force 允许跳过并移除未发布的可选项，具体规则见命令参考。

target remove 移除所选交叉 SDK 及其组件，保留宿主。交叉 SDK 不能直接设为默认或活跃工具链。

配置

用户设置始终保存在 ~/.cjv/settings.toml。CJV_HOME 和 home 只改变数据目录，不改变这个文件的位置。

version = 1
default_toolchain = "lts"
auto_self_update = "check"
auto_install = true

[overrides]
"/home/me/project-a" = "sts"

设置项

自动更新

auto_self_update 只影响未指定名称和全局 +name 的全量 cjv update。enable 自动更新 cjv，check 查询并提示，disable 跳过。开发构建跳过发行检查；cjv self update 可手动执行。

数据目录与主机平台

cjv set home 将相对路径转为绝对路径。cjv set home "" 显式选择默认数据目录。default_host 使用 linux-amd64 这样的 Go 平台格式，和工具链名称中的 linux-x64 格式不同。

继承与临时覆盖

用户设置按字段覆盖系统后备配置，未设置字段继续继承。false 和空字符串也是明确的用户值。cjv set 只保存指定字段，不把其他继承值写入用户文件；要恢复某个字段的继承，删除该字段。

数据目录优先级为 CJV_HOME、home、~/.cjv。分发源优先级为 CJV_DIST_SERVER、合并设置中的 dist_server、manifest_url。环境变量不会因运行 cjv set 而持久化。

未知设置键会警告。无法解析的设置和高于当前支持范围的格式版本会报错。

数据布局

<CJV_HOME>/
  bin/              # cjv 与 SDK 命令入口
  toolchains/<tc>/  # SDK
  stdx/<tc>/        # dynamic/ 与 static/
  docs/<tc>/main/   # 主体文档
  docs/<tc>/stdx/   # 扩展库文档
  downloads/        # 下载归档与可续传部分文件

设置文件只有在使用默认数据目录时才与上述目录位于同一处。用 cjv show home 查看实际数据目录及来源。

下载缓存

带 SHA-256 的下载失败或中断时会保留可续传文件，下次完成后校验整个归档。成功的操作清理自己使用的下载；全量更新全部成功时还会清理残留下载。

SDK 文件复用

默认 link_mode = "hardlink" 对相同发行版、平台和 SHA-256 的 SDK 尝试复用内容相同的普通文件。元数据和组件保持独立，硬链接不可用时保留复制文件。

硬链接共享文件内容，手工原地编辑某份 SDK 可能影响其他安装。需要独立副本时设置 link_mode = "copy"；它只影响后续安装，不拆开已有硬链接。cjv 的更新通过替换目录发布，不原地改写共享文件。

环境变量

环境变量在启动 cjv 前设置，用于当前进程的临时覆盖：

CJV_LOG=debug cjv show active

$env:CJV_LOG = "debug"
cjv show active

重试次数和超时的非法值回退到默认值。清单同时提供制品 URL 与校验和，默认要求 HTTPS；本地回环测试服务器不受该限制。

安装 stdx 后，cjv 为所选 SDK 的运行环境注入 CANGJIE_STDX_PATH_DYNAMIC 和 CANGJIE_STDX_PATH_STATIC，分别指向组件的 dynamic/ 与 static/，通常无需手动设置。

HTTP(S) 代理变量见网络代理。CJV_UPDATE_ROOT 属于安装脚本，用于选择 cjv 本体的首次下载地址；它不覆盖已安装 cjv 的自更新源。

网络代理

cjv 的网络请求遵循标准代理环境变量，涵盖清单、SDK、组件和自更新。

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,artifacts.corp.example
cjv install lts

$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,artifacts.corp.example"
cjv install lts

cmd 使用 set HTTPS_PROXY=http://proxy.example.com:8080。

代理地址支持 http://、https:// 和 socks5://。cjv 不读取 ALL_PROXY / all_proxy，只配置该变量时需改为上表中的变量。请在启动 cjv 前设置代理。

企业 TLS 代理使用自签 CA 时，将 CA 加入操作系统信任库。内部镜像需要直连时，将其主机加入 NO_PROXY。慢速连接可调整 CJV_MAX_RETRIES 和 CJV_DOWNLOAD_TIMEOUT，见环境变量。

企业与离线部署

允许终端访问上游时，配置网络代理即可。终端只能访问内网时，将 SDK、组件和版本清单放入内部分发源。完全离线时使用本地归档或目录。

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 只选择安装脚本的下载地址。该目录需要提供平台归档和 checksums.txt。-NoModifyPath 适合由终端管理系统统一设置 PATH 的环境。

先安装 cjv，再下发设置，最后安装 SDK，可分别检查每一步的退出码。

系统后备配置

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

将示例版本替换为批准版本。关闭自动安装后，项目缺少 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 使用同一完整版本名。nightly 也应固定完整版本，并在分发源中保留该版本及其组件。

完全离线

cjv toolchain link corp-sdk ./cangjie-sdk.zip
cjv component link stdx /opt/corp/cangjie-stdx --toolchain corp-sdk
cjv default corp-sdk

有批准的哈希时，给归档安装传 --sha256 <approved-sha256>。也可直接链接已有 SDK 目录，但这种方式由外部 SDK 所有者维护组件。项目文件使用 corp-sdk 这样的自定义名称，构建依赖也需预先准备。

归档格式见自定义 SDK。docs 和 stdx-docs 不支持本地链接，可在断网前通过分发源安装。

发布和验收

先上传并校验制品，再原子替换清单和推进 latest。nightly 的 latest 位于 nightly.json 顶层；客户端可能根据组件和目标需求选择历史兼容版本。保留被项目固定的所有版本。

验收时使用普通用户和实际 CI 服务账户，检查：

• LTS/STS 和 nightly 分别读取 versions.json、nightly.json，制品 URL 都在批准范围内。
• 批准版本及组件能安装，cjv which cjc 和 cjc --version 指向预期 SDK。
• 断网后，已准备好工具链及依赖的项目仍能构建。
• 企业 CA、代理和 NO_PROXY 生效，缺失项按预期报错。

关闭自动自更新后，由企业软件分发系统升级 cjv 本体。显式执行 cjv self update 仍会使用该构建的上游更新源；网络限制应与部署策略一致。

内部分发源

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 以分发根为基准解析，绝对 URL 完全按 manifest 中的值使用。

文件布局

企业制品库
└── 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：

{
  "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；企业镜像宜直接填入校验和。组件条目支持可选 sha256。版本键决定工具链名称，URL 精确定位下载资产。

nightly 安装以 latest 为候选，并根据目标和组件需求查找清单中的兼容版本；默认不降级。固定完整版本名时使用对应版本。不要把 nightly 内容包在 channels.nightly 下。

组件格式

每个通道的 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 与组件归档。
2. 计算 SDK SHA-256；组件也建议计算并写入 manifest。
3. 先发布所有归档，并用普通终端账户验证 HTTPS GET。
4. 分别生成 versions.json 与 nightly.json。
5. 原子替换对应文件；制品齐全后推进该文件中的 latest。
6. 保留项目工具链文件引用的全部精确版本。

来源优先级为 CJV_DIST_SERVER、设置文件中的 dist_server、manifest_url。CI 可用环境变量临时选择测试源。

命令参考

用 cjv <command> --help 查看本机版本的帮助。名称格式见工具链与版本，选择顺序见项目工具链。

全局选项

显式 --toolchain 优先于全局 +name。exec 和 envsetup 也接受子命令后的 +name。子进程参数由 run、exec 原样传递，退出码也会保留。

安装、更新与卸载

install

cjv install [toolchain]... [-t target]... [-c component]... [--force | --no-update] [--allow-downgrade]

install 省略名称时安装当前选择，指定多个名称时逐项处理。-t/--target 和 -c/--component 可重复或逗号分隔。

安装多个通道，或在安装时添加组件：

cjv install lts sts
cjv install nightly -c stdx,docs

安装与更新策略

没有新增组件或目标需求时，install --no-update 可离线完成。

update

cjv update [toolchain]... [--force] [--allow-downgrade] [--no-self-update]

update 指定名称时处理这些工具链；无名称时使用全局 +name，否则更新所有已跟踪通道。具体版本保持固定，自定义工具链没有官方更新。只有全量更新会按 auto_self_update 检查或更新 cjv，--no-self-update 可跳过。

通道升级会先准备宿主 SDK、已跟踪目标和组件，全部准备完成后替换安装。失败时保留或恢复原安装，固定版本独立保留。

cjv update lts
cjv update --no-self-update

第一条命令只更新 LTS；第二条更新所有已跟踪通道，并跳过 cjv 本体的更新检查。

uninstall

cjv uninstall <toolchain>... [-y]

uninstall 同时清理 SDK、组件、文档及相关目录覆盖。移除默认工具链时尝试选择其他已装宿主。交互终端会确认，-y/--yes、非交互或 JSON 模式直接执行。toolchain uninstall 是等价入口。

check

cjv check

check 只查询 SDK 和 cjv 的可用更新。开发构建跳过自身版本比较。

查询工具链

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...]

使用明确指定的工具链运行命令。cjv 先查找 SDK 工具，再查找该环境的 PATH。需要安装缺失工具链时，把 --install 放在工具链参数前：

cjv run --install sts cjc --version

exec

cjv exec [+toolchain] <command> [args...]

使用当前工具链环境运行命令，也可以用 +name 指定工具链。编译产物需要仓颉运行时库时，可以这样运行：

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 中执行后才会生效。各 shell 的写法和恢复项目工具链选择的方式见运行环境。

自定义工具链

cjv toolchain link <name> <path|url> [--sha256 <hash>] [--force] [--no-stdx]

目录参数创建链接；归档或 URL 解包为受管安装。三个标志仅适用于归档来源：校验 SHA-256、替换同名安装、跳过随包 stdx。布局和平台限制见自定义 SDK。

交叉编译目标

cjv target list [--toolchain <tc>] [--installed]
cjv target add <suffix>... [--toolchain <tc>]
cjv target remove <suffix>... [--toolchain <tc>]

target add 保留宿主版本；target remove 保留宿主安装。target list --installed 可离线查询。

组件

cjv component add <name>... [--toolchain <tc>] [--target <suffix>] [--force]
cjv component link <name> <path> [--toolchain <tc>] [--target <suffix>] [--force]
cjv component remove <name>... [--toolchain <tc>] [--target <suffix>]
cjv component list [--toolchain <tc>] [--target <suffix>] [--installed] [-q]

组件的 --target 只选择已有交叉 SDK，不安装 SDK。

组件名支持 stdx、docs、stdx-docs，可逗号分隔。component add --force 重新安装组件，component link --force 替换已有组件。只有 stdx 支持本地链接，源目录需包含 dynamic/ 和 static/。外部 SDK 目录链接不支持组件修改。详情见组件。

离线文档

cjv doc [topic] [--path] [--toolchain <tc>]

主题为 std、dev-guide（别名 book）、tools、stdx。省略时打开文档首页。--path 和 --json 只返回路径，其他情况启动浏览器。docs 是命令别名，需要先安装文档组件。

选择与设置

default

cjv default [toolchain]

default 省略参数时显示默认选择，none 清除选择；指定未安装的官方工具链时先安装，失败则保留原选择。交叉 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 的顺序选择。交互菜单只列出可用通道；无法确认任何可用通道时，初始化会报错退出。

非终端输入采用非交互模式。工具链安装失败时，命令返回非零退出码，已安装的 cjv 会保留。错误信息提供保留组件选项的重试命令和查询兼容版本的命令。两者都使用已安装程序的绝对路径，无需先刷新 PATH。

self update / self uninstall

cjv self update
cjv self uninstall [-y]

self update 更新 cjv 本体。self uninstall 删除整个数据目录、工具链及组件，并清理 PATH；JSON 模式必须加 -y。

Shell 补全

cjv completion <bash|zsh|fish|powershell>

输出对应 shell 的补全脚本，加载方法见 cjv completion <shell> --help。

常见问题

为什么选中的版本不对？

运行 cjv show active 查看选择及来源，再检查 CJV_TOOLCHAIN、当前目录及父目录的覆盖和 cangjie-sdk.toml。cjv 逐层检查目录，同层覆盖优先；完整规则见项目工具链。

如果执行过 envsetup，当前 shell 可能直接调用某个 SDK。打开新终端恢复代理选择，或重新加载所需工具链的环境。

项目文件拼错字段后会怎样？

未知字段会警告。如果剩余字段没有提供有效的 channel 或 path，命令会报错，不会退回默认工具链。空文件同样如此。需要恢复上级选择时删除文件。

编译产物提示找不到运行时库怎么办？

cjv exec ./my_binary

也可以为当前 shell 加载 cjv envsetup 的输出。各 shell 的写法见运行环境。

离线环境怎样安装？

使用本地 SDK 归档或目录。已有工具链可本地运行，项目依赖仍须预先准备。受管终端可配置内部分发源，并关闭自动安装和自更新检查，见企业部署。

自定义工具链为什么不能下载组件？

自定义 SDK 没有官方发行记录，component add 无法确定对应制品。归档安装可携带 stdx，也可链接本地 stdx。外部目录链接由源 SDK 所有者维护，不支持 cjv 组件修改。参见组件。

卸载会删除什么？

cjv uninstall <name> 删除所选 SDK、附属 stdx 和文档，并清理引用它的目录覆盖。如果它是默认工具链，cjv 会尝试选用其他已安装宿主，否则清除默认选择。链接来源保留。

cjv self uninstall 删除 cjv 数据目录及所有安装，并清理 PATH。命令选项见命令参考。

macOS 下载页为什么让我选架构？

部分浏览器不能可靠报告 Mac 的 CPU 架构。安装脚本会在本机检测；手动下载可运行 uname -m，arm64 对应 Apple Silicon，x86_64 对应 Intel。

nightly 缺少校验和时怎么处理？

cjv 从 nightly.json 读取版本和下载地址。SDK 条目没有 SHA-256 时会尝试 <url>.sha256；sidecar 尚未发布时会提示完整性限制。企业镜像可直接在清单中填写校验和，见分发源格式。