带来了几个工程挑战：

1. 跨平台构建差异：Linux、macOS、Windows 三个平台的构建工具链完全不同（Linux 使用 quilt + bash，macOS 使用 Homebrew，Windows 需要 MSYS2）——每个平台都有自己的脾气
2. 构建产物验证：构建完成后需要自动验证产物能否正常启动——毕竟谁也不想发布一个根本跑不了的东西
3. 统一版本管理：两个包需要共享同一个版本号和发布标签——就像两个人要共用一个名字，总得有个说法
4. 并行构建与串行发布：构建可以并行，但发布需要协调一致——这里容易出错，而且错了就是真的错了

关于 HagiCode

本文分享的方案来自 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，在其桌面端产品中集成了 code-server 作为内置运行时，因此需要解决多平台构建和发布的工程问题。这事儿，说白了就是为了把产品做出来，仅此而已。

上游构建流水线的局限

code-server 上游项目自带的 CI/CD 流水线（build.yaml）只构建 linux-x64 平台，其发布流程（publish.yaml）仅针对 npm、AUR 和 Docker 等渠道。它不支持：

• macOS 和 Windows 的原生构建——可能是觉得这两个平台不够重要吧
• 多平台矩阵并行构建——或许上游团队的人比较少
• 统一的产物验证机制——反正发布出去让用户自己试就好了

这也没什么，毕竟每个项目都有自己的优先级。只是我们刚好需要这些功能，那就自己来吧。

设计决策

基于上述分析，HagiCode 在 repos/vendered 中设计了独立的构建流水线，核心决策如下：

1. 复用共享的版本管理与发布工具链

版本号采用 UTC 日期格式 YYYY.MMDD.RRRR，其中 RRRR 是 GitHub Actions 运行号的零填充序列。这确保了版本的单调递增和可追溯性——毕竟时间是不会倒流的，就像有些事情一旦发生了就无法改变：

	// scripts/versioning.mjs
	export function formatDateVersion({ date = new Date(), revision }) {
	const year = normalizedDate.getUTCFullYear()
	const month = String(normalizedDate.getUTCMonth() + 1).padStart(2, "0")
	const day = String(normalizedDate.getUTCDate()).padStart(2, "0")
	return `${year}.${month}${day}.${normalizedRevision}`
	}

例如 2026-05-05 的第一次构建会生成版本 2026.0505.0001 和标签 v2026.0505.0001。

其实这个版本号格式也没什么特别的，只是刚好够用罢了。

2. 包级隔离的构建脚本

每个包（code-server、omniroute）在 packages/<name>/scripts/ 下维护自己的构建和验证逻辑，共享的发布工具（scripts/versioning.mjs、scripts/github-release.mjs、scripts/publication.mjs）保持包无关性。各自管好各自的事，互不干扰——这大概就是所谓的"井水不犯河水"吧。

3. 统一的元数据契约

所有包产出标准化的 metadata.json，包含 schemaVersion、packageId、version、platform、arch、sourceRevision 和 artifacts[] 字段，确保下游消费方无需感知包的差异。有了统一的格式，大家都能省点心。

解决

Workflow 整体架构

整个流水线定义在 repos/vendered/.github/workflows/code-server-artifacts.yaml 中，包含以下阶段：

prepare_release → build (matrix) → verify (matrix) → publish_github_release

流程说简单也简单，说复杂也复杂——关键看你怎么看。

触发条件

	on:
	workflow_dispatch: # 手动触发
	schedule:
	- cron: "23 3 * * *" # 每日定时构建
	push:
	branches: [main] # 主分支推送触发
	paths: # 仅在相关文件变更时触发
	- ".github/workflows/code-server-artifacts.yaml"
	- ".gitmodules"
	- "scripts/**"
	- "packages/code-server/**"
	- "packages/omniroute/**"

每日定时构建设在了凌晨 3:23——也没什么特别的原因，只是随便选了个时间罢了。或许选这个时间的人当时也没想太多。

阶段一：版本准备

	jobs:
	prepare_release:
	runs-on: ubuntu-22.04
	outputs:
	version: ${{ steps.version.outputs.version }}
	tag: ${{ steps.version.outputs.tag }}
	steps:
	- uses: actions/checkout@v6
	- uses: actions/setup-node@v6
	with:
	node-version: 22
	- id: version
	run: node ./scripts/versioning.mjs >> "$GITHUB_OUTPUT"

此阶段生成统一的版本号和 Git 标签，后续所有构建和发布步骤共享这两个值。一个好的开始，至少为后续工作省了不少麻烦。

阶段二：多平台矩阵构建

构建阶段使用 strategy.matrix 在不同平台上并行执行：

code-server 构建矩阵

	build_code_server:
	needs: prepare_release
	strategy:
	fail-fast: false
	matrix:
	include:
	- name: code-server Linux
	runner: ubuntu-22.04
	artifact_name: code-server-linux
	- name: code-server macOS
	runner: macos-latest
	artifact_name: code-server-macos
	- name: code-server Windows
	runner: windows-latest
	artifact_name: code-server-windows

关键设计：fail-fast: false 确保某个平台失败不会取消其他平台的构建。毕竟一个平台挂了不代表所有平台都有问题，没必要大家一起陪葬。

omniroute 构建矩阵

	build_omniroute:
	needs: prepare_release
	strategy:
	fail-fast: false
	matrix:
	include:
	- name: omniroute Linux x64
	runner: ubuntu-22.04
	platform: linux
	arch: amd64
	- name: omniroute macOS x64
	runner: macos-15-intel
	platform: macos
	arch: amd64
	- name: omniroute macOS arm64
	runner: macos-14
	platform: macos
	arch: arm64
	- name: omniroute Windows x64
	runner: windows-latest
	platform: windows
	arch: amd64

OmniRoute 的矩阵更丰富，包含 macOS 的 Intel 和 ARM 两个架构。注意 macOS ARM 使用 macos-14 runner（Apple Silicon），Intel 使用 macos-15-intel。这个世界就是这样，总有些东西是分阵营的——就像 Intel 和 ARM，永远都不会和解。

阶段三：平台特定前置条件

每个平台需要不同的工具链，Workflow 通过条件步骤处理：

Linux

	- name: Install Linux prerequisites
	if: runner.os == 'Linux'
	run: sudo apt-get update && sudo apt-get install -y jq rsync quilt libkrb5-dev

macOS

	- name: Install macOS prerequisites
	if: runner.os == 'macOS'
	run: brew install jq rsync quilt python-setuptools

Windows（MSYS2）

Windows 最复杂，需要 MSYS2 来提供类 Unix 工具链——这也是没办法的事，毕竟 Windows 的设计哲学和 Unix 系统完全不同：

	- name: Setup MSYS2
	if: runner.os == 'Windows'
	uses: msys2/setup-msys2@v2
	with:
	msystem: MSYS
	path-type: inherit
	update: true
	install: >-
	diffutils jq patch quilt rsync unzip zip
	- name: Configure Windows shell paths
	if: runner.os == 'Windows'
	shell: pwsh
	run: |
	Add-Content -Path $env:GITHUB_ENV -Value 'NPM_CONFIG_SCRIPT_SHELL=/usr/bin/bash'
	Add-Content -Path $env:GITHUB_ENV -Value ("MSYS2_CMD={0}\\setup-msys2\\msys2.cmd" -f $env:RUNNER_TEMP)

其实这些配置也没那么复杂，只是第一次遇到的时候确实会让人有点懵。

阶段四：构建产物验证

每个平台构建完成后，验证步骤会下载产物、解压并实际启动来验证可用性。毕竟我们不想发布一个根本跑不了的东西——那样太丢人了：

	verify_code_server:
	needs: build_code_server
	strategy:
	fail-fast: false
	matrix:
	include:
	- name: code-server Linux
	runner: ubuntu-22.04
	bash_path: bash
	- name: code-server Windows
	runner: windows-latest
	bash_path: C:\msys64\usr\bin\bash.exe

验证脚本（verify-startup.mjs）会：

1. 解压构建产物
2. 在随机可用端口启动 code-server
3. 轮询 /healthz 端点等待服务就绪
4. 确认服务响应 200 后关闭进程

	async function waitForHealth(port) {
	const deadline = Date.now() + 60_000
	while (Date.now() < deadline) {
	const response = await requestHealth(port)
	if (response.statusCode === 200) return
	await new Promise((resolve) => setTimeout(resolve, 1000))
	}
	throw new Error(`Timed out waiting for code-server to become healthy`)
	}

等健康检查的时候总会让人有点焦虑——就像在等一个永远不会回消息的人。只是这次服务终究会启动，而有些人可能永远不会回应你。

阶段五：统一发布

所有构建和验证完成后，发布阶段将产物收集并创建 GitHub Release：

	publish_github_release:
	needs:
	- prepare_release
	- build_code_server
	- build_omniroute
	- verify_code_server
	- verify_omniroute
	if: >-
	${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
	github.event_name == 'workflow_dispatch' }}
	concurrency:
	group: ${{ format('vendered-github-release-{0}', needs.prepare_release.outputs.tag) }}
	cancel-in-progress: false

关键点：

• 并发控制：使用 concurrency 确保同一标签的发布不会并行执行——避免重复发布总归是好的
• 条件发布：只在 main 分支推送或手动触发时发布，定时构建只执行构建和验证
• 产物汇总：使用 download-artifact 的 pattern 参数批量下载 code-server 和 omniroute 的所有平台产物

实践

跨平台构建脚本的编写要点

构建脚本（build-artifacts.mjs）需要处理平台差异，以下是要点：

1. 平台检测与归一化

	function normalizePlatform(value) {
	switch (String(value).toLowerCase()) {
	case "darwin":
	case "macos":
	return "macos"
	case "win32":
	case "windows":
	case "windows_nt":
	return "windows"
	default:
	return "linux"
	}
	}

不同系统对同一平台的称呼都不一样——就像同一个人在不同场合会有不同的名字，但终究还是同一个人。

2. Windows 上的 Shell 兼容

在 Windows 上，npm run 会调用 cmd.exe，但 code-server 的构建脚本依赖 bash。解决方案是设置 NPM_CONFIG_SCRIPT_SHELL 环境变量并使用 MSYS2。这也是没办法的事，毕竟 Windows 和 Unix 的设计理念完全不同：

	function withCodeServerEnv(env) {
	const scriptShell = platform === "windows"
	? "/usr/bin/bash"
	: env.BASH_PATH || "bash"
	return {
	...env,
	NPM_CONFIG_SCRIPT_SHELL: platform === "windows" ? scriptShell : env.NPM_CONFIG_SCRIPT_SHELL,
	}
	}

3. 产物打包

不同平台使用不同的归档格式（Linux/macOS 使用 .tar.gz，Windows 使用 .zip）——每个平台都有自己的偏好，就像每个人都有自己的生活习惯：

	if (platform === "windows") {
	await run("powershell.exe", [
	"-NoLogo", "-NoProfile", "-Command",
	`Compress-Archive -Path '${releaseDir}' -DestinationPath '${archivePath}' -Force`,
	])
	} else {
	await run("tar", ["-czf", archivePath, "-C", codeServerRoot, path.basename(releaseDir)])
	}

4. 补丁管理

code-server 的定制化通过 patches/ 目录下的 quilt 补丁实现。Linux 直接使用 quilt，macOS 通过 Homebrew 安装 quilt，Windows 需要使用 MSYS2 中的 quilt 或退回到 patch 命令（这块挺麻烦的）：

	// Windows 上使用 patch 命令替代 quilt
	async function applyPatchesWithPatch(env) {
	const series = await readFile(path.join(codeServerRoot, "patches", "series"), "utf8")
	const patchFiles = series.split(/\r?\n/)
	.map(line => line.trim())
	.filter(line => line && !line.startsWith("#"))
	for (const patchFile of patchFiles) {
	await runMsys2(`patch -p1 --forward -i "patches/${patchFile}"`, { cwd: codeServerRoot, env })
	}
	}

Windows 这块确实折腾了不少时间——没办法，谁让 Windows 的设计理念和其他系统不一样呢。

版本号设计考量

HagiCode 采用 YYYY.MMDD.RRRR 格式而非上游语义化版本，原因如下：

• 确定性：每次构建的版本号由日期和运行号唯一确定
• 单调递增：日期前缀保证自然排序即为时间顺序
• 来源可追溯：从版本号即可推断构建时间和 CI 运行序号

其实这也没什么的，只是刚好够用罢了。语义化版本那种东西，说起来很好听，只是实际用起来挺麻烦的。

注意事项

1. Submodule 递归检出：构建时必须使用 submodules: recursive，确保 code-server 和 omniroute 的上游代码完整拉取（这个地方容易忘）
2. Node 版本匹配：code-server 构建使用上游 .node-version 文件指定的 Node 版本，omniroute 使用 Node 24
3. Windows Home 目录：OmniRoute 在 Windows CI 上需要手动创建 $HOME 目录结构，避免构建脚本访问不存在的路径——Windows 的目录结构和其他系统不太一样
4. 验证超时：code-server 启动验证设置了 60 秒超时，需根据实际启动速度调整
5. 产物瘦身：构建完成后删除内嵌的 Node 二进制（slimRelease），因为下游会使用自己的 Node 运行时
6. 发布幂等性：github-release.mjs 支持更新已有的 Release（先删除旧 Asset 再上传新的），确保重试安全

这些东西都是踩坑踩出来的经验——当然，踩坑的时候确实挺让人头秃的。

完整的 CI/CD 流程图

	┌─────────────────────────────────────────────────────────────────┐
	│ 触发源 │
	│ push to main / workflow_dispatch / cron(23 3 * * *) │
	└──────────────────────────┬──────────────────────────────────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────────┐
	│ prepare_release │
	│ 生成版本号: 2026.0506.0001, 标签: v2026.0506.0001 │
	└──────────────────────────┬──────────────────────────────────────┘
	│
	┌────────────┼────────────┐
	▼ ▼ ▼
	┌──────────────┐ ┌──────────────┐ ┌──────────────┐
	│ code-server │ │ code-server │ │ code-server │
	│ Linux │ │ macOS │ │ Windows │
	│ ubuntu-22.04 │ │ macos-latest │ │win-latest │
	└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
	│ │ │
	▼ ▼ ▼
	┌──────────────┐ ┌──────────────┐ ┌──────────────┐
	│ verify │ │ verify │ │ verify │
	│ Linux │ │ macOS │ │ Windows │
	│ 启动+healthz │ │ 启动+healthz │ │ 启动+healthz │
	└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
	│ │ │
	└────────────────┼────────────────┘
	│
	┌────────────────┼────────────────┐
	▼ ▼ ▼
	┌──────────────┐ ┌──────────────┐ ┌──────────────┐
	│ omniroute │ │ omniroute │ │ omniroute │ ...
	│ linux-amd64 │ │ macos-amd64 │ │ macos-arm64 │
	└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
	│ │ │
	└────────────────┼────────────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────────┐
	│ publish_github_release │
	│ 下载所有产物 → 创建/更新 GitHub Release → 上传归档文件 │
	└─────────────────────────────────────────────────────────────────┘

这流程图看起来挺复杂的，只是分解来看其实也没那么难。很多事情都是这样，看着吓人，做起来也就那么回事。

关键配置参考

	# 构建环境变量
	env:
	CI: true
	GITHUB_TOKEN: ${{ github.token }}
	ELECTRON_SKIP_BINARY_DOWNLOAD: 1 # 跳过 Electron 下载
	PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1 # 跳过 Playwright 浏览器下载
	npm_config_build_from_source: true # 从源码构建原生模块
	VERSION: ${{ needs.prepare_release.outputs.version }}

这些环境变量对构建速度和正确性至关重要：跳过不必要的二进制下载可以显著减少构建时间，build_from_source 确保原生模块在目标平台上正确编译。

通过这套流水线，HagiCode 实现了 code-server 和 OmniRoute 在三个操作系统上的自动化构建、验证和发布，将原本需要手动操作的多平台发布流程变成了完全自动化的 CI/CD 过程。这也算是把一件麻烦事变得不那么麻烦了。

总结

设计多平台 CI/CD 流水线的关键在于：

• 版本号集中管理：在流水线开始时生成统一的版本号，所有下游步骤共享
• 构建与发布分离：使用 fail-fast: false 确保某个平台失败不影响其他平台，发布阶段才汇总所有产物
• 平台隔离构建脚本：每个包维护自己的构建逻辑，共享工具链保持包无关
• 产物自动化验证：构建后立即验证可用性，避免发布后才发现问题

这套方案不仅适用于 code-server 和 OmniRoute，也能为其他需要多平台构建的项目提供参考。本文分享的构建系统，正是我们在开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下。

毕竟，能把这种麻烦事做成自动化的人，大概也不会太差吧。