CesiumJS 持续集成与持续部署：GitHub Actions 工作流、S3 部署与分支级制品发布实战

CesiumJS 持续集成与持续部署：GitHub Actions 工作流、S3 部署与分支级制品发布实战

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium

导读

CesiumJS 仓库以 GitHub Actions 为唯一 CI/CD 载体，实现了从代码推送、PR 检查、多维度测试到按分支自动部署构建制品的全链路自动化。本文以仓库中的 ContinuousIntegration 指南 为主线，结合仓库内的 workflow 定义、Gulp 任务与 npm scripts，深入拆解.github/workflows/与.github/actions/的结构、各工作流的触发条件与职责分工，以及为分支或 fork 配置独立 S3 桶与 AWS 凭据的完整实操步骤。读完本文，你将能读懂 CesiumJS 的 CI 流水线全貌，并学会在自己的分支或 fork 上复刻这套"构建—测试—部署—状态回写"的发布链路。

CI 背景：为什么 CesiumJS 选择 GitHub Actions

CesiumJS 的持续集成完全建立在 GitHub Actions 之上。官方文档给出了两篇背景阅读：一篇是 2024 年发布的《CI for CesiumJS: A Deep Dive into Our GitHub Actions Workflow》，系统梳理了当前流水线；另一篇是 2016 年的《Cesium Continuous Integration》，记录了 CI 体系的早期演进。从仓库现状看，这套体系由两大目录承载：

• 可复用的 Action 定义在.github/actions/目录；
• 工作流定义在.github/workflows/目录。

工作流会在两类事件下被触发：有人向 CesiumJS 仓库推送代码，或外部贡献者开启 Pull Request。构建完成后，PR 页面底部会显示构建状态；下拉菜单中可查看每一个独立的检查项，点击 "Details" 链接即可访问日志与已部署的构建制品。

对于任意分支，其工作流检查状态可以在 GitHub 的 Branches 页面（/branches/all）中点击分支名旁边的状态图标查看。

工作流全景：.github/workflows/的职责拆解

仓库中实际存在七个工作流文件，各自承担不同的职责。结合源码逐一说明如下。

dev.yml：日常开发与 PR 的守护者

dev.yml 是最核心的开发流水线，触发条件覆盖：

on: push: branches: - main pull_request: merge_group: concurrency: group: dev-${{ github.ref }} cancel-in-progress: true

即：推送至main、任意 PR、以及合并队列（merge_group）都会触发，并且通过concurrency保证同一 ref 的并发运行会被取消，避免重复消耗 CI 资源。它包含四个 job：

1. lint：依次执行 ESLint（npm run eslint）、Markdown lint（npm run markdownlint）、代码格式检查（npm run prettier-check）、构建（npm run build）、TypeScript 检查（npm run tsc），以及用 ast-grep 规则 执行的两步静态检查——ast-grep test（验证规则自身）与ast-grep scan --context 3（按规则扫描代码）。
2. coverage：运行 FirefoxHeadless 下的覆盖率测试（npm run coverage -- --browsers FirefoxHeadless --webgl-stub --failTaskOnError --suppressPassed），若配置了 AWS 凭据，则将Build/Coverage同步到 S3 桶（见下文"持续部署"）。
3. release-tests：执行npm run make-zip打包发布版 zip，再以 ChromeHeadless 运行发布版测试（--release参数），最后统计代码行数（npm run cloc）。
4. node-smoke-test：在 Node 22 与 24 两个版本上做矩阵冒烟测试，流程为npm run build-release→npm pack打包 cesium 主模块与 workspace 各模块 → 调用复合 Action verify-package 验证 npm 包在纯 Node 环境下可正常加载使用。

deploy.yml：按分支部署构建制品

deploy.yml 负责把除cesium.com、production两个分支外的所有分支（branches-ignore）构建结果部署到公开的 S3 桶。其核心步骤包括：

• 通过npm run deploy-set-version -- --buildVersion $BUILD_VERSION（即 Gulp 任务deploySetVersion，见 gulpfile.js）把<ref名>.<run号>写入package.json的版本号（该任务会把版本中的非字母数字字符剔除，以满足 npm 版本号规范）；
• npm run make-zip生成发布版 zip；
• npm pack打包 npm 模块与 workspace 模块；
• npm run build-apps -- --outer-origin="https://ci-builds.cesium.com"构建 Sandcastle 等应用，并通过环境变量VITE_AMPLITUDE_API_KEY、VITE_ANALYTICS_ENVIRONMENT: ci-branch注入埋点配置；
• 调用复合 Action verify-package 做最终包验证；
• 使用aws s3 sync将构建产物同步到s3://cesium-public-builds/cesium/$BRANCH/，并通过--exclude排除.git、node_modules、文档、测试等无需上线的目录，--delete保证远端与本地严格一致；
• 最后执行npm run deploy-status -- --status success --message Deployed回写 GitHub 状态。

prod.yml 与 sandcastle-dev.yml：生产环境的部署

prod.yml 仅在推送至cesium.com分支时触发（on.push.branches: ["cesium.com"]），属于生产发布流水线，在 lint 通过后并行执行四个部署 job：

• deploy-archive：从 GitHub Release 下载 zip，解压到Build/release/，同步到s3://cesium-website/cesiumjs/releases/<version>/，并单独部署 Sandcastle 归档；
• deploy-docs：将Build/Documentation/同步到s3://cesium-website/cesiumjs/ref-doc/，对应公开的参考文档站点；
• deploy-cesium-viewer：构建npm run build-cesium-viewer后将Build/CesiumViewer/同步到s3://cesium-website/cesiumjs/cesium-viewer/；
• deploy-sandcastle：以VITE_ANALYTICS_ENVIRONMENT: production构建 Sandcastle 并部署到独立的s3://cesium-sandcastle-website/，站点为 sandcastle.cesium.com；
• 后续还有一个delete-old-ion-tokenjob，调用 update-tokens 中的ionTokenDeleter.js清理旧的 ion token。

sandcastle-dev.yml 则在每次推送至main时，把main分支构建出的 Sandcastle 部署到 dev-sandcastle.cesium.com（s3://cesium-dev-sandcastle-website/），埋点环境标记为main，用于区分 CI 分支构建与主干构建。

其他工作流与复用 Action

• cla.yml 与 cla-rotation-reminder.yml 负责贡献者许可协议（CLA）检查与轮换提醒，对应 check-for-CLA Action；
• update-tokens.yml 负责定期更新 ion token，依赖 update-tokens Action；
• verify-package 是一个 composite Action，实际执行其目录下的script.sh，用于验证 npm 包在 Node 环境中的可加载性，被 dev 与 deploy 两条流水线复用。

持续部署：每个分支一份可访问的构建制品

自动部署的意义在于：无需本地拉取代码并构建，即可直接测试和评审最新改动。CesiumJS 对每个分支都独立部署以下制品（以main分支为例）：

上述链接地址由 deploy.yml 中DEPLOYED_URL: https://ci-builds.cesium.com/cesium/${{ github.ref_name }}/拼出。其中 zip 与 npm 包的文件名使用<分支名>.<运行号>作为版本号，例如main.1234.zip；该命名正是由deploySetVersion写入package.json的版本后缀衍生而来。

部署完成后的状态回写由 Gulp 任务 deployStatus 完成：它基于DEPLOYED_URL环境变量拼出部署首页、zip、npm 包、覆盖率四个 URL，并调用 setStatus 向 GitHub 的/repos/{repo}/statuses/{sha}API 分别写入deploy / artifact: deployment、zip file、npm package、coverage results四条状态，从而在 PR 或分支页面上呈现出带链接的部署检查项。

为你的分支或 fork 配置独立的 S3 部署

文档强调：如果你没有 CesiumJS 仓库的提交权限（例如使用 fork），则需要进行额外的部署配置。配置分为两步：更换 S3 桶、配置 AWS 凭据。

第一步：更换不同的 S3 桶

如果你使用官方cesium-public-builds桶且已有有效凭据，可直接跳到"配置 S3 凭据"一节；否则需要把桶名替换为自己的桶。以文档为基准、结合当前仓库源码，需要修改两处：

1. 工作流中的aws s3 sync目标。在 dev.yml 与 deploy.yml 中，将cesium-public-builds替换为你的桶名，例如覆盖率上传：

aws s3 sync ./Build/Coverage s3://cesium-public-builds/cesium/$BRANCH/Build/Coverage --delete --color on

以及 deploy.yml 中的全量同步：

aws s3 sync . s3://cesium-public-builds/cesium/$BRANCH/ \ --cache-control "no-cache" \ --exclude ".git/*" \ --exclude ".github/*" \ --exclude "node_modules/*" \ --delete

2. 部署 URL 常量。文档中给出的原始写法是在 gulpfile.js 硬编码：

const devDeployUrl = "https://ci-builds.cesium.com/cesium/";

需要注意：当前仓库源码已改为从环境变量读取：

const devDeployUrl = process.env.DEPLOYED_URL;

该值由 deploy.yml 中的DEPLOYED_URL注入。因此，在新版本中你要做的是把DEPLOYED_URL改成与你 S3 桶对应托管 URL 相匹配的值，而不是直接编辑 gulpfile.js 的常量。该 URL 会被deployStatus用来生成部署制品链接并回写 GitHub 状态，务必保证与桶的实际托管域名一致。

第二步：配置 S3 凭据

要为 CesiumJS 的 fork 配置可部署的 CI，必须持有目标 S3 桶的有效访问凭据，操作步骤如下：

1. 进入你的 fork 仓库页面；
2. 点击Settings标签页；
3. 在左侧边栏的Security分组下，点击Secrets and Variables→Actions；
4. 在Repository secrets中新增两个环境变量：AWS_ACCESS_KEY_ID（访问密钥 ID）与AWS_SECRET_ACCESS_KEY（访问密钥）。

从工作流源码可以看到这些秘密的实际使用方式：dev.yml 与 deploy.yml 的coverage/deployjob 中通过${{ secrets.DEV_AWS_ACCESS_KEY_ID }}、${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}注入环境变量，并用if: ${{ env.AWS_ACCESS_KEY_ID != '' }}做守卫——未配置凭据时，部署步骤会被安全跳过，而不会导致整个流水线失败。这保证了 fork 用户即使不配置 S3 也能正常跑完构建与测试，只是跳过部署环节。生产流水线 prod.yml 则使用PROD_AWS_ACCESS_KEY_ID/PROD_AWS_SECRET_ACCESS_KEY，与开发环境凭据分离。

总结：CesiumJS CI/CD 流水线的可移植性

纵观整套体系，CesiumJS 的 CI/CD 设计有几个值得借鉴的关键点：

• 同一份代码、两套环境：dev 流水线（dev.yml + deploy.yml）服务分支级开发验证，prod 流水线（prod.yml + sandcastle-dev.yml）服务生产站点发布，二者通过分支名（cesium.com）与独立的 Secrets 命名（DEV_/PROD_前缀）隔离；
• 凭据缺失不阻塞：所有 S3 同步步骤都有AWS_ACCESS_KEY_ID != ''守卫，fork 贡献者无需任何配置即可获得完整的测试反馈；
• 状态即入口：通过deployStatus把部署产物 URL 回写到 GitHub commit status，让 PR 评审者点击 "Details" 即可直达对应分支的 Sandcastle、文档、覆盖率与发布包；
• composite Action 复用：verify-package等 Action 被多条流水线共享，避免了重复定义。

如果你打算在自己的 CesiumJS 分支上启用这套分支级部署，只需按上文两步完成"换桶 + 配凭据"即可；若只想获得 CI 测试反馈而暂不需要部署，保持仓库默认配置即可，所有部署步骤会自动跳过。

相关参考文件：工作流定义位于 .github/workflows/、复用 Action 位于 .github/actions/、Gulp 部署任务位于 gulpfile.js，npm 脚本声明见 package.json。

【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium