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.jsonHub 的所有决策并非凭空产生它把关键配置持久化在两个文件里理解它们等于拿到了环境仲裁的源代码。~/.hubsettingsmacOS/Linux或%APPDATA%\UnityHub\.hubsettingsWindows这是一个 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”按钮之前请务必完成以下七项检查。这不是建议是强制流程。每一项都对应一个高频、隐蔽、且修复成本极高的故障点。我把它做成一张可打印的检查表贴在显示器边框上团队新人入职第一周必须逐条打钩。序号检查项验证方法通过标准失败后果1macOS 系统版本 ≥ 12.0 (Monterey)终端执行sw_versProductName: macOSProductVersion: 12.x或更高Xcode 14 无法安装iOS 构建链断裂2Xcode 已安装且版本 ≥ 14.2终端执行xcode-select -p输出/Applications/Xcode.app/Contents/DeveloperHub 无法识别 XcodeiOS 构建按钮禁用3Xcode 命令行工具已安装终端执行xcode-select --install返回command line tools are already installedxcodebuild命令不可用构建中断4Unity Hub 自带的 OpenJDK 已启用Hub 设置 → Installs → 选中版本 → “Show Modules”OpenJDK行状态为 “Installed”Android 构建报JAVA_HOME not set5Android SDK Platform-tools 版本 ≥ 34.0.5终端执行~/Library/Android/sdk/platform-tools/adb --version输出Android Debug Bridge version 34.0.5或更高adb无法连接真机Logcat 无输出6硬盘剩余空间 ≥ 25GBFinder 查看启动盘容量可用空间 25GBHub 下载 SDK/NDK 时静默失败无提示7网络 DNS 解析正常国内用户重点终端执行nslookup registry.npmjs.org返回有效 IP 地址Hub 下载 URP 包超时项目创建卡在“Installing packages”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是阉割版不具备此能力。所以正确的顺序是先从 Mac App Store 安装完整版 Xcode 14.2打开一次 Xcode让它完成首次初始化同意协议、安装额外组件再运行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer将系统默认工具链指向 Xcode.app最后运行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 14API 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 ~/.zshrc4. 创建项目时的模板、设置与陷阱从“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 验证步骤File → Build Settings...Platform选择Android点击Switch Platform点击Player Settings...在Other Settings里确认Package Name已填写如com.yourcompany.mobilegameMinimum API Level设为Android 10 (API Level 29)这是目前 Google Play 的最低要求回到Build Settings点击Build保存为Builds/android-empty.apk将 APK 拖到已连接的 Android 手机上安装并打开。看到 Unity 的默认蓝屏即成功。iOS 验证步骤File → Build Settings...Platform选择iOS点击Switch Platform点击Player Settings...在Identification里确认Bundle Identifier已填写格式同 Android Package NameTarget Device设为iPhoneArchitecture设为ARM64回到Build Settings点击Build And Run选择一个空文件夹如Builds/ios-emptyUnity 会自动生成一个 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 RunXcode 工程生成成功但 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 LibraryMSL。这说明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.3URP 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 RunXcode 编译通过真机运行成功。这个案例的价值在于它展示了如何从一行看似晦涩的编译错误逆向推导出工具链版本冲突。真正的高手不是记住所有报错而是掌握一套通用的“错误溯源”方法论。核心就三点1看错误前缀锁定责任方MetalGradleXcode2用命令行工具验证该责任方的版本与状态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 12API 31引入的新属性用于 Material You 动态色彩系统。AAPTAndroid 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 APIEdit → 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并安装。回到 UnityPlayer 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/checkoutv3 - name: Setup Unity uses: game-ci/unity-builderv3 with: unityVersion: 2021.3.30f1 targetPlatform: Android - name: Upload Artifact uses: actions/upload-artifactv3 with: name: android-apk path: build/android/Build.apk build-ios: name: Build iOS Xcode Project runs-on: macos-12 steps: - uses: actions/checkoutv3 - name: Setup Unity uses: game-ci/unity-builderv3 with: unityVersion: 2021.3.30f1 targetPlatform: iOS - name: Upload Artifact uses: actions/upload-artifactv3 with: name: ios-xcode-project path: build/ios/这个 YAML 的关键点runs-on: macos-12iOS 构建必须在 macOS 环境且版本必须 ≥ 12与我们前面的前置检查一致。game-ci/unity-builderv3这是一个专为 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. 我的个人体会创建项目是写给未来自己的第一封信写