企业官网建设流程全解析

用 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/scalar

Scalar 支持把文档项目（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）：

被发布的“项目”核心是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/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 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

逐步拆解：

1. actions/checkout@v6：把仓库检出到 runner，之后 CLI 读取的配置文件与内容都以检出状态为准（对应上文“默认模式”）。
2. actions/setup-node@v6，node-version: 24：CLI 是 Node 包，工作流显式固定 Node 版本，保证每次运行环境一致。
3. 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的形式注入，避免令牌出现在代码或日志里。
4. npx @scalar/cli project publish --slug your-docs：按 slug 定位平台上的项目并上传发布。之所以能用npx前缀代替全局安装，是因为 CLI 快速入门 说明所有命令都可以写成npx @scalar/cli <command>（pnpm 用户可用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/checkout@v6 - 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_SLUG=production-project" >> $GITHUB_ENV - name: Set development slug if: github.ref == 'refs/heads/development' run: echo "PROJECT_SLUG=development-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_SLUG，github.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/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 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 一节）：

1. 登录 Scalar Dashboard，进入 User API Keys 页面生成 API key；
2. 在 GitHub 仓库中创建名为SCALAR_API_KEY的 Secret；
3. 工作流中只通过${{ 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

参考文件

适用前提小结：以上工作流均要求项目已在 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