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 ActionsCesiumJS 的持续集成完全建立在 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 资源。它包含四个 joblint依次执行 ESLintnpm run eslint、Markdown lintnpm run markdownlint、代码格式检查npm run prettier-check、构建npm run build、TypeScript 检查npm run tsc以及用 ast-grep 规则 执行的两步静态检查——ast-grep test验证规则自身与ast-grep scan --context 3按规则扫描代码。coverage运行 FirefoxHeadless 下的覆盖率测试npm run coverage -- --browsers FirefoxHeadless --webgl-stub --failTaskOnError --suppressPassed若配置了 AWS 凭据则将Build/Coverage同步到 S3 桶见下文持续部署。release-tests执行npm run make-zip打包发布版 zip再以 ChromeHeadless 运行发布版测试--release参数最后统计代码行数npm run cloc。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生成发布版 zipnpm pack打包 npm 模块与 workspace 模块npm run build-apps -- --outer-originhttps://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 通过后并行执行四个部署 jobdeploy-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.coms3://cesium-dev-sandcastle-website/埋点环境标记为main用于区分 CI 分支构建与主干构建。其他工作流与复用 Actioncla.yml 与 cla-rotation-reminder.yml 负责贡献者许可协议CLA检查与轮换提醒对应 check-for-CLA Actionupdate-tokens.yml 负责定期更新 ion token依赖 update-tokens Actionverify-package 是一个 composite Action实际执行其目录下的script.sh用于验证 npm 包在 Node 环境中的可加载性被 dev 与 deploy 两条流水线复用。持续部署每个分支一份可访问的构建制品自动部署的意义在于无需本地拉取代码并构建即可直接测试和评审最新改动。CesiumJS 对每个分支都独立部署以下制品以main分支为例制品链接main分支Sandcastle 示例应用https://ci-builds.cesium.com/cesium/main/Apps/Sandcastle2/index.htmlAPI 文档https://ci-builds.cesium.com/cesium/main/Build/Documentation/index.html覆盖率结果https://ci-builds.cesium.com/cesium/main/Build/Coverage/index.html发布版 ziphttps://ci-builds.cesium.com/cesium/main/github-ref-name.github-run-number.zipnpm 包https://ci-builds.cesium.com/cesium/main/github-ref-name.github-run-number.tgz上述链接地址由 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 凭据一节否则需要把桶名替换为自己的桶。以文档为基准、结合当前仓库源码需要修改两处工作流中的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部署 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 桶的有效访问凭据操作步骤如下进入你的 fork 仓库页面点击Settings标签页在左侧边栏的Security分组下点击Secrets and Variables→Actions在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.jsnpm 脚本声明见 package.json。【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考