unity-build-pipeline

Unity 构建流水线

配置、编写脚本并自动化 Unity 6.3 LTS Player 构建：场景、平台目标、脚本后端、代码剥离，以及无头/CI 构建。目标版本为 Unity 6.3 LTS (6000.3)。

适用场景

• 设置 Build Settings/Profiles、选择平台和脚本后端（Mono 与 IL2CPP）、通过托管代码剥离缩减构建体积、使用 BuildPipeline.BuildPlayer 编写可重复构建脚本，或配置 CI/无头构建时使用。
• 项目中存在 ProjectSettings/EditorBuildSettings.asset 或 CI 构建脚本时使用。

不适用场景： 从头到尾编写 CI 服务配置属于 DevOps；此技能涵盖 Unity 侧的构建 API 和设置。主机/平台认证的具体要求属于平台 NDA 范畴。商店发布 → steam-publish / itch-publish。

核心工作流

1. 列出要构建的场景（File → Build Profiles/Settings → Scene List，或 EditorBuildSettings.scenes）。只有已列出且启用的场景才会打包；场景 0 是起始场景。
2. 选择平台目标，并在需要时切换当前构建目标（BuildTarget / EditorUserBuildSettings）。
3. 选择脚本后端（Player Settings）：Mono（迭代快，适用于桌面端）或 IL2CPP（AOT C++；许多平台都要求使用，性能更好，但更难逆向）。IL2CPP 需要安装对应平台的 C++ 工具链。（前瞻说明：Unity 正在开发 CoreCLR 后端，作为 Mono 的现代 .NET 运行时继任者，但截至 Unity 6.7，该后端仍处于实验性阶段，仅支持桌面端，尚未达到生产就绪状态——因此对于 6.3 LTS，仍需在 Mono 与 IL2CPP 之间选择。）
4. **调整体积/性能：**设置 Managed Stripping Level（Disabled → Minimal → Low → Medium → High），并使用 link.xml 保护仅通过反射访问的代码。按平台设置 Quality Settings。
5. 使用 BuildPipeline.BuildPlayer(BuildPlayerOptions) 编写构建脚本，并检查返回的 BuildReport——任何非 Succeeded 结果都必须导致流水线失败。
6. CI 中使用 -batchmode -quit -executeMethod 运行无头构建，并检查退出代码。
7. 验证实际输出是否能运行（启动 Player），而不只是确认构建没有抛出异常。

常见模式

1. 带结果检查的脚本化构建

using UnityEditor;
using UnityEditor.Build.Reporting;
using UnityEngine;

public static class BuildScript
{
    [MenuItem("Build/Windows x64")]
    public static void BuildWindows()
    {
        var options = new BuildPlayerOptions
        {
            scenes = new[] { "Assets/Scenes/Main.unity", "Assets/Scenes/Level1.unity" },
            locationPathName = "Builds/Windows/Game.exe",
            target = BuildTarget.StandaloneWindows64,
            options = BuildOptions.None,            // add BuildOptions.Development for a dev build
        };

        BuildReport report = BuildPipeline.BuildPlayer(options);
        BuildSummary summary = report.summary;

        if (summary.result != BuildResult.Succeeded)
            throw new System.Exception($"Build failed: {summary.totalErrors} errors");
        Debug.Log($"Build OK: {summary.totalSize} bytes in {summary.totalTime}");
    }
}

2. 无头 / CI 调用

# Exit code is 0 on success; -quit ensures the editor closes; -nographics for build servers.
Unity -batchmode -quit -nographics \
  -projectPath "/path/to/Project" \
  -executeMethod BuildScript.BuildWindows \
  -logFile -

3. 使用 link.xml 保护被剥离的代码

<linker>
  <assembly fullname="MyGameRuntime" preserve="all"/>
</linker>

易踩问题

• 场景在 Editor 中能加载，但构建中缺失——该场景未列入 Build Settings 场景列表（或已禁用）。SceneManager.LoadScene 只能加载列表中的场景。
• 在新机器上 IL2CPP 构建失败——未安装平台 C++ 工具链（例如 Windows 构建工具、Android NDK）。Mono 没有此要求。
• 仅在构建中出现 MissingMethodException/TypeLoadException——托管代码剥离移除了仅通过反射访问的代码。降低剥离级别，或添加 link.xml 保留项。
• 将“BuildPlayer 已返回”视为成功——务必检查 BuildReport.summary.result；即使存在错误，它也可能返回。
• Addressables 内容过时/缺失——Addressables（com.unity.addressables）需要单独构建内容（Build → Addressables），并使用指向正确加载路径的配置文件；仅构建 Player 不会重新构建 Addressables 内容。
• 发布 Development 构建——BuildOptions.Development 会启用 Profiler/调试功能，且速度较慢；发布时使用 BuildOptions.None。

参考资料

• 如需完整的多平台 CI 构建脚本（目标切换、版本标记、参数解析、退出代码）以及 Addressables 内容构建调用，请阅读 references/ci-build-script.md。
• 主要文档：ScriptReference/BuildPipeline.BuildPlayer、Unity Manual 的构建章节（Player 设置、托管代码剥离）。有关前瞻性的 CoreCLR 后端，请参阅以下实验性说明： https://docs.unity3d.com/6000.7/Documentation/Manual/scripting-backends-coreclr.html。

相关技能

• steam-publish / itch-publish — 分发刚构建的游戏。
• unity-csharp-scripting — 构建脚本使用的编辑器脚本约定。