在构建过程中写入版本号

为每个版本分配版本号和构建号，将其传入构建流程，再由 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，因此1.4.0会紧跟在1.4.1之后。首个版本为0.1.0。如有需要，可手动输入其他版本号。
从代码库读取版本号：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_VERSION`	`coroid_version`	版本号
`COROID_BUILD_NUMBER`	`coroid_build_number`	构建号
`COROID_RELEASE_NAME`	`coroid_release_name`	版本名称
`COROID_COMMIT_SHA`	`coroid_commit_sha`	完整的提交哈希值
`COROID_ENVIRONMENT`	`coroid_environment`	环境标识
`COROID_RELEASE_ID`	`coroid_release_id`	Coroid 版本 ID
`COROID_ATTEMPT_ID`	`coroid_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中记录相关内容。审核该请求后，即可像处理其他任务一样继续推进。

在构建过程中写入版本号

1. Coroid 负责命名

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

3. 最终供用户查看使用

4. Coroid 负责验证确认

版本号的来源#

构建流程接收的参数#

编写版本清单文件#

实施方案#

Web 应用（Next.js、Vite）#

服务器与 API#

Docker 镜像#

iOS#

安卓#

Flutter#

Expo和React Native#

上报已部署的版本#

查看当前运行版本#

让Coroid完成相关配置#

相关文档#