Unity双端项目创建：Android与iOS构建成功率的关键起点

1. 为什么这个“创建项目”动作，比你想象中更关键

Unity Hub 创建支持 Android & iOS 的项目——这听起来像一句教科书式的操作指引，但在我带过二十多个跨平台移动项目、亲手配置过三百多台开发机之后，我越来越确信：绝大多数 Unity 移动端项目的崩溃、构建失败、真机调试黑屏、甚至上线后闪退，其根源，往往就埋在“新建项目”那三分钟里。不是代码写错了，不是逻辑有问题，而是从第一步起，环境底座就松动了。

很多人以为“选个模板 → 点确定 → 开始写脚本”就完事了。但现实是：Unity Hub 界面右下角那个小小的“Add Modules”按钮，背后关联着 Android SDK/NDK/JDK 的版本兼容矩阵；你勾选的“iOS Build Support”，实际会触发 Xcode 工具链的深度校验；而“Universal Render Pipeline”模板看似省事，却可能让 iOS Metal 渲染管线在旧款 iPhone 上直接拒绝初始化。这些都不是报错后才出现的问题，而是静默失效——构建成功，安装成功，一打开就白屏或卡死。

这篇内容，就是为你把“新建一个能真正跑通双端的 Unity 项目”这件事，拆解到每一个可验证、可回溯、可复现的原子步骤。它不讲泛泛而谈的“安装指南”，而是聚焦在：Hub 界面里哪几个像素级操作决定成败？哪些默认勾选项必须手动取消？SDK 版本号后面那个小数点，差0.1就足以让你在凌晨三点对着 Xcode 控制台发呆。适合两类人：一是刚从 PC 或 WebGL 转向移动开发的 Unity 程序员，二是团队里负责搭建标准化开发环境的 Tech Lead。你不需要提前装好所有工具，也不需要背诵版本号——我会告诉你，每一步“为什么必须这样”，以及“如果跳过会怎样”。

2. Unity Hub 的真实角色：不只是启动器，更是环境仲裁者

很多人把 Unity Hub 当成一个“快捷方式集合”，点开它，选个版本，新建项目，完事。这是最大的误解。Unity Hub 的本质，是一个跨版本、跨平台、跨依赖的环境仲裁系统（Environment Arbitrator）。它不直接编译代码，但它决定了：你的 Unity Editor 实例，到底能调用哪一套 Android 构建工具链？能否识别出你本地安装的 Xcode 命令行工具？甚至，它会主动拦截并重写某些 Editor 的内部路径配置，以规避 macOS 的 SIP（系统完整性保护）限制。

2.1 Hub 与 Editor 的权限分工：谁管什么，必须分清

这是新手最容易混淆的底层逻辑。我们来划一条清晰的线：

• Unity Hub 负责“准入”和“授权”：它检查你是否安装了对应平台的构建模块（Android/iOS Build Support），验证 JDK/SDK/NDK/Xcode Command Line Tools 是否存在且路径可读，生成.unityconfig配置文件，并将这些信息注入到即将启动的 Editor 实例中。它不关心你写的 C# 代码有没有语法错误，但它会坚决阻止你用 Unity 2021.3.30f1 去构建一个强制要求 Metal API 的 iOS 项目（因为该版本 Editor 的 Metal 后端尚未稳定）。

• Unity Editor 负责“执行”和“反馈”：一旦 Editor 启动，它就接管全部构建流程。它读取 Hub 注入的配置，调用gradle打包 Android APK，调用xcodebuild编译 iOS 工程。此时 Hub 已经“退场”，Editor 报出的任何错误（比如CommandInvokationFailure: Gradle initialization failed），表面看是 Editor 的锅，根因却极可能在 Hub 阶段——比如 Hub 指向了一个损坏的 NDK r21e 安装目录，而 Editor 只是忠实地执行了这个错误路径。

提示：你可以通过 Hub 的“Installs”页签，右键点击任意已安装的 Unity 版本，选择“Show in Explorer/Finder”。你会看到一个名为Editor\Data\PlaybackEngines的文件夹。里面每个子文件夹（如AndroidPlayer,iOSPlayer）都对应一个平台支持模块。Hub 在你勾选“Android Build Support”时，实际就是在下载并解压这个完整文件夹。它不是简单地打个勾，而是在硬盘上搬运几百 MB 的二进制引擎代码。

2.2 Hub 的“Add Modules”按钮：一个被严重低估的决策点

当你在 Hub 中点击“New Project”，选择模板后，界面底部会出现“Add Modules”按钮。绝大多数人会忽略它，直接点“Create”。但这里藏着双端构建成败的第一道闸门。

• Android 模块：必须同时勾选三项：

  • Android Build Support（核心）
  • Android SDK & NDK Tools（关键！Hub 默认不勾选此项）
  • OpenJDK（推荐勾选，避免与系统 JDK 冲突）

  为什么Android SDK & NDK Tools必须手动勾选？因为 Hub 自带的这套工具链，是 Unity 官方经过严格测试的“黄金组合”。它打包的是特定版本的 SDK Platform-tools（如 34.0.5）、NDK（如 r21e）、OpenJDK（如 11.0.18）。如果你依赖系统全局安装的 SDK，很可能遇到Failed to run 'xxxx/android-sdk/tools/bin/sdkmanager --list'这类路径错误——因为系统 SDK 的sdkmanager是 shell 脚本，而 Windows 上的 Unity Editor 无法正确执行它。Hub 自带的工具链是跨平台预编译二进制，无此问题。

• iOS 模块：只需勾选iOS Build Support。但注意：它不会为你安装 Xcode。Hub 只做一件事——扫描/Applications/Xcode.app/Contents/Developer/usr/bin/目录，确认xcodebuild,xcrun,security等命令是否存在。如果缺失，Hub 会在创建项目后，在 Editor 的Build Settings窗口中，用醒目的红色文字提示：“Xcode command line tools not found”。这不是警告，是判决书：没有它，iOS 构建按钮是灰色的，点不了。

2.3 Hub 的隐藏配置文件：.hubsettings与editor-install.json

Hub 的所有决策并非凭空产生，它把关键配置持久化在两个文件里，理解它们，等于拿到了环境仲裁的源代码。

• ~/.hubsettings（macOS/Linux）或%APPDATA%\UnityHub\.hubsettings（Windows）：这是一个 JSON 文件，记录了你所有偏好设置，其中最关键的字段是"androidSdkPath"和"iosXcodePath"。当你在 Hub 设置中手动指定 SDK 路径时，改的就是这里。但请注意：这个路径只对 Hub 本身生效，它不会自动同步给已启动的 Editor 实例。如果你在 Hub 中修改了 SDK 路径，必须重启 Editor 才能生效。

• ~/.unityhub/editor-install.json：这个文件记录了每个 Unity 版本的详细安装信息，包括modules数组。例如：

  "modules": [ { "name": "AndroidPlayer", "version": "2021.3.30f1", "path": "/Users/xxx/Unity/Hub/Editor/2021.3.30f1/Editor/Data/PlaybackEngines/AndroidPlayer" } ]

  如果你发现某个 Unity 版本的 Android 构建突然失败，第一件事就是打开这个文件，确认AndroidPlayer模块的path是否真实存在。曾经有同事误删了PlaybackEngines文件夹，导致 Hub 显示“已安装”，但 Editor 构建时疯狂报Could not find AndroidPlayer module。原因就在这里。

3. 创建双端项目前的硬性前置检查清单（逐项手敲验证）

在你点击“Create”按钮之前，请务必完成以下七项检查。这不是建议，是强制流程。每一项都对应一个高频、隐蔽、且修复成本极高的故障点。我把它做成一张可打印的检查表，贴在显示器边框上，团队新人入职第一周必须逐条打钩。

3.1 为什么 macOS 12.0 是硬门槛？——Metal API 与 Rosetta 2 的双重枷锁

这个问题常被忽略。Unity 从 2021.2 开始，将 iOS 构建的默认渲染后端从 OpenGL ES 切换为 Metal。而 Metal 的完整支持，要求 macOS 系统内核提供特定的 GPU 驱动接口。Apple 在 macOS 12.0 中首次完整开放了这些接口，并优化了 Rosetta 2 对 ARM64 架构的模拟效率。

如果你在 macOS 11.6 上强行安装 Xcode 14，会遇到一个诡异现象：Xcode 可以启动，也能创建 iOS 工程，但 Unity Editor 在调用xcodebuild时，会返回error: The requested device could not be found because no available devices matched the request.。根本原因，是 macOS 11.6 的 Rosetta 2 无法正确模拟 Xcode 14 所需的 Metal 编译器metal。解决方案只有一个：升级系统。别试图找“兼容补丁”，这是 Apple 硬件层的限制，绕不过去。

3.2xcode-select --install的真相：它安装的不是 Xcode，而是“影子工具集”

很多开发者以为xcode-select --install是在安装 Xcode。大错特错。它安装的是一个独立于 Xcode.app 的、精简版的命令行工具集（Command Line Tools），体积仅约 200MB，包含clang,git,make,xcodebuild等核心命令。它的作用，是让系统在没有完整 Xcode.app 的情况下，也能执行基础编译任务。

但 Unity iOS 构建必须使用完整 Xcode.app 中的xcodebuild，而非 CLT 中的同名命令。为什么？因为 Unity 需要调用 Xcode 的私有框架（如IDEFoundation.framework）来动态生成.xcworkspace和配置Build Settings。CLT 中的xcodebuild是阉割版，不具备此能力。

所以，正确的顺序是：

1. 先从 Mac App Store 安装完整版 Xcode 14.2+；
2. 打开一次 Xcode，让它完成首次初始化（同意协议、安装额外组件）；
3. 再运行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer，将系统默认工具链指向 Xcode.app；
4. 最后运行xcode-select --install—— 这步其实已非必需，但能确保git等基础工具可用。

注意：sudo xcode-select -s ...这条命令必须由管理员执行，且会影响整个系统的xcodebuild路径。如果你的机器上还跑着其他 iOS 开发项目（如原生 Swift 项目），请确保它们也兼容此路径。否则，切回 CLT 的命令是sudo xcode-select --reset。

3.3 Android SDK Platform-tools 34.0.5：那个被 Google 隐藏的“兼容开关”

Google 在 2023 年发布的 Platform-tools 34.0.5，是一个关键的兼容性里程碑。它首次正式支持 Android 14（API 34）的adb协议，并修复了与 Unity Editor 2021.3+ 的握手 Bug。如果你使用的是 33.0.3 或更早版本，会遇到一个经典问题：Editor 能识别到连接的 Android 设备，但在点击“Build and Run”时，控制台疯狂刷adb: error: device 'xxxx' not found，而adb devices命令在终端里却显示设备在线。

根因在于adb协议的握手流程变更。旧版adb在启动 daemon 时，会尝试绑定一个随机端口，而 Unity Editor 的 Android 构建模块，会硬编码一个固定端口（5037）去连接它。34.0.5 之后，adb引入了ADB_SERVER_SOCKET环境变量机制，允许外部程序指定 daemon 的监听地址。Unity Hub 自带的 SDK，正是通过这个机制，确保 Editor 与adbdaemon 的通信通道绝对可靠。

验证方法很简单：打开终端，输入which adb。如果输出路径是~/Library/Android/sdk/platform-tools/adb，说明你用的是 Hub 自带 SDK；如果是/usr/local/bin/adb或/opt/homebrew/bin/adb，说明你用的是 Homebrew 或手动安装的 SDK，请立即切换。切换命令：

# 临时切换（仅当前终端有效） export PATH="/Users/yourname/Library/Android/sdk/platform-tools:$PATH" # 永久切换（写入 ~/.zshrc） echo 'export PATH="/Users/yourname/Library/Android/sdk/platform-tools:$PATH"' >> ~/.zshrc source ~/.zshrc

4. 创建项目时的模板、设置与陷阱：从“Hello World”到“真机可运行”的鸿沟

现在，你已经通过了所有前置检查。打开 Unity Hub，“New Project”，选择模板。这一刻，你的每一个点击，都在为后续三个月的开发体验投票。我们来逐项拆解。

4.1 模板选择：URP、Built-in、HDRP？哪个才是双端安全牌？

Unity 官方提供了三个主流模板：3D (URP)、3D (Built-in)、3D (HDRP)。对于 Android & iOS 双端项目，唯一安全的选择是3D (URP)。理由如下：

• Built-in Render Pipeline（内置管线）：它已进入维护模式，Unity 官方明确表示，自 2023 年起，不再为其添加新功能。更重要的是，它对 iOS Metal 的支持是“尽力而为”（best-effort）。在 iPhone 8 及更老机型上，Built-in 会自动降级到 OpenGL ES，但降级逻辑不稳定，极易导致纹理采样错误、UI 渲染错位。我们曾有一个项目，在 iPhone 7 上运行 Built-in 模板，主界面按钮全部变成紫色方块——因为 Metal 降级时，Shader 的UNITY_DECLARE_TEX2D宏未被正确重定义。

• HDRP（高清渲染管线）：它是为高端 PC 和主机设计的，对移动端 GPU（尤其是 Mali-G76、Adreno 640）支持极差。即使你强行开启 HDRP 的移动端简化模式，也会遇到Shader compilation failed for 'HDRP/Lit': Unsupported platform这类编译错误。HDRP 的 Shader Graph 节点，在移动端的编译器后端（SPIR-V）上，有大量未实现的指令。

• URP（通用渲染管线）：它是 Unity 为跨平台（尤其是移动平台）量身打造的。它内置了针对 Mali、Adreno、Apple A 系列芯片的 Shader 编译优化规则；它的 Light Probe 系统在低端 Android 设备上内存占用比 Built-in 低 40%；它对 Metal 的支持是“原生级”的，无需降级。更重要的是，URP 的Lightweight Render Pipeline Asset可以精细控制每个平台的渲染特性，比如关闭 iOS 的 Screen Space Reflections，保留 Android 的 Shadow Distance。

实操心得：不要被“URP 学习成本高”吓退。URP 的核心配置只有三个文件：URP Asset（全局渲染参数）、Renderer Feature（后处理效果）、Shader Graph（材质）。对于新项目，你完全可以先用默认 URP Asset，等美术资源到位后再逐步优化。起步阶段，URP 的稳定性远胜于 Built-in 的“玄学”。

4.2 项目名称与路径：一个影响 Git 协作的隐形雷区

项目名称看起来无关紧要，但它会直接影响到 Git 仓库的 URL 结构和 CI/CD 流水线的解析逻辑。我们团队踩过一个深坑：一位同事创建项目时，项目名称用了中文“我的第一个游戏”，Hub 自动生成的路径是/Users/xxx/UnityProjects/我的第一个游戏。当他在 GitHub 上创建仓库时，URL 变成了https://github.com/xxx/%E6%88%91%E7%9A%84%E7%AC%AC%E4%B8%80%E4%B8%AA%E6%B8%B8%E6%88%8F。CI 流水线脚本里有一行cd $PROJECT_NAME，在 Linux 服务器上执行时，$PROJECT_NAME变量被解析为乱码，导致整个构建失败。

解决方案极其简单，但必须成为肌肉记忆：

• 项目名称只能包含英文、数字、下划线（_）、短横线（-）
• 路径不能包含空格、中文、特殊符号（如括号、顿号、波浪线）
• 推荐命名法：全小写 + 短横线分隔，如mobile-game-core、ios-android-starter

这样做的好处不仅是 Git 友好，还能避免 Unity Editor 在解析Assets/Plugins/Android目录下的.jar文件时，因路径编码问题导致ClassNotFoundException。

4.3 创建后的第一件事：立刻验证双端构建能力，而非写代码

项目创建完成，Unity Editor 自动打开。此时，90% 的开发者会立刻双击Assets文件夹，开始拖拽模型、编写Start()函数。这是最危险的习惯。你应该做的第一件事，是立刻进行一次“空项目构建验证”。

Android 验证步骤：

1. File → Build Settings...
2. Platform选择Android，点击Switch Platform
3. 点击Player Settings...，在Other Settings里，确认Package Name已填写（如com.yourcompany.mobilegame），Minimum API Level设为Android 10 (API Level 29)（这是目前 Google Play 的最低要求）
4. 回到Build Settings，点击Build，保存为Builds/android-empty.apk
5. 将 APK 拖到已连接的 Android 手机上，安装并打开。看到 Unity 的默认蓝屏，即成功。

iOS 验证步骤：

1. File → Build Settings...
2. Platform选择iOS，点击Switch Platform
3. 点击Player Settings...，在Identification里，确认Bundle Identifier已填写（格式同 Android Package Name），Target Device设为iPhone，Architecture设为ARM64
4. 回到Build Settings，点击Build And Run，选择一个空文件夹（如Builds/ios-empty）
5. Unity 会自动生成一个 Xcode 工程。打开Builds/ios-empty/Unity-iPhone.xcworkspace，在 Xcode 顶部选择你的 iPhone 设备（非模拟器），点击运行按钮 ▶️。等待几秒，看到 Unity 的蓝屏出现在真机上，即成功。

关键经验：这个“空项目构建”必须在创建项目后的 10 分钟内完成。它能暴露 80% 的环境配置问题。如果 Android 构建失败，90% 是 SDK/NDK 路径问题；如果 iOS 构建失败，90% 是 Xcode 工具链或证书问题。此时修复，成本最低。等你写了两周代码再构建，报错堆栈会淹没在上千行日志里，定位难度指数级上升。

5. 常见构建失败的完整排查链路：从报错日志到根因定位

即便你严格执行了以上所有步骤，构建失败仍可能发生。下面，我以一个真实案例，带你走一遍完整的、可复现的排查链路。这不是“答案速查表”，而是教你如何像一个资深工程师一样思考。

5.1 案例背景：iOS 构建卡在Compiling Shader 'Hidden/PostProcessing/Uber'

现象：在 Unity Editor 中点击Build And Run，Xcode 工程生成成功，但 Xcode 编译时，在CompileShader阶段卡住，控制台输出：

Compiling Shader 'Hidden/PostProcessing/Uber' ... error: Metal: Compilation failed for shader 'Hidden/PostProcessing/Uber', variant 'metal_frag', target 'metal_ios': program_source:123: error: use of undeclared identifier 'metal::float3'

第一反应：Shader 写错了？Post Processing 包版本不兼容？立刻去 GitHub 查 URP 和 Post Processing 的 issue 列表？错。这是典型的“过早归因”。

正确排查链路：

Step 1：锁定错误源头是 Metal 编译器，而非 Unity Shader

• 错误信息中明确写着Metal: Compilation failed，且提到了metal::float3。这是一个 C++ 命名空间，属于 Apple 的 Metal Standard Library（MSL）。
• 这说明，Unity 的 Shader 编译器（ShaderCompilerWorker）已经成功将 HLSL 转换为 MSL，但 MSL 代码在被 Apple 的metal编译器编译时失败了。
• 因此，问题不在 Unity 的 Shader Graph 或 URP Asset，而在Xcode 的 Metal 编译器版本。

Step 2：验证 Xcode 的metal编译器版本

• 打开终端，执行：

  /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/metal/metal --version

• 如果输出是Apple clang version 14.0.0 (clang-1400.0.29.202)，说明你用的是 Xcode 14.2，其metal编译器版本为 14.0.0。
• 但metal::float3是在Xcode 14.3中才引入的 MSL 新特性。14.2 的 MSL 标准库中，对应的类型是float3，没有metal::命名空间。

Step 3：确认 URP 版本与 Xcode 的兼容性矩阵

• 查阅 Unity 官方文档《URP Compatibility Matrix》，发现：
  • URP 14.0.0+ 要求 Xcode 14.3+
  • URP 12.1.0 ~ 13.1.0 兼容 Xcode 14.2
• 此时，你项目里用的 URP 包版本是 14.0.2（最新版），而本地 Xcode 是 14.2。版本不匹配。

Step 4：解决方案

• 方案 A（推荐）：升级 Xcode 到 14.3+。从 Mac App Store 更新即可。
• 方案 B（临时）：降级 URP 包。在 Unity Editor 中，Window → Package Manager，找到Universal RP，点击右上角齿轮图标 →Show in Project，然后在Packages/manifest.json中，将"com.unity.render-pipelines.universal"的版本号从"14.0.2"改为"13.1.0"，保存。Unity 会自动重新导入。

Step 5：验证修复

• 删除Library文件夹（强制 Unity 重新编译所有 Shader）
• 重新执行Build And Run
• Xcode 编译通过，真机运行成功。

这个案例的价值在于：它展示了如何从一行看似晦涩的编译错误，逆向推导出工具链版本冲突。真正的高手，不是记住所有报错，而是掌握一套通用的“错误溯源”方法论。核心就三点：1）看错误前缀，锁定责任方（Metal？Gradle？Xcode？）；2）用命令行工具验证该责任方的版本与状态；3）查官方兼容性矩阵，做版本对齐。这套方法，适用于 95% 的构建失败。

5.2 Android 构建失败：Execution failed for task ':launcher:processDebugResources'

现象：Android 构建时，Gradle 报错，末尾是AAPT: error: resource android:attr/lStar not found.

排查链路：

Step 1：识别lStar属性的来源

• lStar是 Android 12（API 31）引入的新属性，用于 Material You 动态色彩系统。
• AAPT（Android Asset Packaging Tool）报找不到它，说明你项目中引用的某个 Android 库（通常是androidx.core:core或com.google.android.material:material），其compileSdkVersion设为了 31+，但你的 Unity 项目Player Settings中的Target API Level却低于 31。

Step 2：检查 Unity 的 Android Target API

• Edit → Project Settings → Player → Android → Other Settings
• 找到Target API Level，确认其值。如果它是Automatic (highest installed)，而你本地最高只装了 Android SDK 30，那么 Unity 会强制使用 API 30，但 Gradle 依赖的库却要求 API 31，冲突产生。

Step 3：统一 SDK 版本

• 在 Hub 中，Settings → Installs → Add Modules，勾选Android SDK Platform 31并安装。
• 回到 Unity，Player Settings，将Target API Level手动设为Android 12.0 (API Level 31)。
• 在Publishing Settings中，确认Custom Main Gradle Template已勾选，然后打开Assets/Plugins/Android/mainTemplate.gradle，在android { }块内，添加：

  compileSdkVersion 31 defaultConfig { targetSdkVersion 31 }

Step 4：清理并重建

• Assets → Reimport All
• 删除Temp和Library文件夹
• 重新构建

这个过程再次印证：Android 构建失败，80% 是 SDK 版本碎片化导致的。Hub 自带的 SDK、系统全局 SDK、Gradle 依赖的 SDK，三者必须严格对齐。而 Unity Editor 的 UI 设置，只是其中一环。

6. 项目创建后的必做五件事：让团队协作与持续集成真正落地

项目创建成功，双端构建验证通过，这只是万里长征第一步。为了让这个项目能真正进入团队协作、CI/CD 流水线、以及长期维护的轨道，还有五件关键的事，必须在第一天就做完。它们不难，但遗漏任何一件，都会在未来某天，让整个团队陷入“为什么我的电脑可以，他的不行”的泥潭。

6.1 生成并提交.gitignore：不是模板，是定制化清单

Unity 项目特有的文件，必须被 Git 精确过滤。一个通用的.gitignore模板远远不够。你需要根据本次创建的项目特性，定制它。

• 必须忽略的 Unity 生成文件：

  • Library/：Unity 的缓存数据库，完全二进制，体积巨大，且每个开发者机器上的内容都不同。
  • Temp/：临时编译文件，每次构建都会刷新。
  • Obj/：C++ 插件的中间对象文件。
  • Builds/：构建产物，应由 CI 流水线生成并上传到制品库，而非放入 Git。

• 必须纳入 Git 的关键文件：

  • ProjectSettings/下的所有.asset文件：它们存储了Player Settings、Graphics Settings、Input Manager等核心配置。缺少它们，新成员 clone 项目后，连 Android 包名都看不到。
  • Packages/manifest.json：这是 Unity Package Manager 的“合同”，精确锁定了所有第三方包的版本。没有它，com.unity.render-pipelines.universal可能被自动升级到不兼容版本。
  • Assets/Plugins/Android/AndroidManifest.xml（如果自定义过）：这是 Android 的“宪法”，权限、Activity、Application 类都定义于此。

• 定制化项（本次项目专属）：

  • 因为本项目是双端，需额外忽略：
    • Assets/Plugins/iOS/：如果项目里有自定义 iOS 原生插件，其.m、.h文件应纳入 Git，但编译后的.a静态库必须忽略。
    • Assets/Plugins/Android/libs/：同理，.so文件忽略，.jar、.aar源文件纳入。

实操技巧：在项目根目录创建.gitignore后，立即执行git status --ignored，查看哪些本该忽略的文件被 Git 错误地跟踪了。如果有，用git rm -r --cached <file>将其从索引中移除，再git commit。这一步，能避免未来数月的 Git 冲突噩梦。

6.2 初始化ci.yml：用 GitHub Actions 跑通第一次自动化构建

把构建流程自动化，是专业团队的分水岭。我们用最简单的 GitHub Actions，为这个新项目写一个ci.yml。

# .github/workflows/ci.yml name: Unity Build on: [push, pull_request] jobs: build-android: name: Build Android APK runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Unity uses: game-ci/unity-builder@v3 with: unityVersion: 2021.3.30f1 targetPlatform: Android - name: Upload Artifact uses: actions/upload-artifact@v3 with: name: android-apk path: build/android/Build.apk build-ios: name: Build iOS Xcode Project runs-on: macos-12 steps: - uses: actions/checkout@v3 - name: Setup Unity uses: game-ci/unity-builder@v3 with: unityVersion: 2021.3.30f1 targetPlatform: iOS - name: Upload Artifact uses: actions/upload-artifact@v3 with: name: ios-xcode-project path: build/ios/

这个 YAML 的关键点：

• runs-on: macos-12：iOS 构建必须在 macOS 环境，且版本必须 ≥ 12，与我们前面的前置检查一致。
• game-ci/unity-builder@v3：这是一个专为 Unity 设计的 Action，它会自动下载并配置指定版本的 Unity Editor，无需你手动管理。
• targetPlatform: iOS：它会自动调用BuildPipeline.BuildPlayer，生成 Xcode 工程，而非 IPA（因为签名需要开发者证书，CI 环境通常不存放私钥）。

第一次 push 这个文件后，GitHub Actions 会自动触发。如果 Android 构建成功，说明你的manifest.json和ProjectSettings已被正确提交；如果 iOS 构建成功，说明你的 Unity 版本与 macOS 环境兼容。这是对整个项目健康度的终极快照。

6.3 创建README.md：用三句话说清“这个项目是什么、怎么跑、谁负责”

一个专业的README.md，不是项目介绍，而是新成员的“快速上手协议”。

# Mobile Game Starter (Android & iOS) A minimal, production-ready Unity project template for cross-platform mobile development. ## Quick Start 1. Clone this repo. 2. Open with Unity Hub (requires Unity 2021.3.30f1 or later). 3. `File → Build Settings → Switch to Android/iOS → Build`. ## Key Configurations - **Android**: Target API Level 31, Package Name `com.example.mobilegame` - **iOS**: Bundle Identifier `com.example.mobilegame`, Deployment Target iOS 14.0 - **Rendering**: Universal Render Pipeline (URP) v13.1.0

这份README的价值在于：它把所有分散在 UI 里的配置，浓缩成可搜索、可复制的文本。当新成员问“Android 包名是多少？”，你不用截图，直接让他cat README.md | grep "Package Name"。

我在实际项目中发现，一个写得好的README，能让新成员的上手时间从 2 小时缩短到 15 分钟。因为它消除了所有“我不知道该问谁”的模糊地带。

7. 我的个人体会：创建项目，是写给未来自己的第一封信

写