用 GitHub Actions 自动发布 Scalar Docs 项目：基于 @scalar/cli 的 CI 发布实践-北京尧图网络

用 GitHub Actions 自动发布 Scalar Docs 项目基于 scalar/cli 的 CI 发布实践【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar 支持把文档项目Docs project发布为可托管的在线文档站点。官方提供了 GitHub Actions 部署指南通过一个 CI 工作流配合scalar/cli即可在代码推送到指定分支后自动完成“登录 Scalar 平台 → 上传项目配置与内容 → 发布”的完整流程。本文完整覆盖基础工作流、多环境分支级部署、密钥管理三个核心场景并结合 Scalar CLI 文档、认证指南与 CLI 部署参考说明每个步骤背后的 CLI 语义帮助你在自己的仓库中直接落地可运行的发布流水线。先理解发布模型本地文件直传 vs 从 GitHub 拉取在写工作流之前先明确scalar project publish的两种部署模式见 CLI 部署参考默认模式本地直传CLI 把当前机器上的项目配置和内容上传到 Scalar 平台——磁盘上是什么部署的就是什么。GitHub Actions 的actions/checkout步骤把仓库检出到 runner 后发布的就是仓库里的内容。--github模式仅当 Docs 项目已与 GitHub 仓库关联时使用。Scalar 直接从 GitHub 拉取文件部署本地runner 上的改动会被忽略。这一区别决定了两类工作流策略如果项目未关联 GitHub 仓库工作流就是标准的“检出登录发布”三步如果已关联也可以在 CI 中用scalar project publish --github触发从远端拉取并部署从而与本地文件状态解耦。project publish的完整选项如下来自 deployment/cli.md选项类型必填说明--slugstring否项目 slug 标识用于定位平台上的 Docs 项目--configstring否指定scalar.config.json的路径--previewboolean否以预览模式发布不上线--githubboolean否从项目关联的 GitHub 仓库发布Scalar 从 GitHub 拉取忽略本地文件被发布的“项目”核心是scalar.config.json配置文件它定义项目元数据、导航结构和站点设置参考 scalar.config.json 配置说明。可以直接用本仓库根目录的 scalar.config.json 作为真实样例该仓库自身就是按此配置发布文档站点的{ $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, info: { title: Scalar Documentation, description: Guides for Scalar, covering your favorite frameworks, languages and use cases. }, assetsDir: documentation/assets, siteConfig: { subdomain: scalar, customDomain: scalar.com } }其中siteConfig.subdomain决定文档站点挂在https://subdomain.apidocumentation.com下customDomain则支持绑定自有域名见 CLI 文档中关于发布后访问地址的说明。基础工作流推送即发布这是 GitHub Actions 指南中最简的发布工作流放到.github/workflows/publish-scalar-project.yml# .github/workflows/publish-scalar-project.yml name: Publish Scalar Project on: push: branches: - main jobs: publish-project: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Log in to Scalar run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish Project run: npx scalar/cli project publish --slug your-docs逐步拆解actions/checkoutv6把仓库检出到 runner之后 CLI 读取的配置文件与内容都以检出状态为准对应上文“默认模式”。actions/setup-nodev6node-version: 24CLI 是 Node 包工作流显式固定 Node 版本保证每次运行环境一致。npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}CI 环境没有浏览器无法走交互式scalar auth login因此认证指南明确建议自动化工作流使用 API key 直接登录。key 从 Scalar Dashboard 的 Account API Keys 页面生成并以仓库 SecretSCALAR_API_KEY的形式注入避免令牌出现在代码或日志里。npx scalar/cli project publish --slug your-docs按 slug 定位平台上的项目并上传发布。之所以能用npx前缀代替全局安装是因为 CLI 快速入门说明所有命令都可以写成npx scalar/cli commandpnpm 用户可用pnpm dlx无需在 runner 上持久安装。注意仓库里还存在另一个与 git 同名的scalar命令。如果全局安装scalar/cli时遇到EXIST: file already exists冲突可用npm -g --force install scalar/cli覆盖或干脆只用npx/pnpm dlx免安装方式执行见 getting-started.md 的冲突处理一节。如果配置文件不在仓库根目录或项目名与 slug 不一致可在发布步骤中显式指定scalar project publish --slug your-docs --config scalar.config.json环境化部署按分支发布到不同 slug当团队需要main分支发布生产、development分支发布测试环境时官方给出了一套“同一工作流、按分支切换目标项目”的写法# .github/workflows/publish-scalar-project.yml name: Publish Scalar Project on: push: branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Install Scalar CLI run: npm install -g scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set project slug if: github.ref refs/heads/main run: echo PROJECT_SLUGproduction-project $GITHUB_ENV - name: Set development slug if: github.ref refs/heads/development run: echo PROJECT_SLUGdevelopment-project $GITHUB_ENV - name: Publish Project run: scalar project publish --slug $PROJECT_SLUG这套写法值得注意的几个细节安装方式这里改用npm install -g scalar/cli全局安装后续步骤直接调用scalar命令与基础工作流的npx写法等价可按团队习惯二选一。认证方式通过步骤级env把SCALAR_API_KEY注入环境变量后再执行scalar auth login同样是 token 不落盘、不出现在命令参数中。分支路由两个条件步骤分别向$GITHUB_ENV追加PROJECT_SLUGgithub.ref匹配到哪个分支就写入哪个目标项目的 slug最后一个发布步骤用变量统一消费。若未来增加 staging 分支只需追加一个条件步骤无需改动发布逻辑。两个条件步骤保证了PROJECT_SLUG在任何受触发分支上都有值避免发布步骤因变量为空而失败。与这种分支级 slug 路由类似的矩阵化思路也可以在多 API 文档推送 Registry 的场景中见到参考 Registry 的 GitHub Actions 指南中用strategy.matrix并行发布多个文档的写法模式可直接迁移到“一个仓库发布多个 Docs 项目”的场景把 slug 放进矩阵发布步骤消费矩阵变量即可。用预览发布做合并前验证除了直接上线project publish还支持预览模式在发布命令上加--preview即可把构建结果发布为预览部署而不影响线上版本见 CLI 选项参考。典型的 CI 用法是在 pull request 上触发on: pull_request: branches: - main jobs: preview: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Log in to Scalar run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish preview run: npx scalar/cli project publish --slug your-docs --preview这正是预览部署指南中推荐的“项目未关联 GitHub 仓库时”的方案CLI 以预览模式发布让团队成员在合并前就能查看文档变更效果。若项目已在 Dashboard 中启用自动预览Scalar 还会在 PR 上自动留言附预览链接此时无需在工作流里重复实现。密钥管理SCALAR_API_KEY 从哪里来、如何保管官方指南对密钥的要求非常明确GitHub Actions 指南的 Secrets 一节登录 Scalar Dashboard进入 User API Keys 页面生成 API key在 GitHub 仓库中创建名为SCALAR_API_KEY的 Secret工作流中只通过${{ secrets.SCALAR_API_KEY }}或步骤级env引用令牌本身不进入代码库。认证指南也印证了 CI/CD 场景的正确姿势交互式scalar auth login会打开 Dashboard 页面完成授权适合本地开发机自动化环境一律使用scalar auth login --token key。如果发布后需要确认 runner 登录到的是预期账户可以在工作流中追加一步scalar auth whoami用于排障。与自动部署的关系以及回滚选择 GitHub Actions 之前可以先看看自动部署指南在 Dashboard 项目设置中开启自动部署后每次合入默认分支文档都会自动发布且引用了 Registry 文档的项目会在 Registry 文档更新时联动重发。两者定位不同自动部署零配置、跟分支走适合“合入即发布”的简单诉求GitHub Actions由你控制触发条件分支、路径、PR、目标项目按分支切 slug和发布模式--preview或正式适合多环境、多项目或需要额外步骤校验、通知的团队。发布出问题时的恢复手段在 CLI 文档的 Rollback 一节先用scalar project deployments list --slug your-docs查看最近的生产部署记录再用scalar project rollback --slug your-docs回滚到上一个构建或用--to build-id指定目标构建。这条命令同样可以放进工作流或直接在 runner 上手动执行为 CI 自动化发布兜底。可选强化发布前先校验CLI 提供document validate命令用于校验 OpenAPI 文档见 CLI 快速入门中的 GitHub Actions 校验示例。如果你的 Docs 项目内容包含 OpenAPI 文件可以在发布工作流的前面加一步校验让坏文档在 CI 阶段就被拦住而不是发布后才发现问题- name: Validate OpenAPI File # 把 ./my-openapi-file.yaml 换成你项目中 OpenAPI 文件的实际路径 run: npx scalar/cli document validate ./docs/openapi.yaml参考文件文件用途documentation/guides/docs/deployment/github-actions.md本文主体GitHub Actions 发布工作流与 Secrets 配置documentation/guides/docs/deployment/cli.mdproject publish选项表、两种部署模式、回滚命令documentation/guides/docs/deployment/preview-deployments.md预览部署与 PR 预览链接documentation/guides/docs/deployment/automatic-deployment.mdDashboard 自动部署与 CI 方案的取舍参考documentation/guides/cli/authentication.mdCI/CD 中 token 认证方式documentation/guides/cli/getting-started.mdCLI 安装、npx/dlx 免安装用法、命令冲突处理documentation/guides/docs/configuration/scalar.config.json.md被发布项目的配置文件参考scalar.config.json本仓库自身的 Docs 项目配置实例适用前提小结以上工作流均要求项目已在 Scalar 平台创建可通过scalar project create --name ... --slug ...创建且工作流运行的是scalar/cli当前 npm 版本Node 版本固定为 24 是官方示例的选择实际以你仓库 CI 的 Node 基线为准。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

用 GitHub Actions 自动发布 Scalar Docs 项目：基于 @scalar/cli 的 CI 发布实践

相关推荐

Nginx配置前后端分离项目实战指南

超外差接收机本振泄露原理与SDR探测定位实战指南

SEO分析软件核心价值与实战应用解析

更多资讯

手搓教程：工程师的确定性防线与AI协同方法论

高并发排行榜方案：Redis ZSET + 快照缓存 + 双TTL

工学椅选型核心：坐深、腰靠落点、坐高膝高比三大生物力学指标

2026年AI论文检测与智能降重工具全解析

WordPress主题CoreNext免授权版安装配置与安全检查指南

技术内容标题设计：原则、技巧与实战案例

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？