Version: 2019.2
构建播放器管线
批处理模式和内置协程兼容性

命令行参数

可以从命令行运行 Unity(从 macOS 终端或 Windows 命令提示符)。

macOS 上,在终端中输入以下命令来启动 Unity:

/Applications/Unity/Unity.app/Contents/MacOS/Unity

Windows 上,在命令提示符下输入以下命令来启动 Unity:

C:\Program Files\Unity\Editor\Unity.exe

以这种方式启动时,Unity 会在启动时收到命令和信息,这对于测试套件、自动构建和其他生产任务非常有用。
注意:使用相同方法来启动独立平台 Unity 游戏。

以静默方式启动 Unity

macOS 上的终端中输入以下命令以静默方式启动 Unity:

/Applications/Unity/Unity.app/Contents/MacOS/Unity -quit -batchmode -serial SB-XXXX-XXXX-XXXX-XXXX-XXXX -username 'JoeBloggs@example.com' -password 'MyPassw0rd'

注意:使用 Jenkins 之类的连续集成 (CI) 工具通过命令行激活时,请添加 -nographics 标志以防止 WindowServer 错误。

Windows 上的命令提示符下输入以下命令以静默方式启动 Unity:

Windows: C:\Program Files\Unity\Editor\Unity.exe" -batchmode -username name@example.edu.uk - password XXXXXXXXXXXXX -serial E3-XXXX-XXXX-XXXX-XXXX-XXXX –quit

将许可证退回到许可证服务器

macOS 上的终端中输入以下命令来退回许可证:

/Applications/Unity/Unity.app/Contents/MacOS/Unity -quit -batchmode -returnlicense

Windows 上的命令提示符下输入以下命令来退回许可证:

"C:\Program Files\Unity\Editor\Unity.exe" -quit -batchmode -returnlicense

创建激活文件并用命令导入许可证文件

macOS 上的终端中输入以下命令:

/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -createManualActivationFile -logfile

/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -manualLicenseFile <yourulffile> -logfile

Windows 上的命令提示符下输入以下命令:

"C:\Program Files\Unity\Editor\Unity.exe" -batchmode -createManualActivationFile -logfile

"C:\Program Files\Unity\Editor\Unity.exe" -batchmode -manualLicenseFile <yourulffile> -logfile

请查看手动激活指南以了解更多详细信息。 ​

选项

可以在启动时运行 Editor 并使用其他命令和信息构建 Unity 游戏。本部分将介绍可用的命令行选项。

命令 详细信息
-assetServerUpdate <IP[:port] projectName username password [r <revision>]> 强制更新 IP:port 指定的资源服务器 (Asset Server) 中的项目。端口是可选的,如果未指定,则假定其为标准端口 (10733)。建议将此命令与 -projectPath 参数结合使用,以确保使用正确的项目。如果未指定项目名称,那么命令行将使用 Unity 打开的最后一个项目。如果 -projectPath 指定的路径中不存在项目,则命令行会自动创建一个项目。
-batchmode 以批处理模式运行 Unity。应始终将此命令与其他命令行参数结合使用,因为此命令可确保不会出现弹出窗口且无需任何人为干预。在执行脚本代码期间发生异常时,资源服务器更新失败时,或其他操作失败时,Unity 将立即退出并返回代码 1
请注意,在批处理模式下,Unity 会将其日志输出的最小版本发送到控制台。但是,日志文件仍包含完整的日志信息。当 Editor 打开某个项目时,您无法以批处理模式打开相同的项目;一次只能运行一个 Unity 实例。
提示__:要检查是否正在以批处理模式运行 Editor 或独立平台播放器,请使用 Application.isBatchMode 运算符。

如果在使用 -batchmode 时还没有导入项目,则目标平台为默认平台。要在使用 -batchmode 时强制选择其他平台,请使用 -buildTarget 选项。| |-buildLinux32Player <pathname>|构建 32 位独立平台 Linux 播放器(例如,-buildLinux32Player path/to/your/build)。| |-buildLinux64Player <pathname>|构建 64 位独立平台 Linux 播放器(例如,-buildLinux64Player path/to/your/build)。| |-buildLinuxUniversalPlayer <pathname>|构建 32 位和 64 位组合独立平台 Linux 播放器(例如,-buildLinuxUniversalPlayer path/to/your/build)。| |-buildOSXPlayer <pathname>|构建 32 位独立平台 Mac OSX 播放器(例如,-buildOSXPlayer path/to/your/build.app)。| |-buildOSX64Player <pathname>|构建 64 位独立平台 Mac OSX 播放器(例如,-buildOSX64Player path/to/your/build.app)。| |-buildOSXUniversalPlayer <pathname>|构建 32 位和 64 位组合独立平台 Mac OSX 播放器(例如,-buildOSXUniversalPlayer path/to/your/build.app)。| |-buildTarget <name>|允许在加载项目之前选择有效的构建目标。可能的选项包括:
standalone、Win、Win64、OSXUniversal、Linux、Linux64、LinuxUniversal、iOS、Android、Web、WebStreamed、WebGL、XboxOne、PS4、WindowsStoreApps、Switch、N3DS、tvOS。 | |-buildWindowsPlayer <pathname>|构建 32 位独立平台 Windows 播放器(例如,-buildWindowsPlayer path/to/your/build.exe)。| |-buildWindows64Player <pathname>|构建 64 位独立平台 Windows 播放器(例如,-buildWindows64Player path/to/your/build.exe)。| |-stackTraceLogType|详细的调试功能。StackTraceLogging 允许进行详细日志记录。所有设置都允许选择
NoneScript Only__ 和 Full。(例如 -stackTraceLogType Full
-CacheServerIPAddress <host:port> 在启动时连接到指定的缓存服务器,这将覆盖 Editor Preferences 中存储的配置。使用此命令可将 Unity 的多个实例连接到不同缓存服务器。
-createProject <pathname> 在指定路径中创建一个空项目。
-editorTestsCategories 按类别过滤 Editor 测试。使用逗号分隔测试类别。
-editorTestsFilter 按名称过滤 Editor 测试。使用逗号分隔测试名称。
-editorTestsResultFile 存放结果文件的路径位置。如果路径是文件夹,则命令行使用默认文件名。如果未指定,则将结果放在项目的根文件夹中。
-diag-debug-shader-compiler Unity 仅启动一个着色器编译器实例,并将其超时强制为一小时。对于调试着色器编译器问题很有用。
-enableCodeCoverage 启用代码覆盖率并允许访问 Coverage API
-executeMethod <ClassName.MethodName> Unity 打开项目后以及可选的资源服务器更新完成后,立即执行静态方法。可以使用此命令来执行连续集成,执行单元测试,进行构建或准备数据等任务。要从命令行进程返回错误,要么抛出异常(这会导致 Unity 退出并显示返回代码 __1__),要么调用 EditorApplication.Exit(这会显示非零返回代码)。要传递参数,请将它们添加到命令行,并使用 System.Environment.GetCommandLineArgs 在函数内检索它们。要使用 -executeMethod,需要将包裹脚本放在 Editor 文件夹中。执行的方法必须定义为 static
-exportPackage <exportAssetPath1 exportAssetPath2 ExportAssetPath3 exportFileName> 在指定路径(或指定路径集)的情况下导出资源包。在此示例中,exportAssetPath 是要从 Unity 项目导出的文件夹(相对于 Unity 项目根目录),exportFileName 是资源包名称。目前,此选项一次只导出整个文件夹。通常需要将此命令与 -projectPath 参数一起使用。
-force-d3d11(仅限 Windows) 使 Editor 使用 Direct3D 11 进行渲染。通常,图形 API 取决于 Player 设置(通常默认为 D3D11)。
-force-device-index 使用 Metal 时,通过传递 GPU 设备的索引,让 Editor 使用特定 GPU 设备(仅限 macOS)。
-force-gfx-metal 使 Editor 使用 Metal 作为默认图形 API(仅限 macOS)。
-force-glcore 使 Editor 使用 OpenGL 3/4 Core 配置文件进行渲染。Editor 会尝试使用可用的最佳 OpenGL 版本以及 OpenGL 驱动程序公开的所有 OpenGL 扩展。如果不支持该平台,则使用 Direct3D。
-force-glcoreXY -force-glcore 类似,但请求特定的 OpenGL 上下文版本。XY 的可接受值:32、33、40、41、42、43、44 或 45。
-force-gles(仅限 Windows) 使 Editor 使用 OpenGL for Embedded Systems 进行渲染。Editor 会尝试使用可用的最佳 OpenGL ES 版本以及 OpenGL 驱动程序公开的所有 OpenGL ES 扩展。
-force-glesXY(仅限 Windows) -force-gles 类似,但请求特定的 OpenGL ES 上下文版本。XY 的可接受值:30、31 或 32。
-force-clamped -force-glcoreXY 一起使用以防止检查其他 OpenGL 扩展,允许在具有相同代码路径的平台之间运行。
-force-free 使 Editor 运行,就像机器上有免费的 Unity 许可证一样,即使安装了 Unity Pro 许可证也是如此。
-force-low-power-device 使用 Metal 时,让 Editor 使用低功耗设备(仅限 macOS)。
-importPackage <pathname> 导入指定的资源包。不显示导入对话框。
-logFile <pathname> Specify where Unity writes the Editor or Windows/Linux/OSX standalone log file. To output to the console, specify - for the path name. On Windows, specify - option to ensure output goes to stdout, which is not the console by default.
-nographics 在批处理模式下运行时,完全不初始化图形设备。这样,即使在没有 GPU 的机器上也能运行自动化工作流程(自动工作流程仅在有窗口获得焦点时才起作用,否则无法发送模拟输入命令)。请注意,-nographics 不允许烘焙 GI,因为 Enlighten 需要 GPU 加速。
-noUpm 禁用 Unity Package Manager。
-password <password> 在激活 Unity Editor 期间,在登录窗体中输入密码。
-projectPath <pathname> 在指定路径下打开项目。
-quit 在其他命令执行完毕后退出 Unity Editor。请注意,这可能导致错误消息被隐藏(但是,它们仍会出现在 Editor.log 文件中)。
-returnlicense 将当前激活的许可证退回到许可证服务器。在删除许可证文件前请留出几秒钟,因为 Unity 需要与许可证服务器通信。
-runEditorTests 从项目中运行 Editor 测试。这个参数需要 projectPath,并且最好与 batchmode 参数一起运行。quit 不是必需的,因为 Editor 在运行完后自动关闭。
-serial <serial> Activate Unity with the specified serial key. When using this to automatically activate Unity, you must pass the -batchmode, and it is good practice to pass the -quit argument. Please allow a few seconds before the license file is created, because Unity needs to communicate with the license server. Make sure that license file folder exists, and has appropriate permissions before running Unity with this argument. If activation fails, see the Editor.log for info.
-setDefaultPlatformTextureFormat 在导入纹理或构建项目之前,将默认纹理压缩设置为所需的格式。这样就不必再使用所需的格式导入纹理。可用的格式为 dxt、pvrtc、atc、etc、etc2 和 astc。
请注意,这仅在 Android 上受支持。
-silent-crashes 阻止 Unity 显示独立平台播放器崩溃时出现的对话框。希望在自动的构建或测试中运行播放器时(此时不希望对话框提示阻碍自动化过程),此参数非常有用。
-username <username> 在激活 Unity Editor 期间,在登录窗体中输入用户名。
-disable-assembly-updater <assembly1 assembly2> 指定一个以空格分隔的程序集名称列表作为 Unity 在自动更新时忽略的参数。
以空格分隔的程序集名称列表是可选的:如果传递命令行选项时不带任何程序集名称,表示忽略所有程序集,如示例 1 所示。

示例 1
unity.exe -disable-assembly-updater

示例 2 有两个程序集名称,其中一个具有路径名。示例 2 无论 A1.dll 存储在哪个文件夹中都会将其忽略,但只有 A2.dll 存储在 subfolder 文件夹下时才会将其忽略:

示例 2
unity.exe -disable-assembly-updater A1.dll subfolder/A2.dll

如果在 -disable-assembly-updater 命令行参数中列出程序集(或者如果不指定程序集),Unity 会将以下消息记录到 Editor.log

[Assembly Updater] warning: Ignoring assembly [assembly_path] as requested by command line parameter.").

可用于在导入程序集时避免不必要的 API Updater 开销。

如果知道 Unity API 不需要更新,对于导入访问 Unity API 的程序集非常有用。在导入完全不访问 Unity API 的程序集时也很有用(例如,如果在 Unity 之外构建了游戏源代码或其中部分代码,并且想要将生成的程序集导入到 Unity 项目中)。

注意:如果对任何需要更新的程序集禁用更新,则可能会在编译时和/或运行时都出现难以跟踪的错误。
-accept-apiupdate 使用此命令行选项可指定在批处理模式下启动 Unity 时应运行 APIUpdater。

示例:

unity.exe -accept-apiupdate -batchmode [other params]

在批处理模式下启动 Unity 时省略此命令行参数会导致 APIUpdater 不运行,从而导致编译器错误。请注意,在 2017.2 之前的版本中,以批处理模式启动 Unity 时,无法运行 APIUpdater。

示例

C#:

using UnityEditor;
class MyEditorScript
{
     static void PerformBuild ()
     {
         string[] scenes = { "Assets/MyScene.unity" };
         BuildPipeline.BuildPlayer(scenes, ...);
     }
}

以下命令以批处理模式执行 Unity,执行 MyEditorScript.PerformBuild 方法,然后在完成时退出。

Windows:

C:\program files\Unity\Editor\Unity.exe -quit -batchmode -executeMethod MyEditorScript.PerformBuild

Mac OS:

/Applications/Unity/Unity.app/Contents/MacOS/Unity -quit -batchmode -executeMethod MyEditorScript.PerformBuild

以下命令以批处理模式执行 Unity,并使用提供的项目路径从资源服务器更新。从资源服务器下载并导入所有资源后执行该方法。函数执行完毕后,Unity 会自动退出。

/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -projectPath ~/UnityProjects/AutobuildProject -assetServerUpdate 192.168.1.1 MyGame AutobuildUser l33tpa33 -executeMethod MyEditorScript.PerformBuild -quit

Unity Editor 特殊命令行参数

应该只在特殊情况下或者在 Unity 支持人员的指导下使用这些命令行参数。

命令 详细信息
-enableIncompatibleAssetDowngrade 如果资源由较新的不兼容 Unity 版本制作而成,并希望将其降级以便与当前版本的 Unity 一起使用,请使用此选项。启用此选项后,如果尝试打开需要该资源的项目,Unity 会显示一个对话框,要求确认此降级。
注意:此过程不受支持且风险很高,应仅用作最后的手段。

Unity 独立平台播放器命令行参数

使用 Unity 构建的独立平台播放器也能识别一些命令行参数:

命令 详细信息
-adapter N(仅限 Windows) 允许游戏在另一个显示屏上全屏运行。N 映射到 Direct3D 显示适配器。在大多数情况下,适配器和视频卡之间存在一对一的关系。在支持多头显示器的显卡上(也就是说,可以通过一张卡驱动多个显示器),每个“头”可能是它自己的适配器。
-batchmode 以“无头”模式运行游戏。游戏不显示任何内容,也不接受用户输入。最适合用于运行联网游戏的服务器。
-force-d3d11(仅限 Windows) 强制游戏使用 Direct3D 11 进行渲染。
-force-d3d11-singlethreaded 强制在使用 D3D11_CREATE_DEVICE_SINGLETHREADED 标志的情况下创建 DirectX 11.0。
-force-device-index 通过向独立平台播放器传递 GPU 设备的索引,使该播放器使用特定 GPU 设备(仅限 macOS)。
-force-gfx-metal 使独立平台播放器使用 Metal 作为默认图形 API(仅限 macOS)。
-force-glcore 强制 Editor 使用 OpenGL Core 配置文件进行渲染。Editor 会尝试使用可用的最佳 OpenGL 版本以及 OpenGL 驱动程序公开的所有 OpenGL 扩展。如果不支持该平台,则使用 Direct3D。
-force-glcoreXY -force-glcore 类似,但请求特定的 OpenGL 上下文版本。XY 的可接受值:32、33、40、41、42、43、44 或 45。
-force-clamped -force-glcoreXY 一起使用,可防止检查其他 OpenGL 扩展,允许在具有相同代码路径的平台之间运行。
-force-low-power-device 使独立平台播放器使用低功耗设备(仅限 macOS)。
-force-wayland 运行 Linux 播放器时激活实验性 Wayland 支持。
-nographics 在批处理模式下运行时,完全不初始化图形设备。这样,即使在没有 GPU 的机器上也能运行自动化工作流程。
-nolog(仅限 Linux 和 Windows) 不生成输出日志。通常,output_log.txt 写入到游戏可执行文件旁边的 *_Data 文件夹中,其中会打印 Debug.Log 输出。
-popupwindow 将窗口创建为弹出窗口,不带框架。macOS 上不支持该命令。
-screen-fullscreen 覆盖默认的全屏状态。此值必须是 0 或 1。
-screen-height 覆盖默认屏幕高度。此值必须是受支持分辨率中的整数。
-screen-width 覆盖默认屏幕宽度。此值必须是受支持分辨率中的整数。
-screen-quality 覆盖默认屏幕质量。示例用法为:/path/to/myGame -screen-quality Beautiful
-show-screen-selector 强制让屏幕选择器对话框显示。
-single-instance(仅限 Linux 和 Windows) 一次只允许运行一个游戏实例。如果另一个实例已在运行,则使用 -single-instance 再次启动会聚焦现有实例。
-parentHWND <HWND> delayed(仅限 Windows) 将 Windows 独立平台应用程序嵌入到另一个应用程序中。使用命令时,需要将父应用程序的窗口句柄 (‘HWND’) 传递给 Windows 独立平台应用程序。

传递 -parentHWND 'HWND' delayed 时,Unity 应用程序在运行时会被隐藏。还必须在应用程序中从适用于 Unity 的 Microsoft Developer 库 中调用 SetParent。Microsoft 的 SetParent 会嵌入 Unity 窗口。当它创建 Unity 进程时,Unity 窗口会采用作为 Microsoft 的 STARTUPINFO 结构的一部分提供的位置和大小。

要调整 Unity 窗口的大小,请在 Microsoft 的 GetWindowLongPtr 函数中检查其 GWLP_USERDATA。图形初始化后,其最低位设置为 1,可以安全地调整大小。显示完 Unity 启动画面后,其第二个最低位设置为 1。
有关更多信息,请参阅此示例:EmbeddedWindow.zip

通用 Windows 平台命令行参数

通用 Windows 应用程序默认情况下不接受命令行参数,因此要传递命令行参数,必须从 MainPage.xaml.cs/cpp 或 ** MainPage.cs/cpp** 调用一个特殊函数。例如:

appCallbacks.AddCommandLineArg("-nolog");

应在 appCallbacks.Initialize() 函数之前调用此函数。

命令 详细信息
-nolog 不生成 UnityPlayer.log。
-force-driver-type-warp 强制使用 DirectX 11.0 驱动程序类型 WARP 设备(有关更多信息,请参阅 Microsoft 的 Windows 高级光栅化平台 (Windows Advanced Rasterization Platform) 文档)。
-force-d3d11-singlethreaded 强制在使用 D3D11_CREATE_DEVICE_SINGLETHREADED 标志的情况下创建 DirectX 11.0。
-force-gfx-direct 强制使用单线程渲染。
-force-feature-level-9-3 强制使用 DirectX 11.0 功能级别 9.3。
-force-feature-level-10-0 强制使用 DirectX 11.0 功能级别 10.0。
-force-feature-level-10-1 强制使用 DirectX 11.0 功能级别 10.1。
-force-feature-level-11-0 强制使用 DirectX 11.0 功能级别 11.0。

  • 2018–09–07 页面已修订

  • 在 Unity 2017.2 中添加了“accept-apiupdate”命令行选项 NewIn20172

  • 在 Unity 2017.3 中添加了“-force-clamped”命令行参数 NewIn20172

  • 2017.3 中停止了 Tizen 支持 NewIn20173

  • 在 Unity 2018.1 中添加了“noUpm”、“setDefaultPlatformTextureFormat”和“CacheServerIPAddress”命令行选项 NewIn20181

  • 2018.2 版中添加了“Application.isBatchMode”运算符 NewIn20182

构建播放器管线
批处理模式和内置协程兼容性