GitLab Runner执行Unity Android构建未生成Builds文件夹及APK问题

问题背景 #

在虚拟机上配置GitLab Runner后，提交代码触发CI流水线时，Unity项目的Library和UserSettings文件夹时间戳更新（说明构建过程执行），但未生成目标Builds文件夹及APK，无法上传制品。手动执行相同命令则能正常生成APK。

相关配置与日志 #

.gitlab-ci.yml配置 #

default:
   tags:
       - unity-powershell

# Build the project with Unity using the script defined in unity.executeMethod:
unity-build:
    stage: build
    script:
      - $CI_PROJECT_DIR
      - cd "C:\Program Files\Unity\Hub\Editor\2021.3.17f1\Editor"
      - .\Unity.exe -projectPath $CI_PROJECT_DIR -batchmode -nographics -buildTarget Android -quit -executeMethod BuildScript.PerformBuild -stackTraceLogType Full -logfile 'build.log'
    artifacts:
     paths:
      - $CI_PROJECT_DIR\Builds\*.*

Unity构建脚本（BuildScript.cs） #

{
    [MenuItem("Custom Utilities/Build Android")]
    public static void PerformBuild()
    {
        string[] defaultScenes = {
            "Assets/Scenes/SampleScene.unity" };

        BuildPipeline.BuildPlayer(defaultScenes, "Builds/Build.apk", BuildTarget.Android, BuildOptions.None);
    }
}

手动执行成功的命令 #

.\Unity.exe -projectPath "C:\GitlabRunner\builds\vV58X3nE\0\xr\androidcitestunity2021" -batchmode -nographics -buildTarget Android -quit -executeMethod BuildScript.PerformBuild -log 'build.log'

流水线日志关键片段 #

Executing "step_script" stage of the job script
05:09
$ $CI_PROJECT_DIR
c:\GitLabRunner\builds\vV58X3nE\0\xr\androidcitestunity2021
$ cd "C:\Program Files\Unity\Hub\Editor\2021.3.17f1\Editor"
$ .\Unity.exe -projectPath $CI_PROJECT_DIR -batchmode -nographics -buildTarget Android -quit -executeMethod BuildScript.PerformBuild -stackTraceLogType Full -logfile 'build.log'
Uploading artifacts for successful job
00:02
...
WARNING: c:\GitLabRunner\builds\vV58X3nE\0\xr\androidcitestunity2021\Builds\*.*: no matching files 
ERROR: No files to upload

问题原因 #

1. 工作目录差异：GitLab Runner执行Unity命令时，工作目录是Unity Editor的安装目录，而构建脚本使用相对路径Builds/Build.apk，导致APK被生成到Unity Editor目录下，而非项目目录。
2. 日志参数不匹配：YAML中使用-logfile参数，手动命令用-log，参数差异导致日志未生成，无法排查构建细节错误。
3. 权限缺失：GitLab Runner运行用户可能没有Unity Editor目录的写入权限，导致构建失败但进程未终止（Unity批处理模式下部分错误无明确返回）。
4. 构建无错误反馈：原构建脚本未捕获构建结果，即使构建失败也会让CI任务标记为成功，掩盖问题。

解决办法 #

1. 修正构建脚本的输出路径与错误反馈 #

修改Unity构建脚本，使用绝对路径输出APK，并添加构建结果校验：

using UnityEngine;
using UnityEditor;
using System.IO;

public class BuildScript
{
    [MenuItem("Custom Utilities/Build Android")]
    public static void PerformBuild()
    {
        string[] defaultScenes = { "Assets/Scenes/SampleScene.unity" };
        // 获取项目根目录绝对路径
        string projectRoot = Application.dataPath.Replace("/Assets", "");
        string outputDir = Path.Combine(projectRoot, "Builds");
        string outputPath = Path.Combine(outputDir, "Build.apk");

        // 确保输出目录存在
        Directory.CreateDirectory(outputDir);

        // 执行构建并获取报告
        BuildReport report = BuildPipeline.BuildPlayer(defaultScenes, outputPath, BuildTarget.Android, BuildOptions.None);
        BuildSummary summary = report.summary;

        // 输出构建日志并处理结果
        if (summary.result == BuildResult.Succeeded)
        {
            Debug.Log($"构建成功，输出路径：{outputPath}");
        }
        else
        {
            Debug.LogError($"构建失败，错误数：{summary.totalErrors}");
            // 抛出异常终止CI任务，避免误标记为成功
            throw new System.Exception($"Unity构建失败，共{summary.totalErrors}个错误");
        }
    }
}

2. 调整CI脚本的工作目录与日志配置 #

切换到项目目录执行Unity命令，统一日志参数并将日志纳入制品：

unity-build:
    stage: build
    script:
      - cd $CI_PROJECT_DIR
      - "C:\\Program Files\\Unity\\Hub\\Editor\\2021.3.17f1\\Editor\\Unity.exe" -projectPath $CI_PROJECT_DIR -batchmode -nographics -buildTarget Android -quit -executeMethod BuildScript.PerformBuild -stackTraceLogType Full -logfile "build.log"
    artifacts:
     paths:
      - Builds/*.*
      - build.log
    allow_failure: false

3. 检查GitLab Runner用户权限 #

• 确认GitLab Runner运行用户（默认gitlab-runner）对项目目录和Unity安装目录有读写权限。
• 尝试以管理员身份启动GitLab Runner服务，或手动调整目录权限。

4. 查看构建日志定位细节 #

修改配置后，build.log会生成在项目目录中，可通过CI制品下载查看，定位具体错误（如缺少Android构建模块、场景路径错误等）。

内容的提问来源于stack exchange，提问作者Thomvdm