如何使用GitLab进行多平台开发

使用 GitLab 进行多平台开发

一、总体架构与Runner规划

• 以 GitLab CI/CD 为核心，通过 .gitlab-ci.yml 定义多阶段流水线（如：validate → build → test → package → deploy），在不同平台使用不同的 GitLab Runner（Linux shell/Runner、Windows shell/Runner、macOS shell/Runner）执行作业，实现跨平台构建与发布。GitLab 原生支持在 Unix、Windows、macOS 等平台运行作业，并可并行拆分任务以加速构建。对于需要 iOS 签名/打包的场景，必须使用 macOS Runner；UE 项目在 Windows 上构建 iOS 时，通常通过 SSH 远程到 macOS Runner 完成签名与打包。

二、Runner 与平台矩阵设计

• 平台与 Runner 建议如下（按目标平台划分作业，避免跨平台副作用）：

• 实践要点：
  • 为不同平台分别注册 Runner（tags: linux, windows, macos），在作业中用 tags 精确调度。
  • 使用 并行矩阵 构建多目标（如 JVM/JS/Wasm），显著缩短总时长。
  • 将 构建产物（artifacts） 在阶段间传递，减少重复工作。

三、多平台 CI 示例模板

• 示例要点：
  • 使用 stages 定义流程；用 cache 提升 Gradle/Node 等依赖复用。
  • 通过 rules 控制触发分支与平台矩阵；用 artifacts:paths 传递产物。
  • iOS 作业必须运行在 macOS；UE 的 iOS 打包可通过 SSH 远程到 macOS 执行。

# .gitlab-ci.yml 骨架（可按需裁剪与扩展）
stages:
  - validate
  - build
  - test
  - package

variables:
  GRADLE_USER_HOME: "$CI_PROJECT_DIR/.gradle"
  CACHE_KEY_PREFIX: "gradle"

cache:
  key: "$CACHE_KEY_PREFIX-${CI_COMMIT_REF_SLUG}"
  paths:
    - .gradle/caches/
    - .gradle/wrapper/
    - kotlin-js-store/
    - node_modules/

# 1) 依赖校验（示例：Kotlin 多平台）
dependency-validation:
  stage: validate
  image: openjdk:11
  script:
    - ./gradlew --write-verification-metadata sha256,md5 resolveDependencies
    - git diff --exit-code gradle/verification-metadata.xml

# 2) 多平台并行构建矩阵
build:
  stage: build
  parallel:
    matrix:
      - TARGET: [jvm, js, wasm]
  script:
    - |
      case "$TARGET" in
        jvm)   ./gradlew jvmJar ;;
        js)    ./gradlew jsBrowserProductionWebpack ;;
        wasm)  ./gradlew wasmJsBrowserProductionWebpack ;;
      esac
  artifacts:
    paths:
      - libraries/*/build/libs/*.jar
      - libraries/*/js/build/distributions/
      - libraries/*/wasmJs/build/distributions/

# 3) 测试（示例：按平台拆分）
test-jvm:
  stage: test
  script: ./gradlew test
  needs: [build]

# 4) 打包示例：iOS（必须在 macOS）
package-ios:
  stage: package
  tags: [macos]
  script:
    - xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -sdk iphoneos -configuration Release archive -archivePath build/YourApp.xcarchive
    - xcodebuild -exportArchive -archivePath build/YourApp.xcarchive -exportPath build/ios -exportOptionsPlist exportOptions.plist
  artifacts:
    paths:
      - build/ios/*.ipa
    expire_in: 30 days

# 5) 可选：UE 项目 iOS 远程打包（Windows 构建机通过 SSH 触发 macOS Runner）
# 在 Windows Runner 上：
ue-build-ios-remote:
  stage: package
  tags: [windows]
  script:
    - ssh $MACOS_RUNNER_USER@$MACOS_RUNNER_HOST "cd $PROJECT_DIR && $UE_PATH/Engine/Binaries/DotNET/UnrealBuildTool.exe YourProject iOS Development"
    - ssh $MACOS_RUNNER_USER@$MACOS_RUNNER_HOST "cd $PROJECT_DIR && xcodebuild -workspace YourProject.xcworkspace -scheme YourProject -sdk iphoneos -configuration Release archive -archivePath build/YourProject.xcarchive"
    - ssh $MACOS_RUNNER_USER@$MACOS_RUNNER_HOST "xcodebuild -exportArchive -archivePath build/YourProject.xcarchive -exportPath build/ios -exportOptionsPlist exportOptions.plist"
  artifacts:
    paths:
      - build/ios/*.ipa

• 说明：
  • Kotlin Multiplatform 可在同一流水线中并行构建 JVM/JS/Wasm 等目标，并通过缓存与产物传递优化时长与一致性。
  • iOS 打包强制依赖 macOS；UE 的 iOS 打包常见做法是 Windows 构建 + SSH 远程到 macOS 完成签名与 Archive。

四、安全与证书管理

• 将敏感信息放入 GitLab CI/CD Variables（Masked、Protected），如：SSH 私钥、Apple 证书/描述文件（.p12/.mobileprovision）、UE 打包密钥 等；在作业中通过环境变量或 SSH 使用。
• iOS 签名与证书：
  • 使用 SSH 登录 macOS Runner 时，将私钥配置为 SSH Key（GitLab 变量），并在 macOS 上配置好 钥匙串与证书信任，确保无交互签名。
  • 通过 exportOptionsPlist 指定 provisioningProfiles 与 signingCertificate，实现自动化 Archive/Export。
• UE 项目：
  • 在 macOS Runner 上预装 UE 与 iOS 工具链，证书导入后由脚本自动选择并完成打包。
• 建议对 Runner 使用专用账号与最小权限，并开启 审计日志 与 定期轮换密钥。

五、协作与本地开发环境

• 跨平台协作流程：
  • 使用 SSH 密钥 或 Personal Access Token 进行身份认证；在 Merge Request 中完成 代码审查、CI 流水线验证、自动化测试 后再合并。
  • 通过 Git 分支策略（main/develop/feature） 与 保护分支 保证主干质量。
• 本地开发环境建议：
  • Windows/macOS/Linux 均安装 Git，配置 用户名/邮箱，并将 SSH 公钥 添加到 GitLab；克隆、提交、推送与拉取代码按常规 Git 流程进行。
  • 各平台安装对应 构建工具链（如 JDK、Xcode、Visual Studio、.NET SDK、Node/Yarn、UE），确保本地与 CI 环境一致（版本、SDK 路径、环境变量）。