cjv 开发指南
本指南说明 cjv 的构建、架构、测试、网站维护和版本发布流程。安装与使用仓颉 SDK 的说明见用户手册。
仓库目录结构
| 目录 | 内容 |
|---|---|
cmd/cjv/ | cjv、cjv-init 及 SDK 代理入口的 Go 主程序 |
internal/ | 命令组、安装生命周期、分发下载、持久化事务和运行环境 |
tests/ | CLI 端到端集成测试、安装脚本测试和真实下载冒烟测试 |
web/ | React 落地页、浏览器平台检测和公开安装脚本(install.sh、install.ps1) |
docs/ | 用户手册与开发指南(src/ 为中文、en/ 为英文)以及共享主题 |
deployment/ | Cloudflare Worker 与腾讯云 EdgeOne 的边缘函数构建及站点验证工具 |
scripts/ | 平台清单生成、CI 范围筛选、文档站构建与鸿蒙模拟器测试辅助脚本 |
参与开发的基本流程
- 先按从源码构建编译本地 CLI,并在隔离的
CJV_HOME目录中试用改动。 - 阅读代码架构定位改动所属的模块,了解并发锁、持久化事务与状态隔离约束。
- 按测试与检查运行相应的 Go 包测试、安装脚本测试、前端测试与双语文档检查。
- 参考贡献指南拆分原子提交、编写提交信息并发起 Pull Request。
- 涉及官网落地页、文档站或正式版本发布时,请查阅落地页、文档站和发布流程。
从源码构建
go.mod 声明最低 Go 版本为 1.26.0,并通过 toolchain go1.27.3 指定首选工具链。使用默认的 GOTOOLCHAIN=auto 时,Go 会在需要时选择或下载该工具链。Go CLI 可以独立于 web/ 前端构建;生成的平台清单和嵌入的多语言资源已提交到仓库。
go build ./...
go build -o cjv ./cmd/cjv
在 Windows 上请使用 go build -o cjv.exe ./cmd/cjv。第一条命令检查所有 Go 包是否正常编译,第二条命令生成独立可执行文件。如果要把当前工作区的代码直接安装到 GOBIN,可以运行 go install ./cmd/cjv。
在本地交互式调试改动时,建议将 CJV_HOME 和 CJV_CONFIG_FILE 指向一个临时目录,这样既能完整测试 cjv init 和工具链安装,又不会影响本机已有的 cjv 环境:
mkdir -p /tmp/cjv-dev
CJV_HOME=/tmp/cjv-dev CJV_CONFIG_FILE=/tmp/cjv-dev/settings.toml ./cjv init --no-modify-path -y
版本信息与镜像构建
普通本地构建的版本号显示为 dev,并在运行时自动跳过自更新版本比较。正式发布时,GoReleaser 会通过 -ldflags 注入 main.version 和 main.updateURL;你在本地也可以显式注入版本号,或者使用 -tags=mirror 构建 GitCode 镜像版:
go build -ldflags "-X main.version=0.0.0-local" -o cjv ./cmd/cjv
go build -tags=mirror -o cjv-mirror ./cmd/cjv
mirror 构建标签会选择 internal/config/manifest_*.go 与 internal/selfupdate/update_*.go 中的 GitCode 默认版本清单地址和自更新实现。修改 config 或 selfupdate 的共享接口时,请务必同时验证普通版和 mirror 版两种构建。
交叉构建与生成文件
使用 Go 的标准平台环境变量(GOOS 与 GOARCH)即可交叉编译。以 Bash 为例:
GOOS=linux GOARCH=arm64 go build -o cjv ./cmd/cjv
发布平台清单统一定义在 internal/target/catalog.go 中,包括:
- Linux:
amd64、arm64 - macOS(
darwin):amd64、arm64 - Windows:
amd64 - OpenHarmony(
openharmony):amd64、arm64
修改平台清单后,请在仓库根目录运行:
go generate ./...
随后检查生成的 web/src/generated/platforms.ts 前端平台列表,并同步核对 .goreleaser.yml 发布配置和 CI 矩阵的一致性。构建后的行为验证见测试与检查。
OpenHarmony
编译 OpenHarmony 目标程序(GOOS=openharmony)需使用 Go-HMOS go1.27.2-hmos.5 提供的 Linux/amd64 工具链,并设置 CGO_ENABLED=0。此构建保持 GOTOOLCHAIN=local,避免首选工具链指令将定制的 Go-HMOS 切换为标准 Go。
在仓库根目录设置工具路径,先用主机 Go 构建代码签名工具,再交叉编译并签名鸿蒙可执行文件:
export GOENV=off GOTOOLCHAIN=local
export HMOS_GO=/absolute/path/to/go-hmos/bin/go
export HMOS_SIGN=/tmp/cjv-hmos-sign
go build -tags=hmos_sign -o "$HMOS_SIGN" ./scripts/harmonyos
GOOS=openharmony GOARCH=arm64 CGO_ENABLED=0 "$HMOS_GO" build -o cjv ./cmd/cjv
"$HMOS_SIGN" cjv cjv
构建 x64 版本时使用 GOARCH=amd64;构建镜像版时增加 -tags=mirror。
主机签名工具(scripts/harmonyos)复用 internal/ohos/selfsign,负责检查 ELF 结构与 Go 构建信息,写入并校验 .codesign 签名段。传入 --verify FILE... 可单独检查已有二进制产物。
正式发布通过 .goreleaser.yml 构建普通版与 mirror 版,鸿蒙产物在打包归档和生成校验和之前完成签名;而在鸿蒙宿主上运行 cjv 下载安装仓颉 SDK 时,则由 internal/dist 的系统钩子自动对解压出的原生可执行文件完成自签名。
代码架构
cli 负责解析命令行参数与渲染输出,lifecycle 负责编排工具链和组件的安装与更新,底层模块则分别管理分发清单、文件所有权和持久化事务。代理执行(如调用 cjc、cjpm)直接从同一套本地安装状态解析 SDK,绕过 Cobra CLI 命令树。
入口与模块职责
cmd/cjv/main.go 按可执行文件调用名称(os.Args[0])进行分流:
- SDK 工具名(
cjc、cjpm等)直接进入proxy.Run。 cjv-init/cjv-setup前缀进入交互式安装向导。- 其余调用进入
cli.Execute。
| 模块 | 职责 |
|---|---|
cli | Cobra 命令树、参数校验、结果渲染与错误输出 |
lifecycle | SDK、交叉目标、组件、自定义安装、历史回退和卸载的编排 |
toolchain | 安装身份、版本解析、宿主与目标关联关系及本地恢复 |
resolve | 活跃工具链准备与项目缺失项自动安装 |
component | 组件目录、文件清单、本地 stdx 链接及批次编辑 |
dist | 按需加载清单、断点续传下载、SHA-256 校验、解包及准备生命周期 |
target | 平台 tuple、SDK/组件平台映射及发布平台清单 |
env、sdktools | 环境合并、shell 脚本输出(envsetup)和 SDK 工具布局 |
proxy、process | 工具代理转发、子进程执行、退出码和信号处理 |
config | 设置来源与继承、项目选择规则和 <CJV_HOME> 数据目录布局 |
reachable、selfupdate | 受管二进制、<CJV_HOME>/bin 代理入口、PATH 配置及 cjv 自更新 |
fstx、fsops | 持久化事务、原子文件操作、目录树合并和平台重试 |
ohos | 为 OpenHarmony 宿主准备原生 ELF 载荷并自签名 |
横切基础模块为全仓库提供共用能力:
progress定义进度事件类型和输出适配器。i18n、cjverr、logging分别提供多语言消息、带错误码的结构化错误和分级日志。retry是文件系统重试与 HTTP 下载重试策略共用的退避循环。testutil提供测试分发源、进度记录器及平台测试辅助;config/configtest用于隔离设置文件,cli/clitest用于在单元测试中运行命令组。
命令状态与输出
每次调用 cli.Execute 都会创建独立的 clictx.Context(持有输出渲染器、全局 +toolchain 选择器和根命令)以及一棵全新的命令树。各命令组位于各自的子包中(showcmd、componentcmd、runcmd、initcmd、toolchaincmd、settingscmd、selfcmd),各自在结构体中保存自己的标志参数并注册到根命令。子命令将请求交给业务模块,业务模块通过 progress.Sink 报告进度事件并返回结果结构,而不直接打印最终文本:
- 文本模式由
progress.Text和结果对象的Text()方法渲染。 - JSON 模式丢弃进度事件,只向
stdout输出单个结构化 JSON 文档或错误对象。 - 代理模式将
stdout完全留给被调用的 SDK 工具,自动补装进度统一写入stderr。
错误由 CLI 层统一渲染一次,main 负责将其转换为进程退出码。修改 CLI 时请始终保持单次调用的状态隔离,不要把标志、io.Writer 或 JSON 模式存回包级全局变量。
安装与发布
lifecycle.OpenDistribution 仅读取设置、平台定义与远程版本清单,不恢复也不扫描本地安装目录;因此 toolchain list-remote、check 等远程查询不依赖本地恢复成功。写入操作则打开安装分发会话,在读取本地安装快照前先恢复中断事务并迁移旧版目录布局。
一次受管 SDK 安装按以下六个阶段执行:
dist.Preparation获取全局安装锁(<CJV_HOME>/.install.lock),并创建本次操作的私有暂存区。- 在
HomeLock锁内读取目标安装身份、已选组件及宿主依赖快照。 - 释放
HomeLock(继续持有安装锁),解析清单版本、下载归档,并在暂存区准备宿主 SDK、已跟踪交叉目标和组件。 - 重新获取
HomeLock,检查本地快照和依赖关系在锁释放期间是否发生变化。 publication.go通过fstx.NewToolchainGroupTransaction在单个持久化事务中发布各成员需要变更的目录和元数据。- 完成
<CJV_HOME>/bin命令入口配置等收尾工作,标记准备阶段成功,并清理本次操作拥有的下载和暂存文件。
CLI 的 install 默认传入 NoUpdate,确保安装或补齐附加项时保留当前发行版;update 显式推进通道。--allow-missing 允许跳过并移除不可用组件/目标(旧 --force 保留兼容),--reinstall 重装当前发行版。解析 nightly 新安装或更新时仍应用兼容性搜索及显式 --allow-downgrade 规则。
SDK 发行版及来源未变化、只需调整组件时,安装组在锁内复查后仅复制受影响的组件目录和组件元数据,SDK 本体保留在原处。组件文件清单和安装记录与组内其他宿主、交叉目标的变更仍通过同一个事务提交;更换 SDK 或显式 --reinstall 时则准备并发布完整 SDK。所有待发布路径均暂存在对应 SDK、文档或 stdx 根旁的 .staging 树中,便于中断后的统一恢复与清理。
受管组件安装批次(component add)同样先在锁外暂存准备、再在 HomeLock 下复查,并通过单个事务发布组件内容和文件清单,期间 SDK 本体留在原处。component remove 在 HomeLock 内逐项移除组件;某一项失败后仍会尝试其余项,并报告已移除项与汇总错误,不提供整批原子提交。固定版本与跟踪通道彼此独立;硬链接去重(link_mode = "hardlink")只用于满足来源及 SHA-256 内容条件的普通 SDK 文件,元数据和组件从不跨工具链共享。
URL 和本地归档安装走 resolved_install.go:先提交 SDK 本体,再处理随包附带的 stdx。如果随包 stdx 安装失败,会保留已提交的 SDK 并报告部分成功,这与受管通道整组原子发布的语义不同。
恢复与文件所有权
fstx 在移动文件前先将提交状态、受管路径和备份位置写入磁盘日志。进程中断后的恢复会重放日志并采用同一提交或回滚决策;当文件系统错误导致恢复受阻时,会保留日志和备份并返回 RecoveryError。安装、删除和活跃工具链准备均要求先完成恢复,绝不能把恢复所需的备份目录当作普通临时残留清除。
并发读写锁(HomeLock 与 WithStableReads)
HomeLock 始终先获取全局写锁,再获取活跃工具链查询门禁锁(gate)。在执行历史快照复制、校验及历史清理等不修改已安装 SDK 目录的耗时阶段,写进程通过 WithStableReads 暂时释放查询门禁锁,同时继续持有全局写锁。
由于这些阶段不改动已安装的根目录,并发的读进程(如运行 cjc、cjv show active、cjv which)可以直接解析现有 SDK 而不必阻塞等待:
- 读进程在目录定位期间持有查询门禁锁,并以非阻塞方式探测全局写锁。
- 如果确认仍有存活写进程持有全局写锁,读进程直接使用现有安装目录;如果没有存活写进程持有全局写锁(例如写进程已崩溃退出),则执行正常的事务恢复。
- 写进程在真正发布修改前,必须重新获取查询门禁锁并原子清除只读阶段标记。
- 读进程绝不能在持有查询门禁锁的同时阻塞等待全局写锁,以避免锁顺序反转死锁。进程崩溃后遗留的阶段标记不会跳过恢复,且在首次旧布局迁移完成前不启用此快速路径。
组件文件清单与路径安全
component 在创建快照及修改文件前会校验组件根目录、完整文件清单和父目录符号链接。与基础 SDK 共享的文件在移除组件时予以保留;受管的叶节点符号链接可以直接移除而不删除其指向的源目录;归档合并拒绝穿过未跟踪的符号链接。外部 SDK 目录链接不能作为组件编辑根,回退操作同样会检查目标根。
受管组件安装批次拥有可跨进程恢复的持久化发布日志。component remove 逐项直接移除文件;component link 和自定义归档组件编辑使用进程内备份与普通错误回滚,恢复失败时保留备份。这些操作的恢复保证不同,不能将组件安装的持久化事务保证套用到移除或链接操作。
数据路径统一从 config/layout.go 派生,目录树复制、合并和平台重试统一交给 fsops。所有归档解包与目录树操作均拒绝逃出受管目录的路径或链接。
活跃工具链与交叉目标
toolchain.SelectActive 按顺序处理显式 CLI 选择(+name、--toolchain)、CJV_TOOLCHAIN 环境变量、逐层目录覆盖与 cangjie-sdk.toml 项目文件以及全局默认设置。PrepareActive 执行待定恢复并定位本地安装,只有确实缺少官方 SDK 时才调用自动安装回调;无效选择、损坏记录和文件系统错误均直接返回。
run 与 exec 共用 resolve.ActiveRuntime,按 auto_install 补齐需求;run --install 显式允许补装,与 --no-auto-install 冲突。which 只查工具路径,envsetup 读取运行环境并校验项目需求,二者不会自动安装。toolchain.ReadHostTargets 绑定宿主身份、发行版和平台,供目标命令、组件和代理使用,避免关联其他宿主或发行版的交叉 SDK。
env.Runtime 从显式传入的基础环境变量合并 SDK 路径与组件变量,生成子进程环境或 envsetup 脚本(env 本身不负责选择工具链;resolve.ActiveRuntime 将当前选择与对应的 env.Runtime 组合,sdktools 统一工具路径)。Unix 代理直接替换当前进程,Windows 代理与 cjv run、cjv exec 共用 process.Run 处理子进程、退出码与信号。
分发与下载
dist.Source 按需读取并缓存 LTS/STS 的 versions.json 与独立的 nightly.json,组件由同一通道数据解析。cjv 消费静态清单;上游发现和清单生成由独立的 cangjie-version-manifest 仓库负责。
Preparation 持有安装锁、暂存目录和已下载归档,持续到发布与清理结束。失败时保留可续传下载,成功时仅清理本次操作拥有的文件,用户提供的本地归档和恢复日志不归它清理。
归档和 nightly SHA-256 sidecar 请求共用可取消的退避重试。HTTP 408、429 和服务器 5xx 错误可重试,永久性 4xx 错误及格式错误不重试(sidecar 返回 404 表示校验和尚未发布)。带 SHA-256 的下载支持跨命令断点续传并校验完整文件,无哈希下载只在单次操作内续传。
设置与 cjv 自管理
config.SettingsFile 保留每个字段是否由用户显式设置的信息:Update 只写入明确选择的字段,使未设置字段继续继承系统后备配置;Save 则可从快照完整恢复值及字段存在性。环境覆盖保持临时生效;写入前先校验,发布成功后更新内存缓存。
reachable.Ensure 统一安装受管二进制、代理入口和环境脚本,并按调用方策略配置 PATH。selfupdate.Check 只查远程版本,而 selfupdate.Update 校验并替换二进制后返回状态结构,交由 CLI 渲染。默认构建与 mirror 构建分别实现 GitHub 和 GitCode 的版本发现。
测试与检查
请根据改动涉及的范围选择对应的验证命令。CLI 参数测试验证标志解析和输出格式;安装与更新行为通过 lifecycle 的真实生产入口进行测试,使用本地 httptest.Server 提供测试清单和归档。常规单元测试和集成测试不依赖线上分发源。
Go
在仓库根目录运行常规构建、测试与静态检查套件:
go build ./...
go test -race -count=1 -timeout 300s ./...
go vet ./...
golangci-lint run
本地开发迭代时,可以把 ./... 换成受影响的包路径。-race 启用数据竞态检测,-count=1 禁用测试缓存。修改后的 Go 文件请使用 gofmt 格式化,并用 gofmt -l . 检查是否有未格式化文件。静态检查规则定义在 .golangci.yml 中。
修改下载逻辑、自更新或 config / selfupdate 的共享接口时,请同时验证 mirror 构建:
go build -tags=mirror ./...
go test -tags=mirror -race -count=1 ./internal/selfupdate/...
go vet -tags=mirror ./...
CLI 端到端集成测试会编译并在隔离子进程中运行实际的 cjv 二进制:
go test -race -tags integration -count=1 ./tests/integration/
编写测试时,应始终隔离用户主目录、CJV_HOME 和系统后备设置(使用 configtest)。请注意,只修改 CJV_HOME 不会隔离用户的 ~/.cjv/settings.toml。PATH 测试在 Unix 上修改临时 shell 配置文件,在 Windows 上使用注册表守卫保存和恢复用户 PATH。
回归测试放在哪里
请将回归测试放在负责该行为的包中:
| 行为 | 测试位置与断言 |
|---|---|
| 参数、重复调用、JSON | internal/cli 及各 *cmd 命令包:真实命令树(clitest.Root)、独立 writer、单份结果或错误 |
| 安装、更新、回退、卸载 | internal/lifecycle:本地模拟分发源、最终目录内容、设置引用及失败恢复 |
| 主机与目标隔离 | internal/toolchain、internal/lifecycle:安装身份、宿主平台及发行版精确匹配 |
| 组件所有权 | internal/component:与 SDK 共享的文件、越界清单拒绝、符号链接及备份恢复 |
| 进程中断与日志 | internal/fstx、lifecycle 回归:子进程异常退出后的真实日志重放恢复 |
| 续传、取消、重试 | internal/dist:实际 HTTP 请求、Range 请求头、SHA-256 哈希及请求次数 |
| 环境与进程 | internal/env、internal/process:显式传入环境、真实子进程退出码和信号转发 |
测试应断言用户可观察的结果。进度事件请使用 testutil.ProgressRecorder 检查事件种类,不依赖可能随语言变化的翻译文本。测试恢复失败时检查备份文件仍在;测试拒绝危险路径时检查 <CJV_HOME> 外部文件未被改动。
安装脚本与前端
运行 Unix 安装脚本测试套件:
CJV_INSTALL_TEST_SHELL=bash sh tests/install-scripts/install-sh.sh
运行 PowerShell 安装脚本测试套件:
$env:CJV_INSTALL_TEST_POWERSHELL = "pwsh"
./tests/install-scripts/install-ps1.ps1
CI 还会覆盖 sh、zsh、fish 和 Windows PowerShell 5.1。
前端测试在 web/ 目录下运行:
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm coverage
pnpm test:built
Vitest 通过 Playwright 使用真实浏览器运行测试:
VITEST_BROWSER可选择chromium、firefox或webkit。pnpm test:integration在每种浏览器中遍历运行全部模拟平台与架构用例。pnpm coverage合并运行单元测试并检查web/vitest.config.ts中的覆盖率阈值。- 构建完成后运行
pnpm test:built,使用真实浏览器的平台信息验证安装入口、字体下载挂起时的内容可见性,以及桌面端和窄屏移动端的布局溢出(可通过PLAYWRIGHT_BROWSER选择浏览器)。
文档、工作流和依赖
提交 Pull Request 前,请在仓库根目录执行文档、工作流和依赖校验:
npx --yes markdownlint-cli2@0.22.1
python3 scripts/build-docs.py
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
go mod verify
修改依赖后请运行 go mod tidy 并审查 go.mod、go.sum 差异;CI 会再次执行 go mod tidy 并要求工作区无变化。漏洞扫描使用 .github/workflows/ci.yml 中固定的 govulncheck 版本并在当前稳定 Go 上运行;升级扫描器时请同时检查本项目支持的 Go 版本。
共享文档构建脚本 scripts/build-docs.py 会构建全部四份中英文手册,并自动检查所有内部页面、跨书 /book/ 链接、静态资源和 #anchor 标题锚点;PR 检查和线上发布均使用同一入口,详见文档站。
真实下载与 CI
鸿蒙模拟器测试
独立的 .github/workflows/hmos.yml 流程在 x86_64 Linux KVM runner 上启动官方 HarmonyOS 6.1.1(API 24)PC 模拟器。它先交叉编译独立的自签名单元测试二进制,分别以未签名和签名形式执行,再通过 go test -exec 在模拟器中运行 ohos、config、env、fsops、target、cjverr、i18n 和 retry 包的完整测试套件。其余包(包括 HTTP 服务测试)继续由主机 CI 覆盖。该流程仅执行 x86_64 二进制,不执行 ARM64 二进制。
scripts/harmonyos/ 下的两个工具负责协调模拟器运行:
scripts/harmonyos/ci.py负责流程的三个阶段:build编译主机工具,install安装固定版本的模拟器和 Ubuntu 依赖,test执行未签名、签名、退出码及包测试。它通过 Python 的subprocess直接调用程序,不使用 Bash 编排。完成build后,运行python3 scripts/harmonyos/emulator.py python3 scripts/harmonyos/ci.py test即可在本地复现 CI 的测试序列。scripts/harmonyos/exec是供go test -exec使用的主机 Go 程序:它通过 HDC 传入测试二进制,将包目录映射到模拟器内的源码目录,为每次运行分配独立的HOME和TMPDIR,并返回模拟器内的退出码。运行时需设置HDC、HDC_TARGET、HMOS_TEST_SOURCE和HMOS_TEST_ROOT(后者必须位于/data/local/tmp下)。设置HMOS_SIGN时会在传输前签名私有副本,留空则测试未签名执行。scripts/harmonyos/emulator.py负责准备模拟器内的源码与环境变量,运行传入的命令,并在结束后停止模拟器。
将官方 CLI 解压到 HMOS_EMULATOR_HOME,并按从源码构建准备好工具后,可在本地运行模拟器包测试:
go build -o /tmp/cjv-hmos-exec ./scripts/harmonyos/exec
python3 scripts/harmonyos/emulator.py env GOOS=openharmony GOARCH=amd64 CGO_ENABLED=0 \
"$HMOS_GO" test -exec /tmp/cjv-hmos-exec -p 1 -count=1 ./internal/ohos/...
在该模拟器镜像中,HDC shell 使用 uid 2000 且 SELinux 为 Enforcing:它允许运行未签名程序和符号链接,但拒绝创建硬链接。因此只有必须成功创建硬链接的测试会在确认权限错误(EPERM/EACCES)后跳过,而文件去重测试仍会验证复制回退行为。由于模拟器 HDC shell 的结果不能证明真机 HiShell 的签名策略相同,正式发布和 SDK 解包准备仍保留仅在鸿蒙启用的自签名。
在线下载与 CI 范围筛选
线上组件下载测试独立于常规测试,会从上游下载真实制品:
go test -v -tags smoke -run TestSmokeRealComponentDownloads_LTSSTS -count=1 -timeout 45m ./tests/smoke/
.github/workflows/smoke.yml 定时执行该冒烟测试。主工作流 .github/workflows/ci.yml 在每次 PR 和 master 推送时触发,通过 scripts/ci-scope.py 按变更路径选择较重的任务;工作流文件或范围规则变更会运行全部检查。同一 PR 的连续更新会自动取消旧运行,master 推送则不会取消。
前端常规 CI 执行三个浏览器的模拟平台用例,以及 Linux/Windows Chromium 和 macOS WebKit 的真实构建页面检查。手动触发或每周定时 CI 会运行全部任务,并补充原生 Linux ARM64、Windows ARM64 和 macOS Intel 的真实页面检查。HarmonyOS 在其独立工作流中使用相同的路径分类规则和 PR 取消策略。
发布辅助脚本的隔离夹具测试可在装有 bash、zip、unzip、tar 和 sha256sum 的环境中运行:
python3 scripts/test_ci_scope.py
bash tests/release-scripts/release-scripts.sh
贡献指南
从最新的 master 创建工作分支。外部贡献者可先 fork Zxilly/cjv,将源仓库配置为 upstream,再向源仓库的 master 提交 Pull Request:
git fetch upstream
git switch -c fix-windows-path upstream/master
改动与本地验证
- 先复现再修复 — 修复问题前先复现故障,并在代码架构中定位负责该行为的模块。
- 通过生产入口测试 — 在负责该行为的模块中通过真实生产入口补充或更新回归测试;测试位置和验证命令见测试与检查。
- 说明平台覆盖情况 — 改动涉及平台差异(如 Windows 文件锁、Unix shell 配置文件或鸿蒙自签名)时,请在 PR 中说明本机实际验证过的平台,其余平台交由 CI 矩阵检查。
- 同步中英文文档与前端翻译 — 文档的中英文内容(
src/与en/)请在同一提交中同步更新;新增、移动或删除章节时需同时更新两份SUMMARY.md并在book.toml中保留旧页面重定向(见文档站)。web/前端文案使用 Lingui(pnpm i18n:extract),修改后需补齐web/src/locales/en/messages.po中的英文翻译(见落地页)。
原子提交与提交信息
每个提交应包含一个独立的逻辑改动。无关的格式化、重构和依赖升级应分别提交。
每次提交前,请先查看最近的提交历史并沿用仓库当前风格:
git log --oneline -20
提交标题采用 type(scope): description 格式,其中 scope 可省略,描述使用简洁的英文祈使句,例如:
fix(component): enforce ownership across file edits
refactor(toolchain): centralize host target associations
docs: simplify project toolchain setup
Pull request
发起 Pull Request 时,请在描述中说明:
- 触发条件与背景 — 什么命令、配置或边界条件触发了该问题。
- 改动后的行为 — 修改了哪些模块以及现在的预期行为。
- 验证结果 — 在本地运行了哪些测试套件和平台。
- 关联 Issue — 附上相关的 Issue 编号或链接。
推送分支后请留意 CI 运行状态;若出现失败,查看日志并在原分支继续补充修复提交。
涉及命令行为、参数选项或配置格式的变化时,请同时更新用户手册。开发指南中的代码架构只记录稳定的模块职责和约束,具体实现细节留在代码注释和测试中。
落地页
web/ 是部署在 cjv.zxilly.com 和 cjv.zxilly.dev 的静态落地页,提供安装命令和各平台二进制下载。前端使用 React Router Framework Mode、Vite、TypeScript、Tailwind CSS 和 Lingui;web/package.json 声明依赖范围及 pnpm 版本,web/pnpm-lock.yaml 锁定依赖版本。
开发与文件位置
在 web/ 目录下启动本地开发服务器:
cd web
pnpm install --frozen-lockfile
pnpm dev
pnpm build 会生成路由类型、执行 TypeScript 检查,再由 React Router 官方构建流程生成中文 / 与英文 /en/ 的完整 HTML。react-router.config.ts 使用 ssr: false 和 根据 Blog 清单生成的 prerender 路径,静态产物位于 web/dist/client/。pnpm preview 用于预览这些生产产物。需要 Node.js 22.22.0 或更新版本,线上无需运行 React SSR 服务。
预渲染与首次 hydration 都使用通用安装方式,接管后再识别浏览器平台、启用边缘节点给出的镜像默认值。不要在首次渲染时读取浏览器平台或用户偏好,否则会产生 hydration 不匹配。页面正文、命令和文档链接在禁用 JavaScript 时也可读取。
src/lib/seo.ts 定义两种语言的页面元信息,首页底部导航提供对应语言的文档与 Blog 入口。两域名的 canonical 与 hreflang 统一指向 .com 对应页面;.dev 继续提供安装与下载。文档由 mdbook-seo 后端生成 HTML 与逐页元信息,mdbook-sitemap 生成章节 sitemap;scripts/site_map.py 读取渲染后的 canonical,将插件产物与已构建的中英文首页、Blog 页面合并为全站 sitemap,不再修改 HTML。
| 文件或目录 | 内容 |
|---|---|
react-router.config.ts、src/routes.ts | 官方预渲染配置与路由表 |
src/root.tsx | HTML 文档、SEO 元信息与 hydration 入口组件 |
src/App.tsx | 安装页面布局、镜像源切换与下载交互 |
src/hooks/use-platform.ts | 浏览器平台识别与下载建议 |
src/generated/platforms.ts | 由 Go 平台清单(internal/target/catalog.go)生成的前端数据 |
src/lib/i18n.ts、src/locales/ | 语言选择与 Lingui 翻译目录 |
src/style.css、src/components/ | 主题样式和界面组件 |
public/install.sh、public/install.ps1 | 公开分发的 Unix 与 PowerShell 安装脚本 |
修改支持的发布平台时,请更新 Go 的 internal/target/catalog.go 清单并在仓库根目录运行 go generate ./...,不要直接手动编辑生成的 src/generated/platforms.ts。
平台检测
use-platform.ts 先根据同步浏览器信息(navigator.userAgent 与 navigator.platform)计算初始结果,再尝试通过 UA Client Hints(navigator.userAgentData)补充 CPU 架构信息。检测结果分为 ready、unknown 和 unsupported 三种状态:
- macOS 架构歧义处理 — 当 macOS 浏览器无法可靠报告真实 CPU 架构时,
install.sh安装脚本命令仍然可用(脚本会在终端本机检测真实架构),而手动下载面板会同时显示 Apple Silicon 与 Intel 两个选项。 - 移动设备与平板 — 移动操作系统及没有预编译二进制的架构显示为不支持(
unsupported),同时还处理了 iPadOS 桌面模式的 User-Agent 差异。 - 鸿蒙(HarmonyOS / OpenHarmony)检测 — 鸿蒙检测优先读取
OpenHarmony/HarmonyOS标记中的版本号并保留其版本命名空间,绝不将ArkWeb、HuaweiBrowser或Chrome版本当作系统版本。Phone/Mobile表示手机,Tablet表示普通平板(unsupported);Tablet同时包含Windows NT时识别为二合一设备平板模式,PC或桌面Windows NT标记识别为鸿蒙电脑。电脑和二合一设备显示 shell 安装命令及原生ARM64/x86_64下载选项;手机、普通平板和无法确认类型的设备保留对应提示。
这些兼容标记及 UA Client Hints 不会将鸿蒙覆盖识别为 Windows 或 Android,也不用于猜测鸿蒙设备的原生 CPU 架构;下载面板会说明如何用 uname -m 确认架构,以及如何在终端运行 cjv-init。
修改平台识别逻辑后,运行真实浏览器平台测试(pnpm test:integration 和 pnpm test:built),确认无法识别架构时不会错误推荐单一二进制。测试命令见测试与检查。
翻译与样式
中文(zh)是 Lingui 的源语言:
- JSX 元素使用
@lingui/react/macro的<Trans>。 - 组件内字符串表达式使用
useLingui().t。 - 组件外消息描述符使用
@lingui/core/macro的msg。
添加或修改前端文案后,提取词条:
pnpm i18n:extract
随后补齐 src/locales/en/messages.po 中的新英文译文。生产页面的语言由 URL 确定,语言链接同时更新 URL、正文和元信息,并支持浏览器前进与后退。开发与生产均以路由为准,保存的语言偏好不会覆盖显式 URL。每个页面渲染树使用独立的 Lingui 实例,避免预渲染时串语言。生产构建由 Lingui Vite 插件自动编译词条目录。
视觉主题在 src/style.css 中定义,深色模式跟随系统设置,字体由本地依赖打包。界面动效需继续遵循 useReducedMotion 的无障碍偏好。
首页保留原始标志、简短介绍、安装面板和底部导航样式,仅在原有文档、GitHub、Releases、仓颉官网链接中增加 Blog 入口。教程目录、项目协作说明和文章推荐放在文档或 Blog 中,避免重复拉长安装页。
Blog 内容发布
Blog 使用 /blog/ 和 /en/blog/,每篇文章有对应的中英文地址。src/content/blog/posts.json 管理 slug、发布日期及双语标题、摘要和分类;正文分别放在 src/content/blog/zh/ 和 en/ 下的同名 Markdown 文件中。Blog 的界面词条集中在 src/lib/blog.ts,独立于首页的 Lingui 目录。
新增文章时同时提供两个语言版本,正文从 H2 开始,不重复页面的 H1 标题。使用稳定的 slug,文档链接指向 .com 的对应语言页面。react-router.config.ts 根据文章清单自动预渲染列表和文章;服务端构建模块解析 Markdown,生产环境不需要 Markdown API。每篇文章都有独立的 canonical、hreflang、摘要与 BlogPosting 数据。文档构建将实际生成的 Blog 页面加入全站 sitemap。
Blog 延续首页的绿色品牌、字体与系统深色模式,以单栏正文、目录和可横向滚动的代码块组织阅读。更新后运行 pnpm test、pnpm build 和 pnpm test:built,并检查桌面及手机布局。文章中的 SDK 和 CI 命令仍需在所述环境中验证;网页构建测试不代表 SDK 工作流已经执行。
部署内容
在 CI 部署中,.github/workflows/pages.yml 会先构建 web/ 前端,再向 web/dist/client/ 中放入各平台的 /dl/ cjv-init 安装器和两本双语手册。本地单独执行 Vite 构建不会生成这些额外目录。下载安装器来源见发布流程,文档构建输出见文档站。
文档站
docs/user-guide/ 和 docs/dev-guide/ 是两个独立的 mdBook 项目。每本书的 src/ 目录保存简体中文源文件,en/ 目录保存英文源文件,共用同一份 book.toml 配置;两本书的站点主题与语言切换器统一保存在 docs/theme/。
编辑章节
中英文源文件独立维护,内容变化应在同一提交中同步完成:
- 新增、移动或删除章节时,请同时修改
src/SUMMARY.md和en/SUMMARY.md,保持两种语言的页面文件路径完全一致。 - 代码块中的命令、路径、配置键和标识符保持一致,正文与注释可以按语言翻译。
- 同一本书内部使用相对
.md链接;跨书(用户手册与开发指南之间)使用站点绝对 URL(https://cjv.zxilly.com/book/...),因为两本书分别构建。 - 移动或重命名已发布页面时,请在
book.toml的[output.seo.html.redirect]中保留旧地址重定向。
docs/theme/cjv-i18n.js 和 cjv-i18n.css 提供顶栏语言切换器。它通过替换当前 URL 中的 /zh-CN/ 与 /en/ 路径段来切换语言,因此两种语言必须具有相同的页面路径。由于中英文标题生成的 HTML 锚点 ID 不同,切换语言会打开对应章节顶部,并去掉原语言的 #anchor 标题锚点。
本地预览
完整站点构建与检查(推荐)
安装 mdBook 0.5.3、mdbook-sitemap 0.1.1、mdbook-seo 和 Python 3.9 以上版本,在仓库根目录执行:
cargo install mdbook-sitemap --version 0.1.1 --locked
cargo install --git https://github.com/Zxilly/mdbook-seo --rev de97785a384305e149dc52ac24f9f1d8f827bb9c --locked
python3 scripts/build-docs.py
python3 -m http.server --directory web/dist/client 8000
在浏览器中访问 http://localhost:8000/book/user-guide/zh-CN/(或 /en/),即可预览与线上发布完全一致的主题和语言切换器。在 Windows 上如果未配置 python3,可将其换为 python。
scripts/build-docs.py 会为四份书(用户手册与开发指南的中英文版)设置源语言、标题和站点路径,在临时目录中加入共享主题,并自动检查所有生成的 HTML 页面中的内部链接、跨书 /book/ 链接、静态资源和 #anchor 锚点。传入 --output <dir> 可指定其他输出目录,--check-only 只检查已有产物而不重新调用 mdbook。Markdown 格式检查命令见测试与检查。
每本书通过 [output.seo] 使用 mdbook-seo 渲染 HTML,同时生成 canonical、description、hreflang、Open Graph 和 Twitter 元数据。HTML 渲染选项位于 [output.seo.html]。共享的 docs/theme/head.hbs 提供统计代码,docs/user-guide/seo-pages.json 保存安装页的中英文元数据覆盖;构建时分别设置语言的规范域名路径和 locale。
mdbook-sitemap 通过 [output.sitemap] 发现章节,完整构建将 seo/ 产物复制到原有公开路径。scripts/site_map.py 读取生成页面中的 canonical,排除 noindex 页面,并合并四份文档与实际已构建的首页、Blog 页面,不再修改 HTML。发布地址不包含后端目录名。继续关闭 include-lastmod,避免将构建日期写成页面修改日期。
编辑时重新构建
修改 Markdown 或 SEO 配置后,重新执行 python3 scripts/build-docs.py 并刷新静态预览。这是完整中英文站点的预览入口,与生产使用相同的临时构建目录、主题和元数据。直接运行 mdbook serve 不在 SEO 后端当前验证的兼容范围内。
Pages 部署
.github/workflows/pages.yml 在相关前端、文档或部署文件推送到 master、手动运行或被发布流程调用时部署。它先构建 web/ 前端,再向 web/dist/client/ 中放入安装器和四份手册输出:
web/dist/client/
dl/{official,mirror}/{os}_{arch}/cjv-init[.exe]
book/user-guide/{zh-CN,en}/
book/dev-guide/{zh-CN,en}/
请保持这一构建顺序:在 web/ 中执行 pnpm build 会清空 web/dist/client/。PR 检查和发布工作流使用完全相同的 mdBook 版本与构建入口:
python3 scripts/build-docs.py
整个 web/dist/client 作为一个 github-pages artifact 部署到 GitHub Pages 与腾讯云 EdgeOne。安装器来源与发布顺序见发布流程。
发布流程
向仓库推送符合 vX.Y.Z 格式的稳定标签会触发 .github/workflows/release.yml 发布工作流。其他以 v* 开头的标签虽然也会启动工作流,但会在第一步标签格式检查处直接失败。
发布顺序
推送 vX.Y.Z 标签后,发布工作流按以下四个阶段依次执行:
- 校验
vX.Y.Z标签格式,并将发布提交及标签推送到 GitCode。 - 使用 GoReleaser 构建所有平台的普通版(
cjv)与镜像版(cjv-mirror),并上传到 GitHub Release。 - 调用
sync-gitcode-release.yml同步上传 GitCode Release 制品。 - 两边 Release 都发布完成后,调用
.github/workflows/pages.yml更新网站/dl/安装器、落地页和文档站。
日常分支与标签同步由 .github/workflows/mirror.yml 处理。如果第 3 步因临时网络问题导致制品同步失败,可使用 sync-gitcode-release.yml 的手动入口(workflow_dispatch)重试恢复,具体输入参数与凭据见工作流文件。
产物
.goreleaser.yml 定义了 cjv 和带 -tags=mirror 编译的 cjv-mirror 两套构建,每套发布 Linux、macOS、OpenHarmony 的 amd64 与 arm64,以及 Windows amd64:
| 项目 | 命名 |
|---|---|
| 普通归档 | cjv_<os>_<arch>.tar.gz,Windows 为 .zip |
| 镜像归档 | cjv-mirror_<os>_<arch>.tar.gz,Windows 为 .zip |
| 校验和 | checksums.txt |
| 归档内二进制 | cjv 或 cjv-mirror,Windows 加 .exe |
正式发布通过 -ldflags 注入版本号与自更新地址。mirror 构建切换默认的清单地址和自更新后端,而清单中显式写出的绝对制品 URL 仍按原样使用。
修改归档命名规则或增减支持平台时,请同步检查 .goreleaser.yml、安装脚本(install.sh、install.ps1)、scripts/extract-init-binaries.sh、前端生成平台数据(go generate ./...)和 CI 矩阵。
OpenHarmony 构建与签名
发布构建时,.github/actions/setup-hmos 会安装 go1.27.2-hmos.5 工具链(HMOS_GO)并构建主机签名工具(HMOS_SIGN)。GoReleaser 使用 HMOS_GO 构建 openharmony_arm64 和 openharmony_amd64,并在打包归档前调用 HMOS_SIGN 完成签名。生成的鸿蒙归档一并参与 GitCode 同步和 Pages 提取。
在本地运行 GoReleaser 快照预演前,请先按从源码构建设置 HMOS_GO、HMOS_SIGN 并编译好主机签名工具。
网页安装器
发布工作流向 Pages 传入当前发布标签;普通网站部署则在下载前解析一次最新稳定标签(手动运行 Pages 也可指定 release_tag)。随后 scripts/download-release-archives.sh 从同一标签下载全部 14 个归档和 checksums.txt,并运行:
ARCHIVES_DIR=archives OUT_DIR=web/dist/client/dl bash scripts/extract-init-binaries.sh
该脚本会先对照 checksums.txt 校验全部 14 个归档的 SHA-256——任何缺失、重复、无效的校验项或内容不匹配都会在解包前直接报错失败。校验通过后,脚本提取二进制并重命名为 cjv-init(Windows 为 cjv-init.exe),输出到 web/dist/client/dl/{official,mirror}/{os}_{arch}/。程序启动时识别到 cjv-init 前缀后会自动进入 init 安装向导(名称前缀匹配同样兼容浏览器重复下载时自动添加的后缀,如 cjv-init (1).exe)。
install.sh 和 install.ps1 直接下载发布归档并核对 checksums.txt。脚本默认选择最新稳定版,也可显式指定版本;网页安装器则来自最近一次网站部署所选的发布标签。核对两种安装方式时应使用同一标签,并确认对应的网站部署已完成。
本地预演与确认
正式推送标签前,请先运行相关测试与检查,并在本地执行快照预演:
goreleaser release --snapshot --clean
快照构建把产物写到 dist/ 目录,不会真正发布 Release。发布前请检查归档内容与校验和;正式发布后,请确认 GitHub 和 GitCode 的标签与附件、运行 node deployment/verify-site.mjs https://cjv.zxilly.dev/ https://cjv.zxilly.com/ 检查线上下载路径,并实测验证安装器能够下载对应的新版本。