如何使用 GitHub Actions 构建多平台的 code-server 与 OmniRoute面对需要在 Linux、macOS 和 Windows 三个平台构建并统一发布的需求我们设计了一套基于 GitHub Actions 的多平台 CI/CD 流水线。其实这事儿说难也不难只是踩坑的时候确实挺让人头秃的。本文分享这套流水线的设计思路和实现细节——当然也有我们踩过的那些坑。背景code-server (https://github.com/coder/code-server) 是一个将 VS Code 运行在浏览器中的开源项目允许开发者通过远程服务器上的 Web IDE 进行开发。随着 HagiCode 桌面端将 code-server 作为内置运行时我们需要在不同操作系统Linux、macOS、Windows上构建、验证并分发 code-server 的定制版本。这事儿本来应该挺简单的只是…生活哪有那么容易呢与此同时OmniRoute (https://github.com/diegosouzapw/OmniRoute) 作为多模型路由服务也需要与 code-server 共享同一套构建和发布流水线。两个软件包虽然构建方式不同但最终需要汇聚到同一个 GitHub Release 中发布。就像两条原本不相交的线最终还是要在某个点相遇——这就是所谓的宿命吧。这带来了几个工程挑战跨平台构建差异Linux、macOS、Windows 三个平台的构建工具链完全不同Linux 使用 quilt bashmacOS 使用 HomebrewWindows 需要 MSYS2——每个平台都有自己的脾气构建产物验证构建完成后需要自动验证产物能否正常启动——毕竟谁也不想发布一个根本跑不了的东西统一版本管理两个包需要共享同一个版本号和发布标签——就像两个人要共用一个名字总得有个说法并行构建与串行发布构建可以并行但发布需要协调一致——这里容易出错而且错了就是真的错了关于 HagiCode本文分享的方案来自 HagiCode (https://hagicode.com) 项目中的实践经验。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 运行号的零填充序列。这确保了版本的单调递增和可追溯性——毕竟时间是不会倒流的就像有些事情一旦发生了就无法改变javascript // 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中包含以下阶段Plain Text prepare_release → build (matrix) → verify (matrix) → publish_github_release流程说简单也简单说复杂也复杂——关键看你怎么看。触发条件yaml 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——也没什么特别的原因只是随便选了个时间罢了。或许选这个时间的人当时也没想太多。阶段一版本准备yaml jobs: prepare_release: runs-on:ubuntu-22.04 outputs: version:${{steps.version.outputs.version}} tag:${{steps.version.outputs.tag}} steps: -uses:actions/checkoutv6 -uses:actions/setup-nodev6 with: node-version:22 -id:version run:node./scripts/versioning.mjs$GITHUB_OUTPUT此阶段生成统一的版本号和 Git 标签后续所有构建和发布步骤共享这两个值。一个好的开始至少为后续工作省了不少麻烦。阶段二多平台矩阵构建构建阶段使用strategy.matrix在不同平台上并行执行code-server 构建矩阵yaml build_code_server: needs:prepare_release strategy: fail-fast:false matrix: include: -name:code-serverLinux runner:ubuntu-22.04 artifact_name:code-server-linux -name:code-servermacOS runner:macos-latest artifact_name:code-server-macos -name:code-serverWindows runner:windows-latest artifact_name:code-server-windows关键设计fail-fast: false确保某个平台失败不会取消其他平台的构建。毕竟一个平台挂了不代表所有平台都有问题没必要大家一起陪葬。omniroute 构建矩阵yaml build_omniroute: needs:prepare_release strategy: fail-fast:false matrix: include: -name:omnirouteLinuxx64 runner:ubuntu-22.04 platform:linux arch:amd64 -name:omniroutemacOSx64 runner:macos-15-intel platform:macos arch:amd64 -name:omniroutemacOSarm64 runner:macos-14 platform:macos arch:arm64 -name:omnirouteWindowsx64 runner:windows-latest platform:windows arch:amd64OmniRoute 的矩阵更丰富包含 macOS 的 Intel 和 ARM 两个架构。注意 macOS ARM 使用macos-14runnerApple SiliconIntel 使用macos-15-intel。这个世界就是这样总有些东西是分阵营的——就像 Intel 和 ARM永远都不会和解。阶段三平台特定前置条件每个平台需要不同的工具链Workflow 通过条件步骤处理Linuxyaml - name:InstallLinuxprerequisites if:runner.osLinux run:sudoapt-getupdatesudoapt-getinstall-yjqrsyncquiltlibkrb5-devmacOSyaml - name:InstallmacOSprerequisites if:runner.osmacOS run:brewinstalljqrsyncquiltpython-setuptoolsWindowsMSYS2Windows 最复杂需要 MSYS2 来提供类 Unix 工具链——这也是没办法的事毕竟 Windows 的设计哲学和 Unix 系统完全不同yaml - name:SetupMSYS2 if:runner.osWindows uses:msys2/setup-msys2v2 with: msystem:MSYS path-type:inherit update:true install:- diffutils jq patch quilt rsync unzip zip -name:ConfigureWindowsshellpaths if:runner.osWindows 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)其实这些配置也没那么复杂只是第一次遇到的时候确实会让人有点懵。阶段四构建产物验证每个平台构建完成后验证步骤会下载产物、解压并实际启动来验证可用性。毕竟我们不想发布一个根本跑不了的东西——那样太丢人了yaml verify_code_server: needs:build_code_server strategy: fail-fast:false matrix: include: -name:code-serverLinux runner:ubuntu-22.04 bash_path:bash -name:code-serverWindows runner:windows-latest bash_path:C:\msys64\usr\bin\bash.exe验证脚本verify-startup.mjs会解压构建产物在随机可用端口启动 code-server轮询/healthz端点等待服务就绪确认服务响应 200 后关闭进程javascript async functionwaitForHealth(port) { const deadline Date.now() 60_000 while (Date.now() deadline) { const response awaitrequestHealth(port) if (response.statusCode 200) return awaitnewPromise((resolve) setTimeout(resolve, 1000)) } thrownewError(Timed out waiting for code-server to become healthy) }等健康检查的时候总会让人有点焦虑——就像在等一个永远不会回消息的人。只是这次服务终究会启动而有些人可能永远不会回应你。阶段五统一发布所有构建和验证完成后发布阶段将产物收集并创建 GitHub Releaseyaml 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. 平台检测与归一化javascript function normalizePlatform(value) { switch (String(value).toLowerCase()) { casedarwin: casemacos: returnmacos casewin32: casewindows: casewindows_nt: returnwindows default: returnlinux } }不同系统对同一平台的称呼都不一样——就像同一个人在不同场合会有不同的名字但终究还是同一个人。2. Windows 上的 Shell 兼容在 Windows 上npm run会调用cmd.exe但 code-server 的构建脚本依赖 bash。解决方案是设置NPM_CONFIG_SCRIPT_SHELL环境变量并使用 MSYS2。这也是没办法的事毕竟 Windows 和 Unix 的设计理念完全不同javascript 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.gzWindows 使用.zip——每个平台都有自己的偏好就像每个人都有自己的生活习惯javascript 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 直接使用 quiltmacOS 通过 Homebrew 安装 quiltWindows 需要使用 MSYS2 中的 quilt 或退回到patch命令这块挺麻烦的javascript // Windows 上使用 patch 命令替代 quilt asyncfunctionapplyPatchesWithPatch(env) { const series awaitreadFile(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) { awaitrunMsys2(patch -p1 --forward -i patches/${patchFile}, { cwd: codeServerRoot, env }) } }Windows 这块确实折腾了不少时间——没办法谁让 Windows 的设计理念和其他系统不一样呢。版本号设计考量HagiCode 采用YYYY.MMDD.RRRR格式而非上游语义化版本原因如下确定性每次构建的版本号由日期和运行号唯一确定单调递增日期前缀保证自然排序即为时间顺序来源可追溯从版本号即可推断构建时间和 CI 运行序号其实这也没什么的只是刚好够用罢了。语义化版本那种东西说起来很好听只是实际用起来挺麻烦的。注意事项Submodule 递归检出构建时必须使用submodules: recursive确保 code-server 和 omniroute 的上游代码完整拉取这个地方容易忘Node 版本匹配code-server 构建使用上游.node-version文件指定的 Node 版本omniroute 使用 Node 24Windows Home 目录OmniRoute 在 Windows CI 上需要手动创建$HOME目录结构避免构建脚本访问不存在的路径——Windows 的目录结构和其他系统不太一样验证超时code-server 启动验证设置了 60 秒超时需根据实际启动速度调整产物瘦身构建完成后删除内嵌的 Node 二进制slimRelease因为下游会使用自己的 Node 运行时发布幂等性github-release.mjs支持更新已有的 Release先删除旧 Asset 再上传新的确保重试安全这些东西都是踩坑踩出来的经验——当然踩坑的时候确实挺让人头秃的。完整的 CI/CD 流程图Plain Text ┌─────────────────────────────────────────────────────────────────┐ │ 触发源 │ │ 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 → 上传归档文件 │ └─────────────────────────────────────────────────────────────────┘这流程图看起来挺复杂的只是分解来看其实也没那么难。很多事情都是这样看着吓人做起来也就那么回事。关键配置参考yaml # 构建环境变量 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 本身也值得关注一下。毕竟能把这种麻烦事做成自动化的人大概也不会太差吧。参考资料HagiCode 项目地址 (https://github.com/HagiCode-org/site)HagiCode 官网 (https://hagicode.com)code-server 上游仓库 (https://github.com/coder/code-server)OmniRoute 项目 (https://github.com/diegosouzapw/OmniRoute)GitHub Actions 文档 (https://docs.github.com/en/actions)如果本文对你有帮助来 GitHub 给个 Stargithub.com/HagiCode-org/site (https://github.com/HagiCode-org/site)访问官网了解更多hagicode.com (https://hagicode.com)观看正式版演示视频www.bilibili.com/video/BV1z4oWB3EpY/ (https://www.bilibili.com/video/BV1z4oWB3EpY/)一键安装体验docs.hagicode.com/installation/docker-compose (https://docs.hagicode.com/installation/docker-compose)Desktop 桌面端快速安装hagicode.com/desktop/ (https://hagicode.com/desktop/)公测已开始欢迎安装体验原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524 (https://www.newbe.pro)原文链接: https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-05-06-github-actions-multi-platform-code-server-omniroute%2F (https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-05-06-github-actions-multi-platform-code-server-omniroute%2F)版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处! 如何使用 GitHub Actions 构建多平台的 code-server 与 OmniRoute
如何使用 GitHub Actions 构建多平台的 code-server 与 OmniRoute面对需要在 Linux、macOS 和 Windows 三个平台构建并统一发布的需求我们设计了一套基于 GitHub Actions 的多平台 CI/CD 流水线。其实这事儿说难也不难只是踩坑的时候确实挺让人头秃的。本文分享这套流水线的设计思路和实现细节——当然也有我们踩过的那些坑。背景code-server (https://github.com/coder/code-server) 是一个将 VS Code 运行在浏览器中的开源项目允许开发者通过远程服务器上的 Web IDE 进行开发。随着 HagiCode 桌面端将 code-server 作为内置运行时我们需要在不同操作系统Linux、macOS、Windows上构建、验证并分发 code-server 的定制版本。这事儿本来应该挺简单的只是…生活哪有那么容易呢与此同时OmniRoute (https://github.com/diegosouzapw/OmniRoute) 作为多模型路由服务也需要与 code-server 共享同一套构建和发布流水线。两个软件包虽然构建方式不同但最终需要汇聚到同一个 GitHub Release 中发布。就像两条原本不相交的线最终还是要在某个点相遇——这就是所谓的宿命吧。这带来了几个工程挑战跨平台构建差异Linux、macOS、Windows 三个平台的构建工具链完全不同Linux 使用 quilt bashmacOS 使用 HomebrewWindows 需要 MSYS2——每个平台都有自己的脾气构建产物验证构建完成后需要自动验证产物能否正常启动——毕竟谁也不想发布一个根本跑不了的东西统一版本管理两个包需要共享同一个版本号和发布标签——就像两个人要共用一个名字总得有个说法并行构建与串行发布构建可以并行但发布需要协调一致——这里容易出错而且错了就是真的错了关于 HagiCode本文分享的方案来自 HagiCode (https://hagicode.com) 项目中的实践经验。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 运行号的零填充序列。这确保了版本的单调递增和可追溯性——毕竟时间是不会倒流的就像有些事情一旦发生了就无法改变javascript // 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中包含以下阶段Plain Text prepare_release → build (matrix) → verify (matrix) → publish_github_release流程说简单也简单说复杂也复杂——关键看你怎么看。触发条件yaml 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——也没什么特别的原因只是随便选了个时间罢了。或许选这个时间的人当时也没想太多。阶段一版本准备yaml jobs: prepare_release: runs-on:ubuntu-22.04 outputs: version:${{steps.version.outputs.version}} tag:${{steps.version.outputs.tag}} steps: -uses:actions/checkoutv6 -uses:actions/setup-nodev6 with: node-version:22 -id:version run:node./scripts/versioning.mjs$GITHUB_OUTPUT此阶段生成统一的版本号和 Git 标签后续所有构建和发布步骤共享这两个值。一个好的开始至少为后续工作省了不少麻烦。阶段二多平台矩阵构建构建阶段使用strategy.matrix在不同平台上并行执行code-server 构建矩阵yaml build_code_server: needs:prepare_release strategy: fail-fast:false matrix: include: -name:code-serverLinux runner:ubuntu-22.04 artifact_name:code-server-linux -name:code-servermacOS runner:macos-latest artifact_name:code-server-macos -name:code-serverWindows runner:windows-latest artifact_name:code-server-windows关键设计fail-fast: false确保某个平台失败不会取消其他平台的构建。毕竟一个平台挂了不代表所有平台都有问题没必要大家一起陪葬。omniroute 构建矩阵yaml build_omniroute: needs:prepare_release strategy: fail-fast:false matrix: include: -name:omnirouteLinuxx64 runner:ubuntu-22.04 platform:linux arch:amd64 -name:omniroutemacOSx64 runner:macos-15-intel platform:macos arch:amd64 -name:omniroutemacOSarm64 runner:macos-14 platform:macos arch:arm64 -name:omnirouteWindowsx64 runner:windows-latest platform:windows arch:amd64OmniRoute 的矩阵更丰富包含 macOS 的 Intel 和 ARM 两个架构。注意 macOS ARM 使用macos-14runnerApple SiliconIntel 使用macos-15-intel。这个世界就是这样总有些东西是分阵营的——就像 Intel 和 ARM永远都不会和解。阶段三平台特定前置条件每个平台需要不同的工具链Workflow 通过条件步骤处理Linuxyaml - name:InstallLinuxprerequisites if:runner.osLinux run:sudoapt-getupdatesudoapt-getinstall-yjqrsyncquiltlibkrb5-devmacOSyaml - name:InstallmacOSprerequisites if:runner.osmacOS run:brewinstalljqrsyncquiltpython-setuptoolsWindowsMSYS2Windows 最复杂需要 MSYS2 来提供类 Unix 工具链——这也是没办法的事毕竟 Windows 的设计哲学和 Unix 系统完全不同yaml - name:SetupMSYS2 if:runner.osWindows uses:msys2/setup-msys2v2 with: msystem:MSYS path-type:inherit update:true install:- diffutils jq patch quilt rsync unzip zip -name:ConfigureWindowsshellpaths if:runner.osWindows 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)其实这些配置也没那么复杂只是第一次遇到的时候确实会让人有点懵。阶段四构建产物验证每个平台构建完成后验证步骤会下载产物、解压并实际启动来验证可用性。毕竟我们不想发布一个根本跑不了的东西——那样太丢人了yaml verify_code_server: needs:build_code_server strategy: fail-fast:false matrix: include: -name:code-serverLinux runner:ubuntu-22.04 bash_path:bash -name:code-serverWindows runner:windows-latest bash_path:C:\msys64\usr\bin\bash.exe验证脚本verify-startup.mjs会解压构建产物在随机可用端口启动 code-server轮询/healthz端点等待服务就绪确认服务响应 200 后关闭进程javascript async functionwaitForHealth(port) { const deadline Date.now() 60_000 while (Date.now() deadline) { const response awaitrequestHealth(port) if (response.statusCode 200) return awaitnewPromise((resolve) setTimeout(resolve, 1000)) } thrownewError(Timed out waiting for code-server to become healthy) }等健康检查的时候总会让人有点焦虑——就像在等一个永远不会回消息的人。只是这次服务终究会启动而有些人可能永远不会回应你。阶段五统一发布所有构建和验证完成后发布阶段将产物收集并创建 GitHub Releaseyaml 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. 平台检测与归一化javascript function normalizePlatform(value) { switch (String(value).toLowerCase()) { casedarwin: casemacos: returnmacos casewin32: casewindows: casewindows_nt: returnwindows default: returnlinux } }不同系统对同一平台的称呼都不一样——就像同一个人在不同场合会有不同的名字但终究还是同一个人。2. Windows 上的 Shell 兼容在 Windows 上npm run会调用cmd.exe但 code-server 的构建脚本依赖 bash。解决方案是设置NPM_CONFIG_SCRIPT_SHELL环境变量并使用 MSYS2。这也是没办法的事毕竟 Windows 和 Unix 的设计理念完全不同javascript 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.gzWindows 使用.zip——每个平台都有自己的偏好就像每个人都有自己的生活习惯javascript 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 直接使用 quiltmacOS 通过 Homebrew 安装 quiltWindows 需要使用 MSYS2 中的 quilt 或退回到patch命令这块挺麻烦的javascript // Windows 上使用 patch 命令替代 quilt asyncfunctionapplyPatchesWithPatch(env) { const series awaitreadFile(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) { awaitrunMsys2(patch -p1 --forward -i patches/${patchFile}, { cwd: codeServerRoot, env }) } }Windows 这块确实折腾了不少时间——没办法谁让 Windows 的设计理念和其他系统不一样呢。版本号设计考量HagiCode 采用YYYY.MMDD.RRRR格式而非上游语义化版本原因如下确定性每次构建的版本号由日期和运行号唯一确定单调递增日期前缀保证自然排序即为时间顺序来源可追溯从版本号即可推断构建时间和 CI 运行序号其实这也没什么的只是刚好够用罢了。语义化版本那种东西说起来很好听只是实际用起来挺麻烦的。注意事项Submodule 递归检出构建时必须使用submodules: recursive确保 code-server 和 omniroute 的上游代码完整拉取这个地方容易忘Node 版本匹配code-server 构建使用上游.node-version文件指定的 Node 版本omniroute 使用 Node 24Windows Home 目录OmniRoute 在 Windows CI 上需要手动创建$HOME目录结构避免构建脚本访问不存在的路径——Windows 的目录结构和其他系统不太一样验证超时code-server 启动验证设置了 60 秒超时需根据实际启动速度调整产物瘦身构建完成后删除内嵌的 Node 二进制slimRelease因为下游会使用自己的 Node 运行时发布幂等性github-release.mjs支持更新已有的 Release先删除旧 Asset 再上传新的确保重试安全这些东西都是踩坑踩出来的经验——当然踩坑的时候确实挺让人头秃的。完整的 CI/CD 流程图Plain Text ┌─────────────────────────────────────────────────────────────────┐ │ 触发源 │ │ 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 → 上传归档文件 │ └─────────────────────────────────────────────────────────────────┘这流程图看起来挺复杂的只是分解来看其实也没那么难。很多事情都是这样看着吓人做起来也就那么回事。关键配置参考yaml # 构建环境变量 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 本身也值得关注一下。毕竟能把这种麻烦事做成自动化的人大概也不会太差吧。参考资料HagiCode 项目地址 (https://github.com/HagiCode-org/site)HagiCode 官网 (https://hagicode.com)code-server 上游仓库 (https://github.com/coder/code-server)OmniRoute 项目 (https://github.com/diegosouzapw/OmniRoute)GitHub Actions 文档 (https://docs.github.com/en/actions)如果本文对你有帮助来 GitHub 给个 Stargithub.com/HagiCode-org/site (https://github.com/HagiCode-org/site)访问官网了解更多hagicode.com (https://hagicode.com)观看正式版演示视频www.bilibili.com/video/BV1z4oWB3EpY/ (https://www.bilibili.com/video/BV1z4oWB3EpY/)一键安装体验docs.hagicode.com/installation/docker-compose (https://docs.hagicode.com/installation/docker-compose)Desktop 桌面端快速安装hagicode.com/desktop/ (https://hagicode.com/desktop/)公测已开始欢迎安装体验原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524 (https://www.newbe.pro)原文链接: https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-05-06-github-actions-multi-platform-code-server-omniroute%2F (https://docs.hagicode.com/go?platformwechattarget%2Fblog%2F2026-05-06-github-actions-multi-platform-code-server-omniroute%2F)版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!