> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/build/build-profiles.md).

# 构建配置

`AIT` 说明菜单的各个构建入口会自动变化哪些设置，以及如何修改这些值。

### 操作菜单

| 菜单                                | 用途                                          |
| --------------------------------- | ------------------------------------------- |
| `AIT > Dev Server > Start Server` | 运行本地开发服务器（使用 devtools Mock SDK + 面板在浏览器中测试） |
| `AIT > Build & Package`           | 生成用于发布的包                                    |
| `AIT > Deploy (Test)`             | 增量构建后测试部署（`ait deploy`）— 通过 QR/URL 在真机上确认   |
| `AIT > Deploy (Production)`       | 清理构建后测试部署（`ait deploy`）— 发布后在控制台申请审核/上线     |

`ait deploy`在两个菜单中都 **始终使用控制台 QR 测试环境**(`intoss-private://`）进行部署。面向实际用户的发布并不是通过这个 CLI 命令完成，而是在部署后 **在控制台申请审核**之后才会完成。详细流程见 [开始使用](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/getting-started)。

### 配置文件矩阵

| 操作                      | 调试控制台 | 开发构建 |  WebGL 压缩  |  剥离级别 | LZ4 压缩 | 调试符号 |
| ----------------------- | :---: | :--: | :--------: | :---: | :----: | :--: |
| **开发服务器**               |  ✅ 启用 | ✅ 启用 |     禁用     |   最小  |  ✅ 启用  |  嵌入  |
| **构建与打包**               |  ❌ 禁用 | ❌ 禁用 | 自动（Brotli） | 自动（高） |  ✅ 启用  |  外部  |
| **Deploy (Test)**       |  ❌ 禁用 | ❌ 禁用 | 自动（Brotli） | 自动（高） |  ✅ 启用  |  外部  |
| **Deploy (Production)** |  ❌ 禁用 | ❌ 禁用 | 自动（Brotli） | 自动（高） |  ✅ 启用  |  外部  |

Deploy (Test) 和 Deploy (Production) 使用同一个生产配置文件，因此上述设置值相同。两者的区别不在这张表中 **构建范围**（增量 vs 清理）以及 **部署 memo 前缀**(`-m "[Test] …"` / `-m "[Production] …"`）— 在控制台中会用这个前缀区分两个部署。

> `Mock 桥接`不是构建配置文件项。 `devtools`(`@apps-in-toss/devtools`）请参见单独章节。

### 各项设置的含义

#### devtools

仅用于 Dev Server， **不是构建配置文件，而是 `AIT > Configuration`的单独设置**。开启后，可以在浏览器中不打开 Toss 应用，使用 devtools 的 Mock SDK 运行游戏，并会在屏幕上显示用于状态操控的面板。与构建配置文件不同，它不会改变构建产物，因此修改设置后 **只需重启服务器即可生效**会生效。返回值和限制见 [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)的 devtools 章节中整理。

#### 开发构建

这是 Unity 的 Development Build 选项。

| 值  | 说明                        |
| -- | ------------------------- |
| 启用 | 提升构建速度，便于调试（可连接 Profiler） |
| 禁用 | 优化后的发布构建                  |

#### 调试符号

决定调试符号（source map）放在哪里。适用于 Unity 2022.3 及以上版本。

| 值  | 说明                       |
| -- | ------------------------ |
| 嵌入 | 将符号包含在构建文件中（文件体积增大，便于调试） |
| 外部 | 拆分为单独文件（文件体积减小，适合发布）     |

#### 调试控制台

在屏幕左下角显示调试按钮。点击后可查看日志和 [SDK 事件](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/metrics)。可以查看。发布到生产环境时请禁用。

#### WebGL 压缩

这是最终产物的压缩格式。

| 值      | 说明               |
| ------ | ---------------- |
| 自动     | 使用 Brotli（默认）    |
| 禁用     | 不压缩（优先构建速度）      |
| Gzip   | Gzip 压缩          |
| Brotli | Brotli 压缩（最高压缩率） |

仅 Dev Server 为了构建速度设为 Disabled，其余配置文件为自动（Brotli）。

#### 剥离级别

决定移除未使用的托管代码的程度。

| 值  | 说明             |
| -- | -------------- |
| 自动 | 使用 High（默认）    |
| 最小 | 只移除最少量的代码      |
| 低  | 低级别代码移除        |
| 中  | 中级别代码移除        |
| 高  | 积极移除代码（最小构建体积） |

仅 Dev Server 为了构建速度设为 Minimal，其余为自动（High）。

> **参考**：Disabled 在 WebGL（IL2CPP）中不受支持，因此已从选项中移除；在旧版本中保存为 Disabled 的值会规范化为 Minimal。仅通过反射引用的类型可能会在 High 中被移除，因此如果剥离后行为发生变化， `link.xml`请通过它指定要保留的对象。

#### LZ4 压缩

这是 Unity 构建流程中的 LZ4 压缩。所有配置文件默认启用。

### 配置文件自定义

1. `AIT > Configuration` 打开菜单
2. 展开“构建配置文件”部分
3. 展开所需的配置文件（Dev Server、Production 等）
4. 更改各选项的复选框
5. 更改会自动保存

配置文件设置在 `Assets/AppsInToss/Editor/AITConfig.asset`里。

### 环境变量覆盖

在 CI/CD 或自动化脚本中，可以不修改代码而覆盖配置文件值。大多数情况下， `AITBuildInitializer.ApplyEnvironmentVariableOverrides(profile)`会应用到配置文件副本中， `AIT_IL2CPP_CONFIGURATION`只有 `Init` 在步骤中直接应用到 PlayerSettings。

| 环境变量                       | 说明             | 允许值                                                    |
| -------------------------- | -------------- | ------------------------------------------------------ |
| `AIT_DEBUG_CONSOLE`        | 启用调试控制台        | `true` / `false`                                       |
| `AIT_COMPRESSION_FORMAT`   | 压缩格式           | `-1` （自动） / `0` （Disabled） / `1` （Gzip） / `2` （Brotli） |
| `AIT_DEVELOPMENT_BUILD`    | 开发构建           | `true` / `false`                                       |
| `AIT_IL2CPP_CONFIGURATION` | IL2CPP 编译器优化级别 | `调试` / `发布` / `主`                                      |

如果超出允许值， `Debug.LogWarning`会通过 Debug.LogWarning 发出警告并仅忽略该变量——构建会继续。

`AIT_DEVELOPMENT_BUILD`和 `AIT_IL2CPP_CONFIGURATION`二者都能减少链接时间，但处于不同层级。前者是 Player 选项，后者是 IL2CPP 编译器优化器级别，因此若要在 CI 中缩短构建时间，同时指定这两个设置效果更大。

```bash
AIT_DEBUG_CONSOLE=true \\
AIT_COMPRESSION_FORMAT=0 \\
/Applications/Unity/Hub/Editor/2022.3.62f1/Unity.app/Contents/MacOS/Unity \\
  -quit -batchmode -projectPath ./MyProject
```

SDK 读取的环境变量不止这四个。打包阶段的 `AIT_DISABLE_INSTALL_SKIP`是 [构建流水线](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process)中，以及 Sentry 相关变量则 [Sentry集成](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/sentry-integration)中有说明。

### 构建日志

构建开始时所应用的配置文件会输出到 Unity Console。哪些值实际生效，这份日志是最终确认手段——环境变量覆盖也会反映在这里。

```
[AIT] ========================================
[AIT] 构建配置文件：Dev Server
[AIT] ========================================
[AIT]   调试控制台：启用
[AIT]   Development Build：启用
[AIT]   LZ4 压缩：启用
[AIT]   压缩格式：Disabled
[AIT]   剥离级别：Minimal
[AIT]   调试符号：Embedded
[AIT] ========================================
```

压缩格式会按配置文件中保存的值原样（`-1`如果是 `自动`） `-1`时，会在括号中同时显示实际应用的值。

### 相关文档

* [开始使用](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/getting-started) — 安装及基本设置
* [构建流水线](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process) — 应用配置文件后实际发生的事情
* [构建自定义](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-customization) — Web 入口点和标记区域
* [API 使用模式](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) — devtools 行为
* [问题排查](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) — 构建受阻时


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/unity/build/build-profiles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.