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

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