1. 为什么 Unity 项目会需要命令行
1.1 重复打点、打包和分发有多烦
先说一个很现实的场景：Unity 2021、2022 的项目做久了，你会发现自己每天有一大堆机械操作——打开编辑器、等工程加载完、切到 Build Settings、选平台、配签名、改版本号、点 Build，然后等编译、等资源打底，盯着进度条发呆。一个人做 demo 还能忍，一个四五人的小团队要做 Android、iOS、WebGL 多平台日常提测包时，这一套动作往往要重复好几遍。更难受的是中间稍微改错一个选项，比如版本号漏改、签名选错、IL2CPP 忘开，又是十几分钟的等待成本。真正让我决定动手做工具的触发点，是好几个晚上都在重复做同一件事：帮同事补一个测试包，然后发现构建的版本号不对，又得重新等一次。那时候我就想，这类事一开始就应该用一个 CLI 工具解决，而不是靠人肉去记、去盯。
所谓 CLI 工具，就是脱离 Unity 编辑器，直接在终端里通过命令完成常用构建任务的程序。它的价值不在于替代什么高大上的引擎功能，而是把你日常的工作流压缩成一行命令。以前要三步五步、盯着界面点半天的事情，现在一条命令跑完，日志自动归档，结果清晰可见。这个工具我在给 Unity 2021、2022 项目做自动化的过程里反复打磨过，后来整理了一版放到开源仓库，一方面是自己团队在新的项目里可以直接复用，另一方面也是希望给有同样痛点的 Unity 开发者一个参考起点。
1.2 Unity 批处理模式，一条命令能做多少事
很多 Unity 开发者可能不知道，Unity 命令行模式其实是一个从很早就存在、并且一直被官方保留的能力。通过给可执行文件传参，比如-batchmode -nographics -quit -projectPath -executeMethod，就可以让 Unity 不开编辑器窗口、不加载图形界面，直接执行你写好的某个静态方法，执行完了自动退出。
这看起来简单，但实际能做的事情非常多：
- 执行自定义构建脚本，生成 APK、AAB、Xcode 导出工程
- 批量打 AssetBundle，做资源校验
- 跑项目里的单元测试，或者做静态检查
- 自动化生成 SpriteAtlas、图标、版本号信息等素材
- 把构建版本号、提交 hash 写进 PlayerSettings 或者打包配置
在 2021、2022 这些版本里，批处理模式一直是持续集成和自动化构建最稳定的入口。我们团队的自动化平台、构建机、定时出包脚本，底层本质上都是在调用这一套命令行能力。但是 Unity 原生的命令有个问题：参数很长、格式容易记错、路径带空格又容易踩坑，而且不同版本、不同平台的参数还有细微差异。于是真正有价值的是做一个外层封装，把这些细节消化掉，让使用者面对的是一个简洁、稳定的命令接口。
1.3 为什么选择外部 CLI 而不是编辑器扩展
有人会问：既然 Unity 本身能写EditorWindow、能配置菜单，为什么还要另外做一个命令行工具？原因很简单：大部分内部提测、版本交付、自动化检查的场景，是需要被脚本、定时任务、构建机器去驱动的，而不是靠一个人类打开 Unity 再点按钮。编辑器扩展解决的是"让人在 Unity 里操作更舒服"，而 CLI 解决的是"让程序去替代人"。两者解决的问题方向不一样。
菜单扩展适合面向美术、策划这类不碰命令行的同事；但是到了 CI、构建机、自动发布流程里，没有图形界面，没有点击入口，只有命令行和脚本。CLI 工具就像一个接线员，把终端里友好的命令翻译成 Unity 能理解的批处理参数。另外，多项目场景下同一个工具可以复用，只要项目用 Unity 2021、2022，结构一致，配置改改就能跑，这个灵活性是编辑器内代码很难比的。
2. 工具的核心设计与实现思路
2.1 整体架构：一个壳，包住 Unity 的命令行模式
我实现的这个 CLI 工具，本质上是把 Unity 的命令行参数封装成一堆易用的子命令。整体架构不是很复杂，但分层很清楚。从使用角度看，它提供build、batch、log这几个核心子命令。build负责单一平台构建，batch负责批量处理多个项目的构建，log负责从构建日志里提取关键信息。在代码层面，它大致分成了几个模块：配置解析、Unity 路径探测、批处理参数组装、进程生命周期管理、日志与状态输出。
配置解析模块处理一个 JSON 格式的本地配置文件，比如把项目路径、输出目录、Unity 安装路径放在一张表里。Unity 路径探测是很多人容易忽略的细节。Windows 上通过 Hub 安装的 Unity，路径通常在一个固定目录下，每个版本号一个子目录。工具会在几个默认位置里搜索，同时允许用户在配置里显式指定，这样在构建机上就不会因为装到了别的盘而找不到引擎。
进程管理是所有 CLI 工具里最需要小心的一环。我用的是 Node.js 的child_process.spawn，而不是exec，原因有两个：第一，spawn 可以直接传参数数组，不需要拼字符串，能有效避开路径带空格的各种问题；第二，spawn 的 stdout 和 stderr 可以使用流式处理，构建过程中的进度和报错能实时透传到终端，而不是等整个进程结束才一次性输出。统一封装了一个runUnity函数，调用方只需要传入目标和方法名，它负责拼参数、启动进程、等待退出、收集日志。如下图所示：
const { spawn } = require('child_process'); function runUnity(binaryPath, projectPath, method, extraArgs = []) { const args = [ '-batchmode', '-nographics', '-quit', '-projectPath', projectPath, '-executeMethod', method, ...extraArgs ]; return new Promise((resolve, reject) => { const child = spawn(binaryPath, args, { stdio: ['ignore', 'pipe', 'pipe'] }); child.stdout.on('data', chunk => process.stdout.write(`[unity] ${chunk}`)); child.stderr.on('data', chunk => process.stderr.write(`[unity-err] ${chunk}`)); child.on('close', code => { if (code === 0) { resolve(); } else { reject(new Error(`Unity exited with code ${code}`)); } }); child.on('error', err => reject(err)); }); }2.2 参数设计：让构建配置外置化
这个工具的设计里，我最满意的一个点是把常见构建配置参数化，而不是让使用者在构建脚本里写死。比如每次打包前都要改的版本号、包名、输出目录、Scripting Backend、目标平台，都可以通过命令行传入。它的命令形式大概是这样：
unity-cli build \ --project ./demo \ --target android \ --version 1.2.3 \ --output ./builds/demo-1.2.3.apk其中--version不只是打包的时候显示的数字，它会在执行阶段通过PlayerSettings.bundleVersion写进 PlayerSettings。这样每次出包前不再需要手动修改代码里的版本号。同理还有--build-number，对应 Android 的versionCode和 iOS 的buildNumber。
参数设计上有一条经验：不要把 Unity 的底层参数直接暴露出来作为 CLI 参数。比如让用户去记-executeMethod那段完全没意义。CLI 的职责是定义"语义化"参数，再由内部完成到 Unity 参数的翻译。这样一来，即使以后 Unity 换了一套批处理参数，改内部映射表就行，使用者的命令可以保持稳定。实际效果就是，团队里任何人接手打包任务，不再需要看一堆打包文档，只需要看一条 help 命令就够了。
2.3 进程管理：启动、等待、识别成功与失败
Unity 的批处理模式有个特点：正常执行时会产生大量日志，但有些阶段是静默的，甚至卡住的时候看起来就像死了一样。所以进程管理不只是 spawn 一下就结束，要处理几个关键点。
第一是超时机制。我预设了一个可配置的超时时间，默认 30 分钟，超过这个时间工具会主动判断这次构建异常，然后杀掉 Unity 进程并给出提示。这个在 CI 环境里尤其有用，因为如果没人看着，某个构建卡在资源导入或者 Shader 编译上，会占着构建机几个小时。第二是退出码的可靠性问题。Unity 在-batchmode下，某些失败场景不会返回非 0 退出码，这个我专门在后面的排查部分会展开讲。第三是要区分"工具本身出错"和 "Unity 项目构建失败"。前者比如命令参数写错了、Unity 路径配错了，工具应该快速失败并给出清晰的错误提示；后者则要完整收集日志、解析日志中的error和Build Failed关键字，再向调用方报告。
2.4 日志与状态反馈：CLI 不只是“黑窗口”
很多人对命令行工具的印象是黑色窗口加一堆滚屏，其实好的 CLI 在设计上是需要注意体验的。日志模块我做了分级：普通信息用灰色，警告用黄色，错误用红色。为了让日志更好读，输出的时候会带上时间戳和阶段标记，比如[build][android] 开始执行、[build][android] 编译完成，用时 3分18秒。颜色不是必须的，但我做进去之后，团队同事明显更容易从一大段日志里定位到问题所在。
实时性也值得提到。Unity 的-logFile参数可以指定写到文件，但在长构建过程中如果只是写文件，人不守着终端的话根本不知道进展。所以我默认让构建输出直接走 stdout，同时在内部保留一份完整日志文件，路径会在命令结束时打印出来。这样双轨制的好处是：日常使用能看到进度，出错复盘时又能找到完整上下文。工具还内置了一个log命令，可以对历史日志做关键字筛选，例如只看error、warning、Building Library这类关键行，这在定位构建日志的时候非常救命。
3. 从零跑通一次真实构建
3.1 环境准备与安装
想把工具跑起来，环境准备其实不复杂。要求是系统里有 Node.js 16 或以上版本，安装方式按官方文档走就行，没有别的依赖。装好之后，把工具安装到全局：
npm install -g unity-cli安装完执行unity-cli --help就能看到所有可用命令。如果出现命令找不到，大概率是 Node.js 的全局 bin 目录没有加到系统变量里，这个和普通 npm 全局工具的问题一致。然后需要做一份本地配置文件，放在项目根目录，名字叫unity-cli.config.json：
{ "unityPath": "C:/Program Files/Unity/Hub/Editor/2021.3.30f1c1/Editor/Unity.exe", "projectPath": "./demo", "platform": "android", "outputDir": "./builds" }如果你的 Unity 是装在默认位置的，这个文件甚至可以只写projectPath和platform，工具会自动去常见目录探测 Unity 可执行文件。我见过不少同事第一次使用时卡在路径格式上，这里提醒一句：Windows 的路径分隔符建议用正斜杠/，反斜杠在 JSON 里要转义成\\，少写一个转义就报错，挺烦的。把配置写好之后，先跑一条最轻的命令验证环境，比如unity-cli batch --list，让它输出当前 Unity 版本以及项目里的构建器列表，确认没问题再进入正式打包。
3.2 Android 包构建实例
环境准备好了，打包就是一条命令的事。我拿一个实际项目来演示。这个项目的配置里已经指定了平台为 Android，所以客户端上只需要显式传版本号和产物路径：
unity-cli build \ --project ./demo \ --target android \ --version 1.2.3 \ --build-number 20240816 \ --output ./builds/demo-1.2.3.apk工具执行的时候，内部会先检查 Android SDK、JDK、Gradle 的路径是否能在 Unity 的 Preferences 里找到。首次在新机器上打包，Unity 会自动补下 Gradle 依赖，这个耗时比较长，不是工具能绕过的。执行完以后，终端末尾会显示构建结果、产物大小和 SHA1 值。SHA1 这个信息是我特意加进去的，因为在交付测试包的时候，很多测试平台需要填包的唯一标识，直接从终端复制比跑到文件管理器里右键看信息省事得多。
这个命令背后对应的是构建器里的一个静态方法，逻辑上就是设置包名、版本号、目标平台，然后调用BuildPipeline.BuildPlayer。我建议所有 Unity 项目都保留一个名为BuildHelper的静态类，里面只放各平台构建方法，方便 CLI 统一调用。如果以后团队成员不满足于现成的命令，在这个类里扩展即可，不需要改外部工具的代码。
3.3 iOS 构建与 Xcode 工程生成
iOS 平台和 Android 有一个本质区别：Unity 本身不直接生成 ipa 文件，它只负责生成一个 Xcode 工程。好多人第一次接手 iOS 自动化时都会懵，以为-buildTarget iOS就能得到一个安装包，结果等半天只看到一个 Xcode 目录。工具里对 iOS 的处理是单独一个命令：
unity-cli build \ --project ./demo \ --target ios \ --version 1.2.3 \ --output ./builds/ios_project这个命令执行完，产物目录下是一个标准的 Xcode 工程。要继续打出 ipa，需要配合xcodebuild做签名和归档，那是 iOS 平台自己的流程，工具不干预。我的经验是，如果团队没有 Mac 构建机，iOS 的日常包还是得走人工步骤；但有了这一步自动生成工程，至少把最耗时、最无脑的导出环节省掉了。在很多公司里，iOS 工程生成这一步往往是急需自动化的，因为人工操作 Unity 导出 Xcode 工程最容易因为选项漏选、版本不匹配而出问题。
3.4 批量处理多项目的构建场景
一个 CLI 工具如果只能构建单个项目，价值会大打折扣。做工具之前，团队里可能有多个 Unity 2021、2022 项目，每天要出若干个小包。我把批量构建这个场景做成了一条子命令。假设有两个项目分别叫 demo 和 other_demo，配置都放在unity-cli.config.json的一个projects数组里，就可以这样执行：
unity-cli batch \ --version 2.0.0 \ --target android \ --output-root ./daily_builds批量模式下有三个细节值得注意。一是任务之间的执行策略。我默认是串行执行，也就是一个构建完成后再启动下一个。这样对内存的占用比较稳定，不会因为同时跑两个 Unity 而把构建机拖垮。二是版本号策略。批量构建时统一传的版本号会对所有项目生效，如果每个项目版本号不同，需要支持在配置文件里给每个项目单独指定。三是失败处理策略。默认一个项目失败就停止整个批处理，避免后面所有项目都在同一个错误上浪费时间；但如果你的场景是"一些项目允许失败"，也可以用--continue-on-error参数改成继续执行，最终统一汇报失败列表。
4. 实测中踩过的坑和排查手册
4.1 Unity 安装路径带空格
这个问题几乎每个 Windows 用户都会遇到。默认安装路径通常是C:\Program Files\Unity\...，里面带着空格。如果使用过程中把命令拼成字符串再用 shell 执行，很容易因为引号没处理好，导致 Unity 路径被拆成两段，最终报"找不到指定的文件"。做法很简单，不要用exec拼字符串启动进程，改用spawn直接传参数数组。如果项目里有的脚本是通过.bat调用的，那么整条命令行在.bat里的引号嵌套也很容易错。建议在.bat里通过配置的UNITY_PATH变量先存路径，再用"%UNITY_PATH%" -batchmode ...这种方式，减少引号位置引起的烦恼。
4.2 许可证与登录导致批处理中断
批处理模式下 Unity 对许可证的状态极其敏感。如果是新装的 Unity，还没有激活许可证，或者许可证正好过期，-batchmode执行请求会直接失败，而且不同小版本表现还不太一样，有的会在日志里给一个错误码，有的就干脆卡住不动弹。踩了几次之后，我的习惯是：任何构建机第一次安装 Unity 时，先手动打开一次编辑器，完成激活流程，确认能从命令行正常进入，再交给自动化工具去跑。有些节点的 CI 机器没有图形界面，也可以用命令行的方式配置许可证，但前提还是许可证本身在有效期内。如果遇到许可证错误，去 Unity 账号后台看一下当前这个订阅绑定的机器数，经常会发现是激活配额满了，而不是工具本身的问题。
4.3 退出码不可靠，日志才是关键
这是整个工具演进过程中最大的一个认知更新。早期判断构建成功与否只看进程退出码，发现有几次退出码是 0，但产物目录里根本没有 APK 文件。发生了什么？Unity 在某些场景下，比如构建过程里遇到了资源报错，但日志只是打了Build completed with a result of 'Failed'，进程却仍然以 0 退出。这让单纯依赖退出码的 CI 判空变得非常不靠谱。后来我在工具里加了产物校验：构建结束之后，先检查配置文件里的输出路径是否存在，文件大小是否大于阈值，同时解析日志，查找Build Failed、error CS、Exception等关键行。只有当"退出码为 0 + 输出文件存在 + 日志无错误关键字"三个条件同时满足，才判定为构建成功。这个逻辑救过很多次，强烈建议所有做 Unity 自动化的朋友采纳，别把健康检查完全交给退出码。
4.4 日志与路径中的编码乱码
在 Windows 上跑 CLI 工具，默认终端编码可能是 GBK 或者系统本地编码，而 Unity 的日志内容以及项目里包含中文资源路径、文件名时，极容易出现中文乱码。表现就是终端显示一堆铏氖之类的乱码，或者日志文件里看到的路径和实际路径对不上。处理办法有几个层面。工具的代码里对日志数据流做一次编码转换，统一成 UTF-8 再输出。终端侧使用 Windows Terminal 或者 VS Code 内置终端，并手动执行chcp 65001切换到 UTF-8 代码页，这样能明显减少乱码。资源路径方面，虽然 Unity 不要求项目路径必须是英文，但为了自动化工具和构建脚本的稳定性，我团队的约定是项目目录始终使用英文，避免很多不必要的跨平台问题。
5. 开源后想要分享的一点心得
5.1 这个工具的适用边界
要不要写一个这样的 CLI 工具，取决于团队规模与出包频率。如果一个月只出一两次包，那手工点几下就够了，不值得为此维护工具。但如果团队像我们一样，每天有多个版本、多个平台要出，早中晚还要跑自动化检查，那么这个投入就非常划算。工具说实话不是一个重量级平台，没有图形界面、没有云端控制台，但它解决的是一个频繁触达、容易出错的环节。对比一些重量级构建服务，它最大的优势是轻：本地一台机器就能跑，不依赖额外的网络服务，也不强制上传项目到某个后台，对代码安全性要求高的团队尤其合适。
5.2 代码组织与贡献建议
开源的时候我把代码结构整理得比较克制，核心部分就是一个包含构建器注册、Unity 进程调用、日志解析的lib目录。每个支持平台用一个独立模块维护，比如builders/android.js、builders/ios.js。新增一个平台的支持，只需要看现有模块的写法，复制一个再改参数就行，这个模式让贡献者低门槛参与。项目里内置的BuildHelper.cs是一个独立的 Unity 编辑器脚本，负责承接具体的构建逻辑。两边通过约定好的方法名「接线」：CLI 传入BuildHelper.DoBuildAndroid，编辑器脚本里实现对应的静态方法。这样的解耦让所有 Unity 版本相关的代码都收敛在 C# 脚本里，CLI 工具本身反而做到比较通用，这是我比较推荐的一种拆法。
5.3 下一步可以扩展的能力
做完一个版本并开源之后，日常使用中自己还是列了几个想做的扩展。第一是支持pre-build和post-build钩子，让使用者能在构建前跑单元测试、做资源检查，构建后自动压缩到归档目录或者上传到内部存储。第二是在批量构建时生成一份 Markdown 格式的报告，记录每个项目的构建时长、产物路径、提交版本号，直接发给相关同事，省去来回核对的时间。第三是支持接入内部 IM 的通知渠道，构建失败时把日志里的关键错误摘要推送出来，这样人在外面也能第一时间知道构建状态。这些都是锦上添花，但工具本身已经能够覆盖绝大多数 Unity 2021、2022 项目的日常自动化诉求，如果你也在被重复打包折腾，完全可以拿这个思路做一个适合自己团队的版本，或者直接拿来改一改就上生产。
