命令参考

本章逐条列出 cjv 的命令，给出用法、参数、标志与可复制的示例。每个命令的简短说明也会出现在 cjv <command> --help 中。

全局约定

几乎所有命令都接受全局标志 --json，它把结果以稳定的 JSON 结构输出到标准输出，便于脚本消费。cjv run、cjv exec、cjv init 不支持 JSON 输出，传入 --json 会报错。

未显式指定工具链的命令会按统一优先级解析活跃工具链：CJV_TOOLCHAIN 环境变量、目录覆盖、cangjie-sdk.toml 工具链文件、默认工具链，按此顺序取第一个生效的。详见 目标与覆盖。

标准通道名为 lts、sts、nightly，也可写成具体版本（如 lts-1.0.0）。通过 cjv toolchain link 链接的自定义工具链使用任意自定义名，但不得与保留通道名冲突。cjv exec 和 cjv envsetup 还支持以 +name 前缀临时指定工具链，覆盖默认解析。

被代理或被执行的子命令以其原始退出码退出，这适用于 cjv run 与 cjv exec。

安装与卸载

cjv install

安装仓颉 SDK 工具链，可附带交叉编译目标与组件。

cjv install <toolchain> [-t target]... [-c component]... [--force]

参数：

• <toolchain>（必填）：要安装的工具链，如 lts、sts、nightly 或具体版本。它不能用于安装自定义工具链，那种情况请用 cjv toolchain link。

标志：

示例：

# 安装最新 LTS 工具链
cjv install lts

# 安装具体版本
cjv install lts-1.0.0

# 安装宿主 STS SDK，并额外安装两个交叉编译目标
cjv install sts -t ohos -t android
cjv install sts --target ohos,android

# 安装时顺带装上组件
cjv install nightly -c stdx,docs

# 强制重装
cjv install lts --force

target 只填目标后缀，不要写完整平台 key（如 linux-x64-ohos）。交叉编译目标是宿主工具链的附加安装项，不改变活跃工具链。详见 交叉编译与 组件。

cjv uninstall

卸载工具链，并一并清理其 stdx 与离线文档。

cjv uninstall <toolchain> [-y]

参数：

• <toolchain>（必填）：要卸载的工具链名称。

标志：

卸载会在交互式终端弹出确认；非交互式终端、--json 模式或加 -y 时直接执行。如果被卸载的工具链是默认工具链，cjv 会把默认指向另一个已安装的宿主工具链，指向它的目录覆盖也会被清除。卸载会连带删除 <CJV_HOME>/stdx/<tc>/ 与 <CJV_HOME>/docs/<tc>/。

cjv uninstall sts
cjv uninstall lts-1.0.0 -y

cjv toolchain uninstall <name> 与本命令等价，行为一致。

cjv update

将指定工具链或所有已安装工具链更新到对应通道的最新版本。

cjv update [toolchain] [--no-self-update]

参数：

• [toolchain]（可选）：只更新指定工具链。省略时更新所有已安装工具链。

标志：

传入通道名（如 lts）时，更新该通道当前已安装版本到最新版本。传入具体版本时，等同于安装该版本，已安装则跳过。自定义（链接）工具链无法更新，会被跳过或报错。更新到新版本后，原指向旧版本的默认工具链与目录覆盖会自动改指向新版本，旧目录被删除。更新结束后会根据 auto-self-update 设置决定是否自更新 cjv 本身，可用 --no-self-update 关闭。

# 更新所有工具链
cjv update

# 只更新 LTS
cjv update lts

# 更新但不触发 cjv 自更新
cjv update --no-self-update

cjv check

检查已安装工具链是否有可用更新，但不执行安装。

cjv check

逐个列出已安装工具链：有更新显示 当前 → 最新，已是最新显示 ✓，并在末尾显示 cjv 自身版本。--json 模式输出结构化结果，含 update_available、latest 等字段。

cjv check
cjv check --json

查看与运行

cjv show

显示活跃工具链、默认主机平台与已安装工具链列表。

cjv show
cjv show active
cjv show installed
cjv show home

子命令：

cjv show
cjv show active
cjv show home

cjv run

使用指定工具链运行命令，不影响当前 shell。

cjv run [--install] <toolchain> <command> [args...]

参数：

• <toolchain>（必填）：用于运行命令的工具链。
• <command>（必填）：要运行的命令；可以是工具链自带工具（如 cjc、cjpm），也可以是该工具链环境下 PATH 中的任意命令。
• [args...]：传给命令的参数。

标志：

命令在该工具链的运行时环境中执行，cjv 会注入正确的 PATH 与库路径，并应用已安装组件的环境（如 CANGJIE_STDX_PATH_*）。该命令不支持 --json。

# 用 sts 工具链查看 cjc 版本
cjv run sts cjc --version

# 工具链未装则先装再运行
cjv run --install nightly cjpm build

cjv exec

在仓颉运行时环境中执行任意命令，便于直接运行编译产物。

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

参数：

• [+toolchain]（可选）：以 +name 前缀临时指定工具链；省略时按标准优先级解析活跃工具链。
• <command>（必填）：要执行的命令。
• [args...]：传给命令的参数。

仓颉编译出的二进制动态链接运行时库，需要正确的库搜索路径。cjv exec 在注入了运行时库路径的环境中执行命令，但不影响当前 shell。该命令不支持 --json。

# 在活跃工具链的运行时环境中运行编译产物
cjv exec ./my_binary arg1 arg2

# 指定工具链
cjv exec +nightly ./my_binary

# "--" 之后的内容原样传递，可运行以 "+" 开头的命令名
cjv exec -- +weird-command

详见 运行时环境。

cjv envsetup

输出用于配置仓颉运行时环境的 shell 命令，供当前 shell 会话 eval。

cjv envsetup [+toolchain] [--target=SUFFIX] [--shell=TYPE]

参数与标志：

envsetup 与代理模式使用相同的工具链解析优先级。--target 对应的目标 SDK 需先通过 cjv install <toolchain> --target <suffix> 安装。--json 模式输出结构化的环境描述（变量、PATH 前后置、库路径键），不打印 shell 脚本。

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

# Fish
cjv envsetup | source

# PowerShell
cjv envsetup | Invoke-Expression

# 指定工具链并强制 bash 格式
cjv envsetup +nightly --shell=bash

# 输出已安装 ohos 目标 SDK 的环境
cjv envsetup --target=ohos

cjv which

显示活跃工具链中某个 SDK 工具的路径；不带参数时打印工具链根目录。

cjv which [command]

参数：

• [command]（可选）：要查询的工具名，如 cjc、cjpm。省略时打印活跃工具链根目录。

# 打印活跃工具链根目录
cjv which

# 打印 cjc 的绝对路径
cjv which cjc

cjv which 与 cjv run 使用一致的工具解析逻辑：除固定代理工具外，也能解析 bin/ 与 tools/bin/ 下的二进制。

cjv doc

在浏览器中打开当前工具链的离线文档。

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

参数：

• [topic]（可选）：要跳转的子页主题，如 stdx、std、dev-guide、book、tools。省略时打开根 index.html。

标志：

若目标工具链尚未安装 docs / stdx-docs，会提示先用 cjv component add 安装。--json 模式同样只返回路径，不启动浏览器。命令别名：cjv docs。

cjv doc
cjv doc std
cjv doc --path
cjv doc stdx --toolchain nightly

工具链管理

cjv toolchain list

列出已安装的工具链（等价于 cjv show installed）。

cjv toolchain list

cjv toolchain link

将自定义工具链链接到本地目录（引用），或从本地归档 / URL 解包并安装为 cjv 拥有的工具链（物化）。

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

参数：

• <name>（必填）：自定义工具链名。必须是自定义名，不能与保留通道名 lts、sts、nightly 冲突，也不能含路径分隔符、+ 前缀或为非法名。
• <path|url>（必填）：本地目录、本地归档文件（.zip / .tar.gz），或 HTTP(S) URL。目录使用引用模式，归档和 URL 使用物化模式。

两种行为：

标志（仅物化模式，本地归档与 URL 同样适用）：

这三个标志只对物化模式有效，与本地目录一起使用会报错，而不是静默忽略。引用模式要求目录是一个真实的仓颉 SDK（须存在 bin/cjc）。

# 引用模式：只创建链接，原目录保留
cjv toolchain link mysdk /path/to/local/sdk

# 物化模式（本地归档）：解包落地为 cjv 拥有的真实目录，源文件保留
cjv toolchain link mysdk ./cangjie-linux-x64-1.0.0.zip

# 物化模式（URL）：下载、解包，落地为 cjv 拥有的真实目录
cjv toolchain link mysdk https://example.com/cangjie-linux-x64-1.0.0.zip

# 物化模式 + 校验 + 覆盖同名 + 跳过随包 stdx
cjv toolchain link mysdk https://example.com/sdk.zip \
  --sha256 <hash> --force --no-stdx

物化模式的归档格式、随包 stdx 和平台限制见从 URL 或本地归档安装工具链。链接本地 stdx 见组件。

cjv toolchain uninstall

卸载工具链（等价于 cjv uninstall）。

cjv toolchain uninstall <name> [-y]

组件管理

cjv component 的子命令统一支持持久标志 --toolchain <tc> 指定目标工具链；省略时使用当前活跃工具链。

cjv component add

为工具链安装一个或多个组件（如 stdx、docs、stdx-docs）。

cjv component add <name>... [--toolchain <tc>] [--force]

<name> 可重复或逗号分隔。通过 cjv toolchain link 链接的自定义工具链没有对应的 release 资产，component add 对其不可用，请改用 cjv component link。

cjv component add stdx --toolchain lts
cjv component add stdx,docs
cjv component add stdx --force

cjv component link

将本地组件目录链接到工具链，而非通过下载安装。当前用于 stdx。

cjv component link <name> <path> [--toolchain <tc>] [--force]

<path> 必须包含 dynamic/ 与 static/ 两个子目录。链接后相关环境变量仍会正常配置；移除组件或卸载工具链不会删除原始目录。

# 自定义工具链没有 release 资产，用 link 挂上本地 stdx
cjv toolchain link mysdk /path/to/local/sdk
cjv component link stdx /path/to/local/stdx --toolchain mysdk

# 标准通道也可用 link 替代下载（离线 / 调试自编译 stdx）
cjv component link stdx /path/to/local/stdx --toolchain lts --force

cjv component remove

从工具链卸载一个或多个组件。

cjv component remove <name>... [--toolchain <tc>]

<name> 可重复或逗号分隔。别名：uninstall、rm、delete、del。

cjv component remove stdx-docs
cjv component remove stdx,docs --toolchain nightly

cjv component list

列出组件的已安装与可安装情况。

cjv component list [--toolchain <tc>] [--installed] [-q]

cjv component list
cjv component list --toolchain nightly
cjv component list --installed -q

详见 组件。

默认工具链与覆盖

cjv default

设置或显示默认工具链。

cjv default [toolchain]

参数：

• [toolchain]（可选）：要设为默认的工具链。省略时显示当前默认。传入 none 清除默认设置。

交叉编译目标变体（如 lts-1.0.0-ohos）不能设为活跃或默认工具链，请用宿主工具链并通过 targets 配置。若设为一个尚未安装的工具链，会给出 warn 但不阻止。

# 显示当前默认
cjv default

# 设为 lts
cjv default lts

# 清除默认
cjv default none

cjv override set

为某个目录设置工具链覆盖。进入该目录（或其子目录）时，cjv 优先使用该工具链。

cjv override set <toolchain> [--path <dir>]

cjv override set nightly
cjv override set lts --path /path/to/project

cjv override unset

移除目录的工具链覆盖。

cjv override unset [--path <dir>] [--nonexistent]

cjv override unset
cjv override unset --path /path/to/project
cjv override unset --nonexistent

cjv override list

列出所有目录覆盖。

cjv override list

工具链解析优先级与覆盖语义详见 目标与覆盖。

配置

cjv set

修改 cjv 设置（存储在 <CJV_HOME>/settings.toml）。

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 set auto-self-update check
cjv set auto-install true
cjv set default-host linux-amd64
cjv set home /opt/cjv

详见 配置与 环境变量。

自管理

cjv self update

将 cjv 自身更新到最新版本。

cjv self update

cjv self update

cjv self uninstall

卸载 cjv 自身以及所有已安装的工具链（删除整个 <CJV_HOME>/ 并清理 PATH 配置）。

cjv self uninstall [-y]

交互式终端会弹出确认。--json 模式下必须配合 -y 才能执行。

cjv self uninstall
cjv self uninstall -y

安装引导

cjv init

交互式引导首次安装：配置数据目录、PATH，并可选安装默认工具链与组件。通常由安装脚本调用，也可手动运行。

cjv init [-y] [--default-toolchain <name>] [-c component]... [--no-modify-path]

标准输入不是终端时（如 curl ... | sh 引导），自动回退为非交互安装。该命令不支持 --json。

cjv init
cjv init -y --default-toolchain lts -c stdx,docs
cjv init -y --default-toolchain none --no-modify-path

安装方式详见 安装 cjv。