使用 Jenkins 自建模组构建
中文 | English
需要由自己的 Windows 构建机处理模组时,用 Jenkins 调度 本地构建清单。官方仓库使用 GitHub Actions 的 Build modpack。
1. 安装服务并完成首次设置
- 在构建机安装该 Jenkins LTS 支持的 Java,再下载并运行 Windows MSI。按向导选择安装目录。服务账户需要 Log on as a service 权限。填写该机的本地或域账户,完成 Java Home 和端口设置。Jenkins Windows 安装
- 完成安装后,在 Windows 服务中确认 Jenkins 已启动。如果之后修改服务配置,用同一处的 Restart 重新启动。浏览器打开本机配置的端口,默认是
http://localhost:8080。 - 在初次 Unlock Jenkins 页面,读取提示位置的
initialAdminPassword并填入。选择 Install suggested plugins,或在 Select plugins to install 自选。安装完成后保存首个管理员账户,再进入 Jenkins。使用下面的 Pipeline 方式时,可以直接调用 Unity,可选插件按需要安装。
2. 配置构建机和清单
- 安装 Git、Git LFS、SDK 要求的 Unity和目标平台的模块。用 Jenkins 服务账户确认该账号能读取工程并运行 Unity。把该版本的
Unity.exe完整路径设到构建机的UNITY_EXE环境变量。 - 在 Unity 项目中提交 ModPackageBuildPiplineData 和
CI/ModBuild.json。按构建清单示例把平台填为StandaloneWindows64,输出到Build/Ship/Windows。第一次运行时先让输出目录保持空白。 - 在 Unity 工程添加
Assets/Editor/CiModBuild.cs,将下方方法作为-executeMethod的入口。清单路径由命令传入。
using System;
using System.IO;
using ShanghaiWindy.Editor;
public static class CiModBuild
{
public static void Run()
{
var args = Environment.GetCommandLineArgs();
var index = Array.IndexOf(args, "-modManifest");
if (index < 0 || index + 1 >= args.Length)
{
throw new ArgumentException("Supply -modManifest followed by the JSON path.");
}
Utility_BuildPipline.BuildPiplineManifest(Path.GetFullPath(args[index + 1]));
}
}
3. 建立 Pipeline 并验收
- 在 Unity 项目中把脚本保存为
CI/Build-Mod.ps1。Unity 2022.3 命令行使用Win64,构建清单仍填写StandaloneWindows64。Unity 编辑器命令行参数
$ErrorActionPreference = 'Stop'
$project = (Resolve-Path .).Path
$manifest = Join-Path $project 'CI/ModBuild.json'
$output = Join-Path $project 'Build/Ship/Windows'
$log = Join-Path $project 'Build/UnityBuild.log'
New-Item -ItemType Directory -Path $output -Force | Out-Null
if (Get-ChildItem -LiteralPath $output -Filter '*.modpack' -File) {
throw "Use a clean output directory before building: $output"
}
$arguments = @(
'-batchmode', '-quit', '-projectPath', ('"' + $project + '"'),
'-buildTarget', 'Win64', '-executeMethod', 'CiModBuild.Run',
'-modManifest', ('"' + $manifest + '"'), '-logFile', ('"' + $log + '"')
)
$build = Start-Process -FilePath $env:UNITY_EXE -ArgumentList $arguments -Wait -PassThru -WindowStyle Hidden
if ($build.ExitCode -ne 0) { throw "Unity exited with $($build.ExitCode). See $log" }
if (-not (Get-ChildItem -LiteralPath $output -Filter '*.modpack' -File)) {
throw "No .modpack in $output. Check the manifest's target platform and directory."
}
- 在 Jenkins 新建 Pipeline 任务,选择 Pipeline script from SCM。将以下
Jenkinsfile保存到仓库根目录,将windows-unity改成 Windows agent 的标签。Checkout 阶段会在检出之前清理该任务的专用构建工作区,保证每轮都有干净的输出目录。如果 Unity 工程在子目录,用dir('工程子目录')包住 PowerShell 构建步骤,并在归档路径前加上子目录。Jenkinsfile 指南 · PowerShell 步骤
pipeline {
agent { label 'windows-unity' }
options { skipDefaultCheckout() }
stages {
stage('Checkout') {
steps {
deleteDir()
checkout scm
bat 'git lfs pull'
}
}
stage('Build mods') {
steps {
powershell '& ./CI/Build-Mod.ps1'
archiveArtifacts artifacts: 'Build/Ship/Windows/*.modpack'
}
}
}
post {
always {
archiveArtifacts artifacts: 'Build/UnityBuild.log', allowEmptyArchive: true
}
}
}
- 用一个教学模组触发 Build Now。从产物中打开
Build/UnityBuild.log,确认活动平台、构建的模组名和输出目录。分发前按构建清单教程生成同名.modpack.json,与归档一起保存,并核对每个包的 GUID、版本和目标平台。