项目地址 github.com/3038665474qq 提取pack 和使用教程、
package.json 里写着 "unity": "6000.0",工程是 2022.3.60f1c1。这两个数字碰在一起,Package Manager 只会告诉你:这个包需要更高版本的编辑器。
大多数时候,事情到这儿就结束了。想用新工具,那就升引擎。听起来很合理,直到你去看那个工程里有什么:URP 14、一批依赖旧 API 的着色器和编辑器扩展、一套和编辑器版本绑在一起的构建脚本,还有团队里每个人机器上各不相同的本地配置。为了一个命令行接口去动这些,账算不过来。
所以这次做的是另一件事:把 Pipeline 1.0.0 回迁到 2022.3,让它在这个版本上被 CLI 调起来。最低版本降到 2022.3,上游的元数据、许可证、依赖原样保留。原包一个字节没动,留在 C:\Tools 当对照;工程里装的是嵌在 Packages/com.unity.pipeline 的 fork,packages-lock.json 指向 file:com.unity.pipeline,不需要在 manifest 里再加一条依赖。
我一开始以为改个最低版本号就完事。事实证明,那只是把门推开了一条缝。
一、改版本号只解决了"让不让装"
真正拦路的是代码。包是按 Unity 6 的 API 写的,直接丢进 2022,会红一片。红的地方不算多,但每一处都得想清楚:是绕过去,还是承认这里没有。
物理材质是第一处。Unity 6 把 [PhysicMaterial](https://zhida.zhihu.com/search?content_id=287825268&content_type=Article&match_order=1&q=PhysicMaterial&zhida_source=entity) 改名成了 PhysicsMaterial,2022 只认旧名字。fork 里两种拼写都接受,落到 2022 上就用 PhysicMaterial。这种改名最烦的地方不是改不动,是它会把"类型不存在"伪装成"逻辑写错了"。
渲染队列是第二处,也是这轮里少数需要小心语义的地方。Unity 6 有 [Material.rawRenderQueue](https://zhida.zhihu.com/search?content_id=287825268&content_type=Article&match_order=1&q=Material.rawRenderQueue&zhida_source=entity),2022 没有。回退到 m_CustomRenderQueue 这个序列化属性,读写本身不难,难的是 -1。-1 不是"队列排在 -1",是"继承 Shader 的队列"。如果回退实现把它当成 0,材质会从"跟随 Shader"变成"排在 Geometry 最前面",画面立刻不对,而且不会报错。
第三处是 Console 计数。Unity 6 的 ConsoleWindowUtility 在 2022 不存在,fork 用反射去读 LogEntries.GetCountsByType。
第四处是 Analytics。Unity 6 的发送 API 在 2022 没有。数据结构、本地诊断记录都保留,就是不发送。
第五处不在 API 上,在依赖上。核心运行时程序集原本硬引用 [Unity.InputSystem](https://zhida.zhihu.com/search?content_id=287825268&content_type=Article&match_order=1&q=Unity.InputSystem&zhida_source=entity),项目没装这个包就编不过。现在键鼠注入挪进了独立的 Unity.Pipeline.InputSystem 程序集,只有装了包、并且启用 ENABLE_INPUT_SYSTEM 时才编译。核心包不再欠这一笔。
还有一处很不起眼但必须先修:包里带的 Roslyn、Metadata 这些 DLL,PluginImporter 元数据用的是 Unity 6 的新数组序列化格式。2022 读不懂。读不懂的后果不是弹个报错,是 DLL 根本不导入,然后所有引用它的代码一起报"找不到类型"------看起来像代码坏了,其实是元数据格式不对。改成 version 2 的旧格式之后两边都能读,DLL 字节和 GUID 都没动。
有些东西没法回退,只能关掉。Build Profiles、Scene Preview、Unity 6 的多人角色和 Play Mode Scenario,这些在 2022 上没有对应的实现,于是被版本宏排除在外。它们的命令不会编译失败,调用时返回一句明确的版本要求。

改完这些,包能编译了。但"能编译"只是入场券。
二、两个不好做的决定
截图:PNG 是真的,图是假的
验证视觉结果最直接的办法是截图,fork 也提供了 capture scene_view。第一次在 2022 + URP 14 上跑摄像机来源的截图时,命令成功,文件生成了,打开看是一张正常的画面。
我差点就信了。后来去读 Console,才发现渲染过程在 Render2DLightingPass 里抛了空引用。异常发生在 pass 中间,之前已经画好的内容还在,于是 PNG 里是一张"看起来没问题"的半成品。这种结果比失败难查得多:退出码是 0,文件存在,图也不是黑的,人眼要盯很久才可能发现少了一层。
最后的处理是让它失败。2022 + SRP 下,Scene View 摄像机来源直接拒绝,返回原因;要截图就走 source=screen,抓已经渲染好的屏幕内容。这条路在本机拿到的是 1173×487 的 PNG。
一个工具最危险的状态不是"不能用",是"用起来像能用"。
Console:反射失败时,不要发布零
Console 计数走反射,而反射是会坏的:API 改名、签名变化、编辑器内部调整,任何一样都能让 GetCountsByType 找不到目标。这时候有两种做法:返回 0,或者返回"不知道"。
返回 0 很省事,下游全都开心------0 个错误,编译干净。但如果真实情况是"编译其实是坏的,只是读不到",这个 0 会一路传下去,变成测试的基线、构建的前置条件,甚至变成给人看的日报。
fork 选了后者:反射失败就不发布快照,状态是未知。
这条规矩后来用在了整条链上。不支持的能力,返回的是版本要求和原因,而不是一个看起来正常的结果;它们都不"假装成功",也都不"静默失败"。
三、验证的顺序,比验证本身重要
这类改动最容易出的问题是:它能编译、能连上、能执行,但你不确定它执行的是不是你以为的那件事。所以顺序是:先编译,再连通,最后才碰功能。

有一项最容易被跳过:Runtime 核心在非 UNITY_EDITOR、加了 ENABLE_RUNTIME_PIPELINE_DEV 的 Player 条件下又编了一遍。编辑器里编译通过,不代表 Player 里能过------这两套符号下,#if UNITY_EDITOR 里面和外面的代码根本不是一个集合。包里的运行时代码在 Player 下走的是另一套分支,不编这一遍,等于没验证。
然后是四个数:status 返回 ready、端口 7800、版本 2022.3.60f1c1;script eval "1 + 1" 返回 2;recompile_status 返回 completed、failed=false、errors=[];console status 返回 compilationFailed=false、consoleErrors=0。
1 + 1 = 2 看起来像个玩笑。它同时证明了五件事:CLI 找到了编辑器、端口通、协议对、脚本编译能跑、编辑器主线程没卡死。这五件事里坏任何一件,后面看到的每个"成功"都要打问号。
真正干活的是构建。dry-run 先过一遍场景列表,确认选中的场景确实是工程里有的那些;正式构建是 Windows64 Development,第一次失败在 Burst 1.8.27 创建临时链接响应文件时------访问被拒。没有改系统环境变量,只对当前 Editor 进程把 TEMP/TMP 指到工程内一个可写目录,重试,成功,212098 毫秒,totalErrors=0。
这个数字值得留着:三分半。它不算快。变化在于,构建这件事现在可以被一条命令触发、被一份报告验收。
最后是测试。test run 能执行,但没有选中任何 Pipeline 的测试用例------包里没有独立的 com.unity.pipeline.tests 程序集。所以这次不能写"测试通过",只能写"测试命令可用,但没有可跑的用例"。这两个说法差别很大,尤其当你打算把它接进 CI 的时候。

四、CLI 到底值在哪
如果把 CLI 理解成"用命令行代替点按钮",它的价值有限------点按钮也不慢。它真正改变的是另一件事:编辑器从一个窗口,变成一个可以被问、可以等、可以验收的进程。

改一次代码,从"重启一遍"变成"问一句"
unity run -- -executeMethod Builder.Build 这条路的成本不在方法本身,在编辑器生命周期。每跑一次,启动、导入资源、编译脚本、执行、退出,全都要重来。改一个字段,付一遍全款。
script run 是另一条路:编辑器一直开着,脚本写到工程里的 .cs 文件(放在 Assets/ 外面,避免触发资源导入),指定入口跑。它做的是内存编译,量级是秒。改一版,跑一版,不用重启。
这次要验证三件事------Console 反射能不能读到计数、材质的继承队列和显式队列读出来对不对、PhysicMaterial 能不能建。写成三个入口,跑完看返回值。如果放批处理里,这三件事要开三次编辑器;现在是一次会话里连着跑完。
再小的事也一样。建一个临时 GameObject、挂上组件、读一次场景打开状态、再删掉------在编辑器里点几下就完了,在批处理里却要开一次编辑器。现在一条 script eval 就够。
附带的好处是,这些验证脚本留在工程里,可以进版本库。下次换机器、换编辑器版本,重跑一遍就知道有没有退化。临时代码跑完就没了,这种脚本跑完还在。
编译结果要能读,不能靠猜
改完 C# 之后最常见的动作是切回编辑器看 Console。这件事在人身上只要几秒,在自动化里就是个死结:你没法"看一眼"。
script recompile 触发的是一次域重载,script recompile_status 给的是结果:completed、failed=false、errors=[]。有了这个,编译就能当门禁用------编译没过,后面的测试和构建根本不用开始。
还有个前提。编辑器不是前台窗口的时候,Unity 会主动限速,重编译和测试可能就挂在那儿不动。所以动手之前先让它一直 tick(沿用上面的 $project):
bash
& $cli command editor set_auto_tick --enable true --project-path $project
这次验证完,这一项是关掉的。它是给无人值守的会话用的开关,不是常开设置。
这里还踩到一个细节:Console 历史里留着之前的错误,包括 URP 截图那次异常和 Burst 首次失败。如果只看"Console 里有没有红字",会得出"现在编译是坏的"这个错误结论。正确的读法是读状态,不是读历史。工具得能区分"当前状态"和"曾经发生过"。
截图和构建,都算验收
capture 这组命令的意义不是"能截图",是"截图可以当证据"。Console 窗口截图用来确认日志界面上的状态,Scene 截图(source=screen)用来确认画面。前面那个"PNG 是真的、图是假的",就是靠它暴露的:如果只看命令返回值,这次兼容会带着一条错误的截图路径交付出去。
构建那一侧,dry-run 和构建报告解决的是同一类问题:在花三分半之前,先知道会构建哪些场景;构建完,知道错了几个、错在哪。
一个可以照着跑的序列大致是这样:
bash
$env:ALLUSERSPROFILE = $env:ProgramData
$cli = "C:\Users\30386\AppData\Local\Unity\bin\unity.exe"
$project = "C:\Users\30386\Desktop\AIDemo\system-cultivation-legend\SystemCultivationLegend"
& $cli status --until-ready --project-path $project
& $cli command console status --project-path $project
& $cli command script eval "1 + 1" --project-path $project
& $cli command script recompile --project-path $project
& $cli command script recompile_status --project-path $project
& $cli command capture scene_view --source screen --output-path Temp/PipelineCompatibility/scene.png --project-path $project
(把 ALLUSERSPROFILE 那行放在最前面不是仪式,缺了它 2022 的 Package Manager 会抛一个和包毫无关系的错,后面会讲。)
边界也要能读
只报告成功的工具没法用。这次兼容里,所有不支持的能力都给了明确出口:Build Profile 命令返回 Unity 6 的版本要求,Input System 未启用时返回 unavailable 和原因,SRP 摄像机截图返回拒绝理由。
对人是这样,对 agent 更是这样。Agent 不会"感觉不对劲",它只会读返回值。返回值如果是 0、是空数组、是一张看起来正常的 PNG,它就会继续往下走,并且把错误当成基线。这也是为什么"反射失败不发布零"这条规矩,比它看起来重要得多。
五、这次兼容换来了什么
说具体一点。
最直接的一条,是在产项目不用为了工具升级引擎。2022 是在产项目最多的那条 LTS 之一,很多工程压在它上面,升级是季度级的事,不是下午级的事。现在这些工程也能被 CLI 连上、被脚本驱动、被截图验收,前提是不动引擎版本。
另一头是升级路径。Unity 6 的代码路径都留在版本宏里,2022 只是多了一条岔路。将来真升级,不需要重新找一遍分叉点------分叉点已经被标出来了。
更实际的变化是失败变得可读。出问题的时候,你知道是"没这个能力",还是"这个能力坏了"。这两种情况的处理方式完全不同:前者改调用,后者查代码。没有这个区分的时候,人只能靠猜,而猜错的成本通常比多写几行判断高。
依赖上也松了一扣。Input System 从"必须有"变成"有就用",项目不装这个包也能编译。对一个要装进各种工程的工具来说,这减少了一整类"装不上就编不过"的事故。
最后是回滚。fork 是嵌在工程里的一个目录,原包原封不动留在 C:\Tools。要退回原状,删目录、改回 lock 文件就行,不用动版本库历史。
六、代价,和还没验证的部分
分叉是要养的。上游每次发版,都要重新过一遍差异:哪些补丁被上游吸收了,哪些 API 又变了,2022 这条路径有没有被新代码绕过去。这不是一次性工作。
还有几件事这次没有验证,得写清楚:
- Unity 6 的代码路径保留着,但本机没有 Unity 6 编辑器,没编译过。它的正确性是"按原样保留"推出来的,不是跑出来的。
- 项目里没装 Input System,键鼠注入这条路径没有实测。分支在,实测没有。
- 项目没启用 Runtime Pipeline,所以 Player 侧连接没验证。构建成功不等于"Player 能被 CLI 连上"。
- 包里没有测试程序集,不能声称测试套件通过。
环境上还有三个坑,跟兼容本身无关,但会让兼容看起来像坏了。
启动 Unity 前,shell 里得有 ALLUSERSPROFILE。缺了它,2022 的 Package Manager 会抛 The "path" argument must be of type string. Received undefined------一个和包毫无关系的错误,但足够让你以为包坏了。在当前进程里设 $env:ALLUSERSPROFILE = $env:ProgramData 就行,不用去改系统变量。
Burst 那次失败也是环境问题:临时目录不可写。改 TEMP/TMP 是进程级的,Editor 退出就恢复。这种修法要写进记录,否则下次换台机器又要重新猜一遍。
还有 Safe Mode。工程里如果有编译错误,编辑器会以 Safe Mode 启动,Pipeline 包不会加载,CLI 根本连不上。这时候 status 不是在说"没连上",它是在说"有一堆编译错误"。先修错误,别在那儿重试连接。
七、判断
这次兼容最值钱的一句话不是"2022 也能跑",是"2022 也能说清楚哪里不能跑"。
一个工具在旧版本上能干什么、边界在哪、失败长什么样------这三件事说清楚了,它才算真的可用。反过来说,一个在旧版本上"看起来都能用"的工具往往最危险:它会在某个不常走的路径上给你一个 0,然后你拿着这个 0 去做决定。
CLI 这边的价值也类似。命令数量不是重点,重点是编辑器变成了一个有状态的进程:能问它状态,能等它编译,能读它的错误,能截它的图,能让它构建,并且每一步都有返回值可以判断。这些东西加起来,才叫"能被程序驱动"。
引擎版本不该是自动化的门槛,但它也不该被伪装成没有门槛。这次做的事,是把门槛标出来,然后在门槛里面,把能走的路都走通。
记录
- 环境:Unity 2022.3.60f1c1,URP 14,CLI 1.0.0
- 包:
com.unity.pipeline1.0.0,revisionce87150,嵌入Packages/com.unity.pipeline - 原包:
C:\Tools\com.unity.pipeline-1.0.0\package(未修改) - 验证产物:工程内
Temp/PipelineCompatibility - 详细记录:包内
Documentation~/unity-2022-compatibility.md