# 自定义脚本符号

> Create your own custom scripting symbols via the Editor UI, from scripts, or with an asset file.

除了 Unity 的[内置脚本符号](/engine/6000.0/manual/scripting/compilation-and-code-reload/script-compilation/conditional-compilation/symbol-reference.md)之外，还可以定义自己的自定义脚本符号。定义自定义脚本符号的位置决定了其适用的范围。您可以在以下位置定义自定义符号：

* [资源文件](#asset)，针对适用于项目中所有 Editor 和 Player 代码的符号（无论活动的[构建配置文件](/engine/6000.0/manual/unity-editor/editor-features/build-settings/build-profiles.md)如何）。
* [播放器设置](#player-settings)，针对当给定平台或其构建配置文件之一处于活动状态时，适用于所有 Editor 和 Player 代码的符号。
* [构建配置文件](#build-profile)，针对当给定构建配置文件处于活动状态时，适用于所有 Editor 和 Player 代码的符号。
* [通过代码](#code)，针对适用于活动平台或单个播放器构建的符号，具体取决于所使用的 API。

## 为整个项目自定义符号##custom-symbols-for-the-whole-project

您可以使用[响应文件](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-response-files?view=vs-2022)资源定义适用于整个项目的自定义脚本符号，如下所示：

1. 给文件 `csc.rsp` 命名并将其放在项目的 **Assets** 文件夹的根目录中。
2. 在以 `-define:` 开头的行上定义脚本符号，后跟一个或多个以分号分隔的脚本符号。

Unity 在启动时会读取此文件，并在编译任何代码之前应用此文件。例如，如果在 `csc.rsp` 文件中包含了单行 `-define:UNITY_DEBUG;UNITY_TEST`，符号 `UNITY_DEBUG` 和 `UNITY_TEST` 将作为全局定义的脚本符号包含在项目的所有 C# 脚本中。

**注意**：在 Unity 重新编译脚本之前，对 `.rsp` 文件的更改不会生效。可通过更新或重新导入单个脚本文件来触发重新编译。

## 为平台自定义符号##custom-symbols-for-a-platform

您可以定义特定于平台的自定义脚本符号，如下所示：

1. 打开[播放器设置 (Player settings)](/engine/6000.0/manual/unity-editor/editor-features/comp-manager-group/class-player-settings.md)。
2. 导航到**其他设置 (Other Settings)** > **脚本重新编译 (Script Compilation)** 部分的**脚本定义符号 (Scripting Define Symbols)** 列表。
3. 选择 **+** 按钮并在文本字段中输入符号的名称，即可将新的脚本符号添加到列表中。使用 **-** 按钮删除现有列表项。
4. 列表编辑完成后，选择**应用 (Apply)** 以应用所做的更改。Unity 会使用新符号重新编译项目中的脚本。

**注意**：**复制定义 (Copy Defines)** 按钮可将列表中的当前一组自定义脚本符号作为一串以分号分隔的值复制到剪贴板中。

## 为构建配置文件自定义符号##custom-symbols-for-a-build-profile

您可以为构建配置文件定义自定义脚本符号，如下所示：

1. 在[构建配置文件 (Build Profiles) 窗口](/engine/6000.0/manual/unity-editor/editor-features/build-settings/build-profiles-reference.md)中选择要为其定义符号的构建配置文件。
2. 导航到**构建数据 (Build Data)** 部分的**脚本定义 (Scripting Defines)** 列表。
3. 选择 **+** 按钮并在文本字段中输入符号的名称，即可将新的脚本符号添加到列表中。使用 **-** 按钮删除现有列表项。对列表的修改会自动保存并应用。

**注意**：您可以使用 `-activeBuildProfile` [命令行参数 ](/engine/6000.0/manual/unity-editor/editor-features/command-line-arguments/editor.md)来启动 Editor，使指定的构建配置文件及其自定义脚本符号自启动时适用。

## 自定义代码定义的符号##custom-symbols-defined-from-code

您可以使用以下 API 来定义脚本符号：

* [`PlayerSettings.SetScriptingDefineSymbols`](/engine/6000.0/script-reference/unity-editor/player-settings/set-scripting-define-symbols.md)
* [`BuildPlayerOptions.extraScriptingDefines`](/engine/6000.0/script-reference/unity-editor/build-player-options/extra-scripting-defines.md)
* [`Build.Player.ScriptCompilationSettings-extraScriptingDefines`](/engine/6000.0/script-reference/unity-editor-build-player/script-compilation-settings/extra-scripting-defines.md)

`BuildPlayerOptions.extraScriptingDefines` 和 `Build.Player.ScriptCompilationSettings-extraScriptDefines` 仅适用于 Player 构建，因此在定义适用于 Editor 脚本的脚本符号时，请使用 [`PlayerSettings.SetScriptingDefineSymbols`](/engine/6000.0/script-reference/unity-editor/player-settings/set-scripting-define-symbols.md)。这相当于在[播放器设置 (Player settings)](#player-settings) 中配置特定于平台的脚本符号的代码。

**重要提示**：在 Editor 重新获得控制权并重新编译脚本之前，从带有 `SetScriptingDefineSymbols` 的代码中创建的符号不会生效。例如，如果在 Editor 脚本中创建带有 `SetScriptingDefineSymbols` 的脚本符号，然后在下一行调用 `BuildPipeline.BuildPlayer`，则在上一行中创建的新符号尚不会生效。在这种情况下，作为 `BuildPlayer` 执行的一部分运行的任何 Editor 代码都会在没有新符号的情况下运行，播放器可能无法按预期构建。

### 在批处理模式下自定义符号##custom-symbols-in-batch-mode

当 Editor 以批处理模式运行时，没有触发脚本重新编译的机制。如果需要在以批处理模式运行的 Editor 中定义特定符号，则必须在启动时[使用 csc.rsp 资源文件](#asset)将其设置到位。

## 脚本符号继承##scripting-symbol-inheritance

如果在多个位置定义自定义脚本符号，Unity 会将适用于当前构建配置的所有符号一并加上。符号继承自每个作用域，而不是覆盖，如下所示：项目范围内的符号（来自 `csc.rsp`）+特定于平台的符号（来自播放器设置 (Player settings)）+构建配置文件符号（来自构建数据 (Build Data)）。仅当平台和构建配置文件符号与活动的构建配置文件匹配时，才会将其包含在内。

例如，假设项目在以下位置定义了以下自定义脚本符号：

| **位置**                  | **定义的符号**  |
| ----------------------- | ---------- |
| `csc.rsp`               | `SYMBOL_A` |
| Windows Player Settings | `SYMBOL_B` |
| WindowsBuildProfile1    | `SYMBOL_C` |
| WindowsBuildProfile2    | `SYMBOL_D` |

根据此示例配置，下表显示了当不同的构建配置文件处于活动状态时，Editor 和 Player 代码的哪些符号处于活动状态。

| **活动构建配置文件**         | **活动符号**                           |
| -------------------- | ---------------------------------- |
| Android              | `SYMBOL_A`                         |
| Windows              | `SYMBOL_A`, `SYMBOL_B`             |
| WindowsBuildProfile1 | `SYMBOL_A`, `SYMBOL_B`, `SYMBOL_C` |
| WindowsBuildProfile2 | `SYMBOL_A`, `SYMBOL_B`, `SYMBOL_D` |

您可以使用代码中的 `#if` 指令来测试此行为。有关更多信息，请参阅[测试条件编译](/engine/6000.0/manual/scripting/compilation-and-code-reload/script-compilation/conditional-compilation/test.md)。

## 其他资源##additional-resources

* [Unity 脚本符号参考](/engine/6000.0/manual/scripting/compilation-and-code-reload/script-compilation/conditional-compilation/symbol-reference.md)
* [引用其他类库程序集](/engine/6000.0/manual/scripting/environment-and-tools/overview-of-dot-net-in-unity/dotnet-profile-assemblies.md)