自动化与 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,因为并未尝试执行自动安装。