Unity MCPmanage_build工具完全指南从单平台构建到跨平台批量自动化【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp导读manage_build是 Unity MCP 提供给 AI 助手的核心构建管理工具让 LLM 可以直接触发 Unity Player 构建、切换目标平台、读写构建设置、管理构建场景与 Build Profile并串联多个平台执行批量构建。阅读本文后你将掌握该工具全部 8 种 action 的参数语义、返回结构、异步轮询机制以及构建任务在 Python Server 与 Unity Editor 两侧的完整调用链能够直接在 Claude、Cursor 等 MCP 客户端中指挥 AI 完成自动打包。工具定位与工作方式manage_build属于core工具组Python 侧注册位于 Server/src/services/tools/manage_build.pyUnity 侧实现位于 MCPForUnity/Editor/Tools/ManageBuild.cs。其工作方式是典型的桥接模式Python 侧通过mcp_for_unity_tool装饰器注册工具manage_build.py并将工具标记为destructiveHintTrue会修改项目/产生构建产物供客户端在调用前给出确认提示。工具函数将各参数做预处理布尔值强制转换、JSON 解析、逗号分隔场景解析然后通过send_with_unity_instance转发给对应 Unity 实例manage_build.py。Unity 侧的 ManageBuild.cs 通过McpForUnityTool(manage_build, RequiresPolling true, PollAction status, MaxPollSeconds 1800)声明其支持轮询——构建是耗时操作工具注册了status作为轮询动作最长轮询 1800 秒30 分钟。Unity 侧的HandleCommand是统一入口ManageBuild.cs先校验action是否为合法值再按 action 分发到HandleBuild、HandleStatus、HandlePlatform、HandleSettings、HandleScenes、HandleProfiles、HandleBatch、HandleCancel八个处理器。参数总览以下参数表完整对应工具注册定义manage_build.py其中仅action为必填参数类型必填说明actionstr是操作类型build、status、platform、settings、scenes、profiles、batch、canceltargetstr \| None—构建目标windows64、osx、linux64、android、ios、webgl、uwp、tvos、visionosoutput_pathstr \| None—构建输出路径scenesstr \| None—场景路径的 JSON 数组或逗号分隔的路径列表developmentstr \| None—是否为开发构建true/falseoptionsstr \| None—BuildOptions 的 JSON 数组clean_build、auto_run、deep_profiling、compress_lz4、strict_mode、detailed_reportsubtargetstr \| None—构建子目标player或serverscripting_backendstr \| None—脚本后端mono或il2cpp持久化修改profilestr \| None—Build Profile 资源路径仅 Unity 6propertystr \| None—设置属性product_name、company_name、version、bundle_id、scripting_backend、defines、architecturevaluestr \| None—要设置的属性值省略则读取当前值activatestr \| None—激活某个构建 Profiletrue/falsetargetsstr \| None—批量构建的目标 JSON 数组profilesstr \| None—批量构建的 Profile 路径 JSON 数组Unity 6output_dirstr \| None—批量构建的基础输出目录job_idstr \| None—用于status/cancel的作业 ID返回值为包含 Unity 响应的dict具体结构取决于 action。action 详解build触发单平台构建build是核心动作。Unity 侧 HandleBuild 的完整校验与调度流程如下若BuildPipeline.isBuildingPlayer为真直接报错构建已在进行中。通过BuildTargetMapping.TryResolveBuildTarget解析target未传target时默认使用当前激活平台随后校验平台是否已安装未安装时报错提示通过 Unity Hub 安装。解析output_path未指定时按 BuildTargetMapping.GetDefaultOutputPath 生成默认路径Windows 为Builds/{target}/{ProductName}.exe、macOS 为.app、Linux 为.x86_64、Android 视buildAppBundle设置输出.aab或.apk。解析scenes支持 JSON 数组与逗号分隔两种写法、development、options、subtarget。若指定scripting_backend会先调用PlayerSettings.SetScriptingBackend做持久化修改再继续构建仅接受mono/il2cpp。Unity 6 下若传入profile则走BuildPlayerWithProfileOptions的 Profile 构建路径见下文旧版本中该参数被忽略并输出警告。生成job_id通过 BuildRunner.ScheduleBuild 把构建调度到下一个EditorApplication.update回调中执行——因为BuildPipeline.BuildPlayer是同步阻塞调用直接执行会卡住命令分发线程。options参数支持 6 种官方写法但底层 BuildRunner.ParseBuildOptions 实际额外支持allow_debugging、connect_profiler、scripts_only、show_player、include_tests五种均可直接使用options 值对应 BuildOptionsclean_buildCleanBuildCacheauto_runAutoRunPlayerdeep_profilingEnableDeepProfilingSupportcompress_lz4CompressWithLz4strict_modeStrictModedetailed_reportDetailedBuildReportallow_debuggingAllowDebugging源码扩展connect_profilerConnectWithProfiler源码扩展scripts_onlyBuildScriptsOnly源码扩展show_playerShowBuiltPlayer源码扩展include_testsIncludeTestAssemblies源码扩展一个完整的构建请求示例{ action: build, target: windows64, output_path: Builds/Win/MyGame.exe, scenes: [\Assets/Scenes/Main.unity\, \Assets/Scenes/Level1.unity\], development: true, options: [\clean_build\, \auto_run\], scripting_backend: il2cpp }Python 侧的对应测试 Server/tests/test_manage_build.py 验证了参数转发、None 参数省略、options 数组解析与 scenes 数组解析行为。status查询构建状态轮询核心status是构建类工具异步协作的关键。行为分三种情况HandleStatus不传job_id优先返回最近一次仍在Building/Pending的作业以支持轮询中间件否则返回最后一次完成的构建再否则Unity 6读取BuildReport.GetLatestReport()返回最近一次 Unity 构建报告含result、platform、output_path、total_size_mb、duration_seconds、errors、warnings最后报错未找到构建作业。传入job_id且是批量作业返回批量进度completed、total、current_build。传入job_id且是单构建作业进行中返回PendingResponse轮询间隔 5 秒已完成返回SuccessResponse。单构建状态响应字段来自 BuildJob.ToStatusResponsejob_id、resultpending/building/succeeded/failed/cancelled/skipped、platform、output_path完成后追加total_size_mb、errors、warnings失败时追加error信息。platform读取或切换目标平台不传target时读取当前平台返回activeBuildTarget、target_group与standaloneBuildSubtarget传target时执行切换HandlePlatform校验平台已安装若已是目标平台则直接返回已在该平台。subtarget支持server/player会设置EditorUserBuildSettings.standaloneBuildSubtarget。通过EditorUserBuildSettings.SwitchActiveBuildTarget同步切换阻塞直至资源重导入完成返回新旧平台名。平台名映射完整定义见 BuildTargetMapping.cswindows64/windows/windows32、osx/macos、linux64/linux、android、ios、webgl、uwp、tvosvisionos仅在当前编辑器安装暴露BuildTarget.VisionOS时可用否则给出专门的安装提示。settings读写构建设置通过propertyvalue组合读写 7 种设置BuildSettingsHelper.csproperty读取实现写入实现product_namePlayerSettings.productName直接赋值company_namePlayerSettings.companyName直接赋值versionPlayerSettings.bundleVersion直接赋值bundle_idPlayerSettings.GetApplicationIdentifier(namedTarget)SetApplicationIdentifierscripting_backend返回il2cpp/mono仅接受il2cpp/monodefinesPlayerSettings.GetScriptingDefineSymbolsSetScriptingDefineSymbolsarchitecture映射x86_64/arm64/universal仅接受这三者none/default等价于x86_64省略value即读取写入后会回读返回最新值。settings会先通过BuildTargetMapping.TryResolveNamedBuildTarget将目标解析为NamedBuildTarget因此读写是按平台生效的。scenes管理 Build Settings 场景列表HandleScenes 同时支持读写不传scenes读取EditorBuildSettings.scenes返回每个场景的path、enabled、guid。传入字符串先尝试按 JSON 数组解析失败则按逗号分隔路径处理两者都会写入场景列表。传入数组支持纯字符串数组默认enabledtrue或{path: ..., enabled: true}对象数组。profiles管理 Build ProfileUnity 6HandleProfiles 仅在 Unity 66000.0编译旧版本返回明确错误。支持不传profile列出项目中全部t:BuildProfile资源及当前激活 Profile。传profile且activatetrue调用BuildProfile.SetActiveBuildProfile激活。传profile不激活返回该 Profile 的场景列表。在build动作中传入profile时Unity 6HandleProfileBuild 会加载 Profile 并通过BuildPlayerWithProfileOptions构建实际目标平台由 Profile 决定作业元数据使用当前激活平台。batch跨平台批量构建HandleBatch 一次串联多个构建串行执行前一个完成才启动下一个适合 CI 风格的一夜打全平台包targets与profiles二选一都传会报错都不传会报错。传入targets逐个解析并前置校验平台是否已安装输出路径默认放在output_dir默认Builds下按目标平台子目录组织。传入profilesUnity 6逐个校验 Profile 存在性输出到{output_dir}/{Profile名}/{ProductName}。每个子构建前会自动SwitchActiveBuildTarget切换到对应平台确保正确的着色器变体、资源导入设置与脚本宏构建完成后通过EditorApplication.update回调推进下一个。调度与完成监视由 BuildRunner.ScheduleNextBatchBuild 负责内置 2 小时超时保护防止子构建卡死造成孤儿回调。批量作业立即返回PendingResponse轮询间隔 10 秒携带job_id与total数量状态查询返回completed、total、current_build与每个子构建的详细状态BatchJob.ToStatusResponse。批量中任一子构建失败批量整体标记为失败。cancel取消构建HandleCancel 的语义需要特别注意批量作业可以取消——标记为cancelled当前正在构建的子任务继续完成但后续子任务全部标记为skipped不再启动。单个构建无法取消进行中的构建因为BuildPipeline.BuildPlayer是同步阻塞调用取消会返回明确错误说明原因。返回结构与异步协作模型所有 action 的返回都遵循 Unity MCP 的统一响应封装。构建类动作大量使用两类响应PendingResponse表示任务已受理、正在异步执行携带pollIntervalSeconds单构建 5 秒、批量 10 秒由客户端中间件自动调用注册的PollAction status继续轮询直至收到非 Pending 响应。SuccessResponse/ErrorResponse最终结果或错误错误响应附带堆栈信息便于排查。作业存储由 BuildJobStore 维护内存字典最多保留 50 个作业并自动清理已终结的作业与空批量。构建成功后会在 Unity Console 打印包含体积与耗时的日志失败则打印LogError。源码中的工程细节构建前的场景自动保存BuildRunner.SaveBeforeBuild 会先AssetDatabase.SaveAssets()再逐个保存脏场景避免BuildPipeline弹出模态保存对话框阻塞自动化从未保存过的新场景空路径会被跳过并告警防止触发模态文件对话框。subtarget 的平台陷阱BuildRunner.CreateBuildOptions 只在 Standalone 平台写入 subtarget因为移动平台上传 0 值会触发 Unity 6000 的已知 bugIN-102413强制 PVRTC 纹理格式忽略 Player Settings。环境变量友好工具本体不依赖特定 CI 环境但结合 Unity MCP 的-batchmode命令行与McpCiBoot.cs可组成无头构建流水线。Python 侧参数归一化coerce_bool将true/false转为布尔parse_json_payload解析 JSON 字符串逗号分隔场景也会被展开为数组manage_build.py因此字符串与 JSON 两种写法均可用。测试与验证Python 侧测试 Server/tests/test_manage_build.py 覆盖 8 个 action 的校验与参数转发未知 action 报错且不转发、None 参数被省略、options/scenes 的 JSON 解析、批量作业参数组合等可作为集成时的行为契约参考。Unity 侧的行为则由 ManageBuild.cs 与Build子目录下的实现直接承载。典型用法与注意事项AI 驱动打包让 LLM 先platform确认/切换平台再settings校准product_name、bundle_id、scripting_backend、defines随后build并持续status轮询直到拿到结果。全平台批量batch传入targets: [windows64, linux64, osx, android, webgl]配合output_dir统一产物目录注意目标平台必须已通过 Unity Hub 安装构建模块否则前置校验直接失败。Unity 6 Build Profile 流程profiles列出/激活 Profile →build传入profile路径实现配置即代码的构建。局限单个进行中的构建不可取消visionos依赖编辑器安装的 Unity 版本与模块profile相关能力在 Unity 6 以下不可用构建作业保存在内存中Editor 域重载后历史记录会清空构建本身同步阻塞域重载不会在构建期间发生故不影响进行中的任务。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考