Unity 编辑器命令行参数

您可以从命令行启动 Unity 编辑器并传入参数来更改编辑器启动方式。还可以使用命令行在启动时执行项目中 C# 脚本一个可以让你创建自己的组件、触发游戏事件、随着时间修改组件属性和以任何你喜欢的方式响应用户输入的代码片段。 更多信息
请参阅 词汇表中的特定方法（请参阅启动时执行方法的示例脚本）。

注意：要使用本页上的信息，您需要了解如何通过操作系统命令行界面启动应用程序和运行命令行参数。

启动 Unity 编辑器时，命令行参数值的定界符为单个空格。例如，要将窗口模式设置为无边框模式，请使用 -window-mode borderless。

启动 Unity

要通过命令提示符或终端启动 Unity 项目，请输入 Unity 应用程序的目录路径，后跟 -projectPath 和目标项目的目录路径。

以下说明假定 Unity 编辑器通过 Unity 集线器安装在默认位置。

在 macOS 上，在终端中键入以下内容来启动 Unity

/Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity -projectPath <project path>

在 Linux 上，在终端中键入以下内容来启动 Unity

/home/<user>/Unity/Hub/Editor/<version>/Editor/Unity -projectPath <project path>

在 Windows 上，在命令提示符中键入以下内容以启动 Unity

"C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -projectPath "<project path>"

当您这样启动 Unity 时，它会在启动时接收命令和信息，这对于测试套件、自动构建和其他生产任务非常有用。

说明:

• 如果您使用安装在其他位置的 Unity 编辑器，请调整命令中的路径。有关如何查找编辑器位置路径的更多信息，请参阅 安装和卸载编辑器版本。

• 在 Windows 平台上传递参数时，确保目录路径不以单个反斜杠结尾，以防止语法错误。使用双反斜杠 (\\) 或不使用反斜杠。例如，

  • "C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -projectPath "C:\MyUnityProjects\MyProject"
  • "C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -createProject "C:\MyUnityProjects\MyProject\\"

配置参数

在启动时，你可以运行 Unity 编辑器和在附加命令和信息下构建 Unity 应用。此页面列出了用于启动和配置 Unity 编辑器和 Unity 播放器实例的命令行参数。

命令	详情
-createProject <路径名>	在给定路径下创建一个空项目。
-disable-assembly-updater <程序集1 程序集2>	指定一个空格分隔的程序集名称列表，作为 Unity 在自动更新时要忽略的参数。 空格分隔的程序集名称列表是可选的：将命令行选项传递给任意程序集名称，以忽略所有程序集，如示例 1 所示。 示例 1 unity.exe -disable-assembly-updater 示例 2 unity.exe -disable-assembly-updater A1.dll 子文件夹/A2.dll 示例 2 中有两个程序集名称，其中一个具有路径名。示例 2 忽略 A1.dll，无论其存储在哪个文件夹中，而仅在存储在 subfolder 文件夹下时忽略 A2.dll 如果你在 -disable-assembly-updater 命令行参数中列出程序集（或者如果没有指定程序集），Unity 会将以下消息记录到 Editor.log [程序集更新程序] 警告：根据命令行参数忽略程序集 [程序集_路径]。”。 导入程序集时，使用此来避免不必要的 API Updater 开销。 如果你要导入访问无需更新的 Unity API 的程序集，此参数很有用。导入不访问任何 Unity API 的程序集（例如，如果你已在 Unity 外部构建了一些或所有源代码，并且希望将结果程序集导入 Unity 项目）时，它也很有用。 注意：如果你禁用需要更新的任何程序集的更新，则在编译时、运行时或两者均可能会收到难以追踪的错误。
-disable-gpu-skinning	在启动时禁用图形处理单元 (GPU) 蒙皮将骨骼关节与角色网格或“蒙皮”的顶点绑定的过程。使用诸如 Blender 或 Autodesk Maya 之类的外部工具执行。 了解更多信息 请参阅 词汇表。
-executeMethod <ClassName.MethodName> 或 -executeMethod <NamespaceName.ClassName.MethodName>	在 Unity 打开项目时执行静态方法，并在可选资产服务器更新完成后执行。你可将其用于诸如连续集成、执行单元测试、制作生成或准备数据等任务。 要从命令行进程返回错误，请引发导致 Unity 以返回代码 1 导出的异常，或以非零返回代码调用 EditorApplication.Exit。 要传递参数，请将其添加到命令行，并在函数内使用 System.Environment.GetCommandLineArgs 检索它们。要使用 -executeMethod，你需要将包含的脚本置于编辑器文件夹中。你执行的方法必须定义为静态方法。
	在您导入纹理或构建项目之前，将默认纹理压缩一种用于存储数据的压缩格式，该格式减少了所需存储空间。请参见纹理压缩、动画压缩、音频压缩、构建压缩。 请参见词汇表格式设置为所需的格式。这样，您就不必再次导入所需的纹理格式。可用的格式有 dxt、pvrtc、atc、etc、etc2 和 astc。在启用纹理压缩定位时，此参数会被忽略。
-overrideTextureCompression	覆盖 Unity 在导入资源时使用的纹理压缩3D 图形硬件要求纹理使用专门格式进行压缩，这些格式针对快速纹理采样进行优化。更多信息 请参见词汇表设置。在本地开发阶段，这尤其有用，因为它可以加快纹理导入速度或构建目标切换速度。有关详细信息，请参见EditorUserBuildSettings.overrideTextureCompression的 API 参考文档。
-silent-crashes	防止 Unity 在独立播放器崩溃时显示一个对话框。当您想在自动化构建或测试中运行播放器且不想让一个对话框提示妨碍自动化时，此参数非常有用。
-upmLogFile <pathname>	指定 Unity 独立于编辑器运行的 UPM 后台应用程序的日志文件路径和文件名。您可以在同一个命令中指定 -upmLogFile 和 -logFile。如果您同时包含这两个参数，您可以为两个日志文件指定独立的路径。
-username <username>	在 Unity 编辑器激活期间在登录表单中输入一个用户名。
-vcsMode <mode>	设置版本控制模式。可用的模式有"可见元文件"、"隐藏元文件"、Perforce 和 PlasticSCM。您可以使用其他标记来填写给定版本控制模式的配置字段。这些标记基于Provider.GetActiveConfigFields方法。例如，您可以使用 -vcPerforceUsername、-vcPerforcePassword、-vcPerforceWorkspace和 -vcPerforceServer来设置 Perforce 用户名、工作区和服务器字段。 注意：包含空格的 <mode> 参数必须用双引号 (“) 括起来.| |-vcsModeSession <mode>|设置此会话的版本控制模式。可用模式为 "Visible Meta Files"、"Hidden Meta Files"、Perforce 和 PlasticSCM。可以使用其他标志来填写给定版本控制模式的配置字段。这些标志基于 Provider.GetActiveConfigFields 方法。例如，可以使用 -vcPerforceUsername、-vcPerforcePassword、-vcPerforceWorkspace 和 -vcPerforceServer 来设置 Perforce 用户名、工作区和服务器字段。 注意：包含空格的 <mode> 参数必须用双引号 (”) 括起来。
-version	在命令行中打印 Unity Editor 的版本号，而无需启动 Editor。
-timestamps	使用当前时间戳和线程 ID 为每个 Editor.log 消息添加前缀。

批处理模式参数

使用以下参数配置 Unity 的批处理模式。批处理模式使 Unity 能够在无需用户输入的情况下运行预定义任务，这使得批处理模式可用于像测试这样的自动化任务。有关更多信息，请参阅 批处理模式和内置协程兼容性。

命令	详情
-accept-apiupdate	当在批处理模式下启动 Unity 时，使用此命令行选项来指定 APIUpdater 应该运行。 示例 unity.exe -accept-apiupdate -batchmode [其他参数] 当你以批处理模式启动 Unity 时，如果不提供此命令行参数，APIUpdater 将不会运行。这可能会导致编译器错误。
-batchmode	在批处理模式下运行 Unity。在批处理模式下，Unity 在无需人工交互的情况下运行命令行参数。它还会抑制需要人为交互（例如“保存场景”窗口）的弹出窗口。在使用命令行参数时，你应该始终在批处理模式下运行 Unity，因为它允许自动化不间断地运行。 当在执行脚本代码期间出现异常、资产服务器更新失败或者其他操作失败时，Unity 会立即以返回代码 1 退出。 在批处理模式下，Unity 会向控制台发送其日志输出的最小版本。然而，日志文件 仍包含完整的日志信息。在 Editor 已打开相同项目的情况下，无法在批处理模式下打开项目；任何时候只能运行 Unity 的单个实例。 要检查 Editor 或独立播放器是否在批处理模式下运行，请使用 Application.isBatchMode 运算符。 如果使用 -batchmode 时项目尚未导入，则目标平台为默认平台。若要强制使用不同的平台，请使用 -buildTarget 选项。
‑ignorecompilererrors	当你使用此参数时，即使有编译错误，Unity 也会继续启动你的应用程序。
-nographics	以批处理模式运行时，Unity 不会初始化图形设备。然后，您可以在没有 GPU 的计算机上运行自动化工作流。只有当有窗口处于焦点时，自动化工作流才有效，否则您无法发送模拟的输入命令。-nographics 不允许您烘焙 GI，因为 Enlighten 实时全局光照需要 GPU 用于 Meta Pass 渲染（有关更多信息，请参阅光照贴图和着色器页面中的 Meta Pass 部分）。 注意：输出日志在此模式下会关闭。要启用输出日志的创建，请使用命令 -logFile 指定文件位置。

构建参数

使用以下参数通过命令行针对各种平台构建播放器。有关用命令行参数构建播放器的更多信息，请参阅 Unity Standalone Player 命令行参数。

命令	详情
-activeBuildProfile <pathname>	将保存在给定路径处的构建配置文件设置为活动构建配置文件（例如，-activeBuildProfile "Asset/Settings/BuildProfile/WindowsDemo.asset"）。
-build <pathName>	将播放器从 activeBuildProfile <pathname> 构建到指定的目标路径。对于某些平台，路径必须以特定于目标平台的文件扩展名结尾。例如，-build path/to/your/build.exe。有关哪些平台需要扩展名的信息，请参阅 目标平台的构建路径要求。
-buildLinux64Player <pathname>	构建一个 64 位的独立 Linux 播放器（例如，-buildLinux64Player path/to/your/build）。
-buildLinuxHeadlessSimulation <pathname>	构建一个 64 位的 Linux 无头模拟播放器（例如，-buildLinuxHeadlessSimulation path/to/your/build）。
-buildOSXUniversalPlayer <pathname>	构建一个 64 位的独立 macOS 播放器（例如，-buildOSXUniversalPlayer path/to/your/build.app）。
-buildTarget <name>	选择一个活动构建目标以在其中启动编辑器。可用的选项取决于您在编辑器中启用了哪些构建目标。这些选项与通过 API 枚举 BuildTarget 可用的选项相对应。可能选项包括 • win64 • win • osxuniversal • linux64 • android • ios • webgl • tvos • windowsstoreapps • cloudrendering • visionos 如果您是具有访问封闭平台权限的开发者，您可能有其他可用的 -buildTarget 选项。有关详细信息，请参阅您的目标平台的文档。
-standaloneBuildSubtarget <name>	在加载项目之前，为独立平台选择一个活动构建子目标。可能选项有 • 播放器 • 服务器
-buildWindowsPlayer <pathname>	构建 32 位独立的 Windows 播放器（例如，-buildWindowsPlayer path/to/your/build.exe）。
-buildWindows64Player <pathname>	构建 64 位独立的 Windows 播放器（例如，-buildWindows64Player path/to/your/build.exe）。

加速器缓存服务器参数

使用以下参数配置 Unity 使用Unity 加速器缓存服务器。这些参数将覆盖存储在编辑器首选项中的任何对应配置。

命令	详情
-EnableCacheServer	启用加速器缓存服务器。还必须使用 -cacheServerEndpoint <host:port> 来指定缓存服务器的地址。
-cacheServerEndpoint <host:port>	指定加速器缓存服务器的终端点地址。 示例 -cacheServerEndpoint 127.0.0.1:10080
-cacheServerNamespacePrefix <prefix>	设置加速器缓存服务器的命名空间前缀。将此参数与命名空间名称配合使用，以便对缓存服务器上的数据进行分区，例如隔离不同项目或 Unity 版本的缓存数据。 示例 -cacheServerNamespacePrefix MyProject_Unity23LTS 包含空格的前缀必须用双引号 (") 括起来。 提供的名称用作缓存中最多 3 个命名空间的前缀，这些命名空间按类型（元数据、构件数据和着色器缓存数据）分隔数据。
-cacheServerEnableDownload <true|false>	启用或禁用从加速器缓存服务器下载。 示例 -cacheServerEnableDownload true
-cacheServerEnableUpload <true|false>	启用或禁用上传到加速器缓存服务器。 示例 -cacheServerEnableUpload true
-cacheServerWaitForConnection <ms>	指定 Unity 在加载项目时等待与加速器缓存服务器连接的时间（以毫秒为单位），在开始初始项目刷新之前。 示例 -cacheServerWaitForConnection 5000
-cacheServerWaitForUploadCompletion	阻止 Unity 关闭，直到所有待处理的加速器缓存服务器上传完成。建议在将加速器与命令行参数 -quit 结合使用时使用此功能，该参数在其他脚本命令执行完成后关闭 Unity 编辑器。
-cacheServerDownloadBatchSize <batchSize>	设置单个加速器缓存服务器下载批处理中的构件数。下载批处理是一种优化，用于通过将单个下载分组到更大的批处理中来减少下载操作的数量。 示例 -cacheServerDownloadBatchSize 256 默认值为128。
-cacheServerUploadExistingImports	在 Unity 开始将新导入项上传到加速器缓存服务器时，上传所有以前未上传的现有导入项。先前已上传的导入项不会重新上传。
-cacheServerUploadAllRevisions	在 Unity 开始将新导入项上传到加速器缓存服务器时，上传所有现有导入项，包括资产数据库中已知的以前从未上传的所有修订。先前已上传的导入项修订不会重新上传。
-cacheServerUploadExistingShaderCache	当 Unity 开始将新导入内容上传到加速器缓存服务器时，请上传任何现有的 着色器在 GPU 上运行的程序。更多信息 请参阅 术语表 缓存导入，这些导入在之前未曾上传。已上传的着色器导入不会重新上传。

调试参数

命令	详情
-disableManagedDebugger	禁用调试器监听套接字。
-diag-debug-shader-compiler	Unity 仅启动 着色器编译器的一个实例，并强制其超时为一小时。对于调试着色器编译器问题非常有用。
-debugCodeOptimization	启用调试代码优化模式，覆盖当前的会话默认代码优化模式。
-enableCodeCoverage	启用代码覆盖并允许访问 覆盖 API。
-force-d3d12-debug	启用 DX12 验证层。对于使用 XR涵盖虚拟现实 (VR)、增强现实 (AR) 和混合现实 (MR) 的应用程序的总称。支持这些形式的交互式应用程序的设备可以称为 XR 设备。更多信息 请参阅 术语表 插件或本机插件非常有用。
-force-d3d12-debug-gbv	启用基于 DX12 GPU 的验证。对于使用 XR 插件或本机插件非常有用。
-force-vulkan-layers	启用 Vulkan 验证层。对于使用 XR 插件或本机插件非常有用。
-stackTraceLogType	允许详细调试。所有设置都允许选择 无、仅脚本和 完整（例如，-stackTraceLogType 完整）。
-log-memory-performance-stats	在关闭编辑器时，将详细的内存和性能报告添加到主 Unity Editor 日志文件中。

图形 API 参数

使用以下参数强制 Unity Editor 使用特定的图形 API。

命令	详情
-force-d3d11（仅适用于 Windows）	使编辑器使用 Direct3D 11 进行渲染。通常，图形 API 取决于 玩家设置设置，用于为 Unity 构建的最终游戏设置各种特定于玩家的选项。更多信息 请参阅 术语表（通常默认为 D3D11）。
-force-d3d12（仅适用于 Windows）	使编辑器使用 Direct3D 12 进行渲染。通常，图形 API 取决于 玩家设置。
-force-opengl	使编辑器使用旧式 OpenGL 后端。
-force-glcore	使编辑器使用 OpenGL 3/4 核心配置文件进行渲染。编辑器尝试使用 OpenGL 驱动程序提供的最佳 OpenGL 版本及所有 OpenGL 扩展。如果平台不受支持，则编辑器使用 Direct3D。
-force-glcoreXY	类似于-force-glcore，但会请求特定的 OpenGL 上下文版本。XY 的可接受值：32、33、40、41、42、43、44 或 45。如果该平台不支持某个特定版本的 OpenGL，Unity 将回退到某个受支持的版本。
-force-gles（仅限 Windows）	让编辑器使用 OpenGL Embedded Systems 进行渲染。编辑器会尝试使用 OpenGL 驱动程序所公开的最佳 OpenGL ES 版本，并使用所有 OpenGL ES 扩展。
-force-glesXY（仅限 Windows）	类似于 -force-gles，但会请求特定的 OpenGL ES 上下文版本。XY 的可接受值：30、31、31aep 或 32。如果该平台不支持某个特定版本的 OpenGL ES，Unity 将回退到某个受支持的版本。如果该平台不支持 OpenGL ES，Unity 将回退到另一个图形 API。
-force-vulkan	让编辑器使用 Vulkan 进行渲染。通常，图形 API 取决于Player Settings。
-force-clamped	将此选项与 -force-glcoreXY 结合使用，以防止 Unity 检查其他 OpenGL 扩展，从而让其能够在不同平台上使用相同的代码路径运行。此方法有助于确定问题是否是特定于某个平台的。例如，驱动程序错误。

许可证参数

使用以下参数处理 Unity 许可证或使用不同的许可证选项运行 Unity 编辑器。

命令	详情
-createManualActivationFile	手动激活 Unity 许可证的三步流程中的第一步。如需了解更多信息，请参阅从命令行生成许可证激活文件 (.alf)。
-manualLicenseFile <yourulffile>	手动激活 Unity 许可证的三步流程中的第三步。如需了解更多信息，请参阅从命令行生成许可证激活文件 (.alf)。
-returnlicense	返回当前激活的基于序列或命名用户许可证。不要使用 -returnlicense 返回浮动许可证。如需了解更多信息，请参阅退回许可证。如需了解有关许可证模型的更多信息，请参阅许可证概述。
-serial <serial-key>	激活您的付费 Unity 许可证。包含 <serial-key> 值以激活基于序列的许可证，或者同时激活命名用户许可证及其序列密钥。要激活命名用户许可证，但无需激活其序列密钥，请排除 <serial-key> 值。如需了解更多信息，请参阅从命令行激活许可证。如需了解有关许可证模型的更多信息，请参阅许可证概述。 注意：当您使用 -serial 参数时，您还必须使用 -batchmode 参数。指定 -quit 参数也是一个好习惯。

Metal 参数（仅限 macOS）

使用以下参数配置 Unity 使用适用于 Apple 设备的Metal图形 API 的方式。

命令	详情
-force-device-index	使用 Metal 时，通过传递 GPU 的索引，让编辑器使用特定的 GPU 设备（仅限 macOS）。
-force-low-power-device（仅限 macOS）	如果您使用 Metal，让编辑器使用低功耗设备。
-force-metal	让编辑器使用 Metal 作为默认图形 API（仅限 macOS）。
-enable-metal-capture	启用在编辑器内部拍摄 Metal 捕获的功能。

分析器参数

使用以下参数配置 Unity 使用分析器一个帮助您优化游戏效果的窗口。它显示了在游戏中各个区域花费的时间。例如，它可以报告渲染、动画和游戏逻辑部分所花费时间百分比。更多信息
参见术语表的情况。

命令	详情
-deepprofiling	为CPU 分析器启用深度分析选项。
-profiler-enable	分析播放器或编辑器的启动。当您与播放器一起使用此参数时，它与在构建配置文件中启用“自动连接分析器”选项以构建播放器具有相同效果。 当您在编辑器中使用此参数时，它会在编辑器启动时开始收集和显示分析器窗口中的分析器信息。
-profiler-log-file <Path/To/Log/File.raw>	此参数将Unity 分析器设置为在启动时将分析数据传输到 .raw 文件。它适用于播放器和编辑器。
-profiler-capture-frame-count <NumberOfFrames>	当在启动时传输到 .raw 文件时，此参数设置分析器在分析中应捕获的帧数。它仅适用于播放器。
-profiler-maxusedmemory	默认情况下，播放器的 Unity 分析器 maxUsedMemory 为 16MB，而编辑器的 maxUsedMemory 为 256MB。您可以在启动时使用此参数将 maxUsedMemory 设置为自定义大小（例如，-profiler-maxusedmemory 16777216）。大小以字节为单位。

Unity 编辑器专用命令行参数

只有在特殊情况下或在 Unity Support 的指导下，才应使用这些参数。

命令	详情
-enableIncompatibleAssetDowngrade	当您有由较新、不兼容的 Unity 版本制作的资源时，如果您想降级到与当前 Unity 版本结合使用，请使用此选项。 当您启用此选项时，如果您尝试打开需要此选项的项目，Unity 会向您显示一个对话框，要求您确认此降级。 注意：此过程不受支持，且风险很高，仅应作为最后手段。
-giCustomCacheLocation	使用此选项为全局光照 (GI) 缓存文件夹设置自定义位置。 注意：关闭编辑器时，giCustomCacheLocation 将恢复到 GI 缓存的默认位置，或您之前设置过的自定义位置。

Unity Hub 特殊命令行参数

您应该仅在特殊情况下或者在 Unity 支持人员指导下使用这些参数。这些参数是在默认情况下不使用 Unity Hub 的 Unity 编辑器版本中使用的。

命令	详情
-useHub	使用 Hub 集成启动 Unity 编辑器。
-hubIPC	启用 Unity 编辑器和 Unity Hub 之间的通信和交互。
-hubSessionId	指定 Unity Hub 会话的唯一标识符。

在 Unity 编辑器所有受支持的版本中，这些参数默认情况下已设置。

软件包中的额外编辑器参数

这些软件包安装后可获得其他编辑器命令行参数。

软件包	详情
Burst	参见 Burst 软件包文档。
测试框架	参见 Unity 测试框架 软件包文档。
代码覆盖率	参见 代码覆盖率 软件包文档。

启动时执行方法的示例脚本

您可以使用命令行在启动时执行项目 C# 脚本中的特定方法。以下示例演示了一个 C# 脚本以及在启动时从该脚本执行方法的命令行参数。

项目中的 C# 示例脚本

using UnityEditor;
class MyEditorScript
{
     static void PerformBuild ()
     {
        BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
        buildPlayerOptions.scenes = new[] { "Assets/Scene1.unity", "Assets/Scene2.unity" };
        BuildPipeline.BuildPlayer(buildPlayerOptions);
     }
}

以下命令在批处理模式下执行 Unity、执行上述脚本中的 MyEditorScript.PerformBuild 方法，然后完成后退出。

Windows

"C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -quit -batchmode -projectPath "C:\Users\UserName\Documents\MyProject" -executeMethod
MyEditorScript.PerformBuild

macOS

/Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity -quit -batchmode -projectPath ~/UnityProjects/MyProject -executeMethod
MyEditorScript.PerformBuild

注意：在编辑器路径中，将 <version> 替换为您要启动的 Unity 版本，或者如果您的 Unity 编辑器路径不是默认路径，则完全替换路径。