文档

在构建过程中写入版本号

为每个发布版本指定版本号和构建号,将其传入构建流程,再由 CoRoid 确认各环境运行的版本。

使用您的软件的用户需要查看他们运行的是哪个版本。CoRoid 会为每个发布版本指定版本号和构建号,将这两个值传入构建它的流水线,随后验证该环境确实运行您部署的发布版本。

1. CoRoid 负责命名

发布

1.4.1

构建 12

来源包括 CoRoid、代码库中的文件或流水线。

2. 由您的流水线完成构建

您的 CI/CD

COROID_VERSION=1.4.1

COROID_BUILD_NUMBER=12

COROID_COMMIT_SHA=3da015d…

这些值会以变量或工作流输入的形式传入。

3. 最终供用户查看使用

关于我们

版本 1.4.1 (12)

版本信息会显示在应用中,并写入 release.json。

4. CoRoid 负责验证确认

GET /version.json

已验证

流水线已上报 1.4.1,构建版本为 12

部署完成后,CoRoid 会读取版本对应的 URL。

版本随发布内容一同进入构建,CoRoid 会验证环境中实际运行的内容。

本页所有设置均按项目在以下路径中配置:版本发布 → 版本设置 → 版本管理。

版本号的来源

每个项目可选择一种来源:

  • CoRoid 会为其赋值(默认模式):当您准备发布版本时,CoRoid 会建议下一个版本号。它会取该项目已发布的最高版本号的最后一个数字加一,因此1.4.0会紧跟在1.4.1之后。首个版本为0.1.0。如有需要,可手动输入其他版本号。若某次部署由 CoRoid 启动(例如向 CoRoid 上报的手动部署),也会采用下一个版本号,除非该流水线自行指定了版本号。
  • 从代码库读取版本号:CoRoid 会读取代码在发布提交时所声明的版本号。它会先查找VERSION、package.json、 app.json(Expo),pubspec.yaml、Android 的 Gradle 文件,Cargo.toml、 pyproject.toml以及 Xcode 项目中的版本信息,也可仅指定特定文件进行读取。若该文件中仍保留着此前发布版本使用的版本号,CoRoid 会要求您先更新版本号。
  • 由我的流水线分配版本号:你的 CI/CD 会选取版本号,例如通过 semantic-release 或标签获取,随后在部署时反馈该版本号。

每个版本还会分配一个构建号。构建号只会递增且不会在同一项目中重复使用,这符合 iOS 和 Android 应用商店的要求。CFBundleVersion以及 AndroidversionCode。

构建流程接收的参数

当 CoRoid 为某个发布版本启动 GitHub Actions 工作流或 GitLab CI/CD 流水线时,会传递以下参数:

GitLab 变量GitHub 输入项取值
COROID_VERSIONcoroid_version版本号
COROID_BUILD_NUMBERcoroid_build_number构建号
COROID_RELEASE_NAMEcoroid_release_name版本名称
COROID_COMMIT_SHAcoroid_commit_sha完整的提交哈希值
COROID_ENVIRONMENTcoroid_environment环境标识
COROID_RELEASE_IDcoroid_release_idCoRoid 发布的版本标识
COROID_ATTEMPT_IDcoroid_attempt_id部署尝试次数

GitHub 会拒绝工作流未声明的相关输入参数。因此 CoRoid 会发送coroid_version、coroid_build_number和coroid_release_name传递给已列出这些参数的工作流。可将它们声明为可选参数:

on:
  workflow_dispatch:
    inputs:
      coroid_release_id: { required: true }
      coroid_attempt_id: { required: true }
      coroid_commit_sha: { required: true }
      coroid_environment: { required: true }
      coroid_version: { required: false }
      coroid_build_number: { required: false }
      coroid_release_name: { required: false }

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      APP_VERSION: ${{ inputs.coroid_version || '0.0.0-dev' }}
      APP_BUILD_NUMBER: ${{ inputs.coroid_build_number || '0' }}
      APP_COMMIT: ${{ inputs.coroid_commit_sha || github.sha }}

GitLab 会将参数作为变量传递,无需额外声明:

deploy:
  script:
    - export APP_VERSION="${COROID_VERSION:-0.0.0-dev}"
    - export APP_BUILD_NUMBER="${COROID_BUILD_NUMBER:-0}"
    - export APP_COMMIT="${COROID_COMMIT_SHA:-$CI_COMMIT_SHA}"

独立运行的流水线可使用自有参数。按下方说明上报所部署的版本号,即可在版本信息中显示该版本。

编写版本清单文件

适用于所有平台的最简单方法是:构建过程中生成一个小文件,随后在需要显示版本号的地方读取该文件内容:

cat > release.json <<EOF
{
  "version": "$APP_VERSION",
  "buildNumber": "$APP_BUILD_NUMBER",
  "commitSha": "$APP_COMMIT",
  "releaseName": "${COROID_RELEASE_NAME:-}",
  "environment": "${COROID_ENVIRONMENT:-local}"
}
EOF

对于 Web 应用或服务,可将文件部署在/version.json。这也为 CoRoid 提供了用于验证的 URL(详见下文)。

实施方案

Web 应用(Next.js、Vite)

浏览器所需的参数需在打包时设置:

NEXT_PUBLIC_APP_VERSION="$APP_VERSION" NEXT_PUBLIC_APP_COMMIT="$APP_COMMIT" npm run build
VITE_APP_VERSION="$APP_VERSION" npm run build

在页脚或关于页面显示process.env.NEXT_PUBLIC_APP_VERSION或import.meta.env.VITE_APP_VERSION,并将release.json复制到构建前的公共文件夹中。

服务器与 API

启动时读取相关参数,并通过版本接口返回结果:

app.get('/version.json', (_request, response) => {
  response.json({
    version: process.env.APP_VERSION,
    buildNumber: process.env.APP_BUILD_NUMBER,
    commitSha: process.env.APP_COMMIT,
  });
});

Docker 镜像

将参数作为构建参数传递并标记镜像,这样运行中的容器和镜像仓库都能识别版本号:

ARG APP_VERSION=0.0.0-dev
ARG APP_COMMIT=unknown
ENV APP_VERSION=$APP_VERSION APP_COMMIT=$APP_COMMIT
LABEL org.opencontainers.image.version=$APP_VERSION \
      org.opencontainers.image.revision=$APP_COMMIT
docker build --build-arg APP_VERSION="$APP_VERSION" --build-arg APP_COMMIT="$APP_COMMIT" .

iOS

Xcode 会从MARKETING_VERSION读取 App Store 显示的版本号,从CURRENT_PROJECT_VERSION:

xcodebuild -scheme App -configuration Release archive \
  MARKETING_VERSION="$APP_VERSION" \
  CURRENT_PROJECT_VERSION="$APP_BUILD_NUMBER"

使用 fastlane 时,可调用increment_version_number(version_number: ENV["APP_VERSION"])和increment_build_number(build_number: ENV["APP_BUILD_NUMBER"])。

安卓

读取其中的数值app/build.gradle.kts:

android {
    defaultConfig {
        versionName = System.getenv("APP_VERSION") ?: "0.0.0-dev"
        versionCode = (System.getenv("APP_BUILD_NUMBER") ?: "1").toInt()
    }
}

BuildConfig.VERSION_NAME随后在应用中显示对应版本。

Flutter

flutter build appbundle --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"
flutter build ipa --build-name="$APP_VERSION" --build-number="$APP_BUILD_NUMBER"

Expo和React Native

读取其中的数值app.config.js:

export default {
  expo: {
    version: process.env.APP_VERSION ?? '0.0.0-dev',
    ios: { buildNumber: process.env.APP_BUILD_NUMBER ?? '1' },
    android: { versionCode: Number(process.env.APP_BUILD_NUMBER ?? 1) },
  },
};

上报已部署的版本

部署事件可标明所部署的版本和构建号。添加version以及buildNumber到流水线已发送的事件中:

{
  "schemaVersion": 1,
  "eventId": "ci:run-812:production:succeeded",
  "providerRunId": "run-812",
  "projectId": "<project-uuid>",
  "environmentKey": "production",
  "repository": "owner/repository",
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "status": "succeeded",
  "occurredAt": "2026-09-28T12:00:00Z",
  "version": "1.4.0",
  "buildNumber": "42"
}

若项目的流水线负责分配版本号,发布版本会采用流水线报告的版本号。否则发布页面会显示报告的版本号,并标注其与发布版本的差异。对于托管在 CoRoid 上的项目,需设置repository为项目ID。部署事件与CI配置文中描述了事件的其余细节。

查看当前运行版本

为每个环境指定版本URL,例如https://app.example.com/version.json。部署成功后,CoRoid 会打开该 URL 并查找对应的提交 SHA 或版本号。报告的提交内容必须与发布提交一致;若不一致,则版本号必须匹配。部署完成期间,CoRoid 会持续检查十分钟,随后显示已验证、版本不符或无法访问显示在当前运行版本下的发布页面上。

该 URL 必须使用 HTTPS 协议且为公开地址。CoRoid 不会跟随重定向,且最多只读取 64 KB 的内容。

让 CoRoid 自动完成相关配置

配置版本标记在版本标记界面点击“新任务”后,系统会为该项目生成针对其技术栈的请求。代理会在构建时读取上述数值,在应用中显示版本号,写入release.json, 声明工作流输入项并在README中记录相关内容。审核该请求后,即可像处理其他任务一样继续推进。