unity-build-pipeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity Build Pipeline

Configure, script, and automate Unity 6 player builds: scenes, platform target, scripting backend, stripping, and headless/CI builds. Targets Unity 6 (6000.0 LTS).

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

When to use

适用场景

Use when setting up Build Settings/Profiles, choosing a platform and scripting backend (Mono vs IL2CPP), reducing build size with managed stripping, scripting a repeatable build with
```
BuildPipeline.BuildPlayer
```
, or wiring a CI/headless build.
Use when the project has
```
ProjectSettings/EditorBuildSettings.asset
```
or a CI build script.

When not to use: authoring a CI service config end-to-end is DevOps; this skill covers the Unity-side build API and settings. Console/platform certification specifics are platform-NDA territory. Storefront submission →

steam-publish

itch-publish

适用于设置构建配置/参数、选择平台与脚本后端（Mono vs IL2CPP）、通过托管代码剥离缩小包体、使用
```
BuildPipeline.BuildPlayer
```
编写可重复执行的构建脚本，或配置CI/无头构建时。
适用于项目包含
```
ProjectSettings/EditorBuildSettings.asset
```
或CI构建脚本的场景。

不适用场景： 端到端编写CI服务配置属于DevOps范畴；本技能仅覆盖Unity端的构建API与设置。主机/平台认证细节属于平台保密协议内容。商店提交请使用

steam-publish

itch-publish

。

Core workflow

核心工作流程

List the scenes to build (File → Build Profiles/Settings → Scene List, or
```
EditorBuildSettings.scenes
```
). Only listed, enabled scenes ship; scene 0 is the start scene.
Pick the platform target and switch the active build target if needed (
```
BuildTarget
```
/
```
EditorUserBuildSettings
```
).
Choose the scripting backend (Player Settings): Mono (fast iteration, desktop) vs IL2CPP (AOT C++; required for many platforms, better perf, harder to reverse). IL2CPP needs the platform's C++ toolchain installed.
Tune size/perf: set Managed Stripping Level (Disabled → Minimal → Low → Medium → High) and protect reflection-only code with a
```
link.xml
```
. Set Quality Settings per platform.
Script the build with
```
BuildPipeline.BuildPlayer(BuildPlayerOptions)
```
and inspect the returned
BuildReport
— a non-
```
Succeeded
```
result must fail your pipeline.
Run headless for CI with
```
-batchmode -quit -executeMethod
```
, and check the exit code.
Verify the actual output runs (launch the player), not just that the build returned without throwing.

列出需构建的场景（文件→构建配置/设置→场景列表，或
```
EditorBuildSettings.scenes
```
）。仅已列出且启用的场景会被打包；场景0为启动场景。
选择平台目标，必要时切换活跃构建目标（
```
BuildTarget
```
/
```
EditorUserBuildSettings
```
）。
选择脚本后端（玩家设置）：Mono（迭代速度快，适用于桌面平台） vs IL2CPP（AOT C++；为众多平台所需，性能更优，反编译难度大）。IL2CPP需要安装对应平台的C++工具链。
调整包体大小/性能：设置托管代码剥离级别（Disabled → Minimal → Low → Medium → High），并使用
```
link.xml
```
保护仅通过反射调用的代码。为各平台设置质量参数。
使用
BuildPipeline.BuildPlayer(BuildPlayerOptions)
编写构建脚本，并检查返回的
BuildReport
——若结果非
```
Succeeded
```
，必须终止流水线。
用于CI的无头运行：使用
```
-batchmode -quit -executeMethod
```
参数，并检查退出码。
验证：确保实际输出的玩家端可正常运行（启动玩家端），而非仅确认构建未抛出错误。

Patterns

模式示例

1. Scripted build with a result check

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

csharp

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}");
    }
}

csharp

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,            // 若为开发构建，添加BuildOptions.Development
        };

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

        if (summary.result != BuildResult.Succeeded)
            throw new System.Exception($"构建失败：{summary.totalErrors} 个错误");
        Debug.Log($"构建完成：{summary.totalSize} 字节，耗时{summary.totalTime}");
    }
}

2. Headless / CI invocation

2. 无头/CI调用

bash

undefined

bash

undefined

Exit code is 0 on success; -quit ensures the editor closes; -nographics for build servers.

成功时退出码为0；-quit确保编辑器关闭；-nographics用于构建服务器。

Unity -batchmode -quit -nographics
-projectPath "/path/to/Project"
-executeMethod BuildScript.BuildWindows
-logFile -

undefined

Unity -batchmode -quit -nographics
-projectPath "/path/to/Project"
-executeMethod BuildScript.BuildWindows
-logFile -

undefined

3. Protect stripped code with

link.xml

3. 使用

link.xml

保护被剥离的代码

xml

<!-- Assets/link.xml — keep types the linker can't see are used (reflection, JSON, plugins). -->
<linker>
  <assembly fullname="MyGameRuntime" preserve="all"/>
</linker>

xml

<!-- Assets/link.xml — 保留链接器无法识别使用情况的类型（反射、JSON、插件）。 -->
<linker>
  <assembly fullname="MyGameRuntime" preserve="all"/>
</linker>

Pitfalls

常见陷阱

A scene loads in the Editor but is missing in the build — it isn't in the Build Settings scene list (or is disabled).
```
SceneManager.LoadScene
```
only sees listed scenes.
IL2CPP build fails on a fresh machine — the platform C++ toolchain (e.g. Windows build tools, Android NDK) isn't installed. Mono has no such requirement.
MissingMethodException
/
TypeLoadException
only in the build — managed stripping removed reflection-only code. Lower the stripping level or add a
```
link.xml
```
preserve entry.
Treating "BuildPlayer returned" as success — always check
```
BuildReport.summary.result
```
; it can return with errors.
Addressables content is stale/missing — Addressables (
```
com.unity.addressables
```
) need a separate content build (Build → Addressables) and a profile pointing at the right load path; a player build alone doesn't rebuild them.
Shipping a Development build —
```
BuildOptions.Development
```
enables the profiler/debugging and is slower; use
```
BuildOptions.None
```
for release.

编辑器中可加载场景，但构建包中缺失——该场景未加入构建设置的场景列表（或已被禁用）。
```
SceneManager.LoadScene
```
仅能识别已列出的场景。
新机器上IL2CPP构建失败——未安装对应平台的C++工具链（如Windows构建工具、Android NDK）。Mono无此要求。
仅在构建包中出现
MissingMethodException
/
TypeLoadException
——托管代码剥离移除了仅通过反射调用的代码。降低剥离级别或在
```
link.xml
```
中添加保留条目。
将“BuildPlayer返回”视为成功——务必检查
```
BuildReport.summary.result
```
；即使返回结果也可能存在错误。
Addressables内容过时/缺失——Addressables (
```
com.unity.addressables
```
)需要单独进行内容构建（构建→Addressables），且需配置指向正确加载路径的参数；仅玩家端构建不会重新生成Addressables内容。
发布开发构建包——
```
BuildOptions.Development
```
会启用分析器/调试功能，且运行速度较慢；发布版本请使用
```
BuildOptions.None
```
。

References

参考资料

For a complete multi-platform CI build script (target switching, version stamping, argument parsing, exit codes) and an Addressables content-build call, read
```
references/ci-build-script.md
```
.
Primary docs:
```
ScriptReference/BuildPipeline.BuildPlayer
```
, Unity Manual build sections (player settings, managed code stripping).

如需完整的多平台CI构建脚本（目标切换、版本标记、参数解析、退出码）以及Addressables内容构建调用，请阅读
```
references/ci-build-script.md
```
。
主要文档：
```
ScriptReference/BuildPipeline.BuildPlayer
```
、Unity手册构建章节（玩家设置、托管代码剥离）。

unity-build-pipeline

Original

Translation

Unity Build Pipeline

Unity Build Pipeline

When to use

适用场景

Core workflow

核心工作流程

Patterns

模式示例

1. Scripted build with a result check

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

2. Headless / CI invocation

2. 无头/CI调用

Exit code is 0 on success; -quit ensures the editor closes; -nographics for build servers.

成功时退出码为0；-quit确保编辑器关闭；-nographics用于构建服务器。

3. Protect stripped code with
`link.xml`

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

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能

unity-build-pipeline

Original

Translation

Unity Build Pipeline

Unity Build Pipeline

When to use

适用场景

Core workflow

核心工作流程

Patterns

模式示例

1. Scripted build with a result check

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

2. Headless / CI invocation

2. 无头/CI调用

Exit code is 0 on success; -quit ensures the editor closes; -nographics for build servers.

成功时退出码为0；-quit确保编辑器关闭；-nographics用于构建服务器。

3. Protect stripped code with link.xml

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

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能

3. Protect stripped code with
`link.xml`

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