1. 為什么自定義包值得研究很多 Unity 開(kāi)發(fā)者第一次接觸 Unity Custom Package 自定義包這個(gè)概念時(shí)容易誤解以為這只是把代碼換個(gè)地方放而已。其實(shí)真不是這樣自從 Unity 引入 Package Manager 之后自定義包就不只是“文件夾里多一個(gè) package.json”那么簡(jiǎn)單它直接改變了我組織項(xiàng)目的方式。我長(zhǎng)期同時(shí)維護(hù)好幾個(gè) Unity 項(xiàng)目有面向移動(dòng)端的有做編輯器工具的也有專(zhuān)門(mén)做原型驗(yàn)證的小項(xiàng)目。過(guò)去我習(xí)慣把公共代碼復(fù)制進(jìn)每個(gè)項(xiàng)目比如對(duì)象池、存檔模塊、UI 框架、網(wǎng)絡(luò)連接管理。一開(kāi)始確實(shí)順手但半年之后問(wèn)題全來(lái)了項(xiàng)目 A 的對(duì)象池是 v1項(xiàng)目 B 里被同事改成了 v2項(xiàng)目 C 又被人回退到舊邏輯因?yàn)樾逻壿嬘悬c(diǎn)問(wèn)題。每當(dāng)我需要給公共模塊加功能或修 Bug就要在多個(gè)項(xiàng)目里逐一搜索、替換、測(cè)試開(kāi)銷(xiāo)極其巨大。這還沒(méi)算上那些藏在 Assets 里的 prefab、shader、材質(zhì)球復(fù)制粘貼根本無(wú)法自動(dòng)追蹤依賴(lài)關(guān)系。自定義包正是解決這個(gè)痛點(diǎn)的標(biāo)準(zhǔn)化方案。它把代碼、資源、配置、程序和文檔統(tǒng)一到一個(gè)帶有版本信息的包里由 Unity 自帶的 UPM 統(tǒng)一管理。你可以把包放到本地磁盤(pán)某個(gè)目錄也可以推到 Git 倉(cāng)庫(kù)然后在任意項(xiàng)目的 manifest.json 里添加一行依賴(lài)約定整個(gè)包就自動(dòng)被安裝并參與編譯。更新的流程也變得清晰改包發(fā)版本項(xiàng)目方自己決定什么時(shí)候升級(jí)依賴(lài)。這個(gè)方案非常適合這幾類(lèi)人經(jīng)常重復(fù)造輪子的獨(dú)立游戲開(kāi)發(fā)者、想把公共模塊統(tǒng)一管理的開(kāi)發(fā)團(tuán)隊(duì)、需要把編輯器小工具分發(fā)給同事的技術(shù)美術(shù)或工具開(kāi)發(fā)者。如果你只是在一個(gè)小游戲項(xiàng)目里寫(xiě)幾段一次性腳本那自定義包確實(shí)不是剛需但只要你開(kāi)始跨項(xiàng)目沉淀代碼它是遲早要掌握的基礎(chǔ)知識(shí)。1.1 復(fù)制粘貼維護(hù)公共代碼的真實(shí)代價(jià)我先說(shuō)說(shuō)痛點(diǎn)因?yàn)橹挥欣斫饬送茨悴艜?huì)真的建包。復(fù)制粘貼公共代碼聽(tīng)上去省事實(shí)際維護(hù)成本遠(yuǎn)比你想象的高。首先是對(duì)版本失去感知。你今天把角色控制器代碼復(fù)制到項(xiàng)目 B明天又復(fù)制一次覆蓋卻根本不知道兩份代碼是否完全一致。假如其中有一段在項(xiàng)目 B 已經(jīng)適配過(guò)特殊需求下次再?gòu)?fù)制就會(huì)直接把項(xiàng)目 A 的版本覆蓋進(jìn)去Bug 就這樣產(chǎn)生了。團(tuán)隊(duì)里只要有兩個(gè)以上的人參與這個(gè)風(fēng)險(xiǎn)會(huì)成倍放大。一個(gè)人認(rèn)為“我復(fù)制的是最新版”另一個(gè)人認(rèn)為“我這邊改得更好”最后代碼在多個(gè)項(xiàng)目里各自演化了誰(shuí)也沒(méi)法保證它們一致。其次是資源依賴(lài)被撕開(kāi)。Unity 的開(kāi)發(fā)特點(diǎn)是代碼和資源深度綁定公共模塊往往不只是腳本還有對(duì)應(yīng)的 shader、材質(zhì)、ScriptableObject 配置、動(dòng)畫(huà)控制器。你用復(fù)制腳本的方式搬過(guò)來(lái)腳本能跑起來(lái)材質(zhì)引用卻斷裂了外表立刻出現(xiàn)紫紅色警告。于是你又得手動(dòng)把公用資源重復(fù)導(dǎo)一份重復(fù)導(dǎo)入又帶來(lái)了 GUID 沖突和引用錯(cuò)亂。我團(tuán)隊(duì)里就出現(xiàn)過(guò)幾乎每個(gè)項(xiàng)目都有兩份同名材質(zhì)球但參數(shù)不同的問(wèn)題找 Bug 找得頭大。再者是沒(méi)有升級(jí)機(jī)制。你發(fā)現(xiàn)對(duì)象池有內(nèi)存泄漏問(wèn)題修好了然后你挨個(gè)項(xiàng)目手動(dòng)復(fù)制一遍修改。你會(huì)發(fā)現(xiàn)切換分支、重新打開(kāi)項(xiàng)目、運(yùn)行測(cè)試、提交代碼這一套流程要重復(fù) N 次。如果每次都有細(xì)微差異你連測(cè)試都懶得做全最終得到一個(gè)“雖然修了 Bug 但在某些項(xiàng)目里可能沒(méi)修干凈”的狀態(tài)。時(shí)間久了公共代碼就是一團(tuán)爛賬。1.2 自定義包到底改變了什么把同樣的模塊放進(jìn)一個(gè)自定義包之后整體邏輯完全不一樣了。包本身有獨(dú)立的版本號(hào)。比如你的存檔系統(tǒng)是 1.2.0它有明確的 release note有對(duì)應(yīng)的 Git tag。項(xiàng)目 A 引用 1.2.0項(xiàng)目 B 暫時(shí)停留在 1.1.4這個(gè)狀態(tài)是可以被 manifest.json 明確記錄下來(lái)的。誰(shuí)也不需要“猜”哪個(gè)項(xiàng)目在用哪版代碼打開(kāi)文件就能看到。包的依賴(lài)關(guān)系也是顯式的。如果這個(gè)包依賴(lài)另一個(gè)包比如對(duì)象池包依賴(lài)一個(gè)數(shù)學(xué)工具包你可以在 package.json 里聲明UPM 會(huì)自動(dòng)把依賴(lài)包一并解析安裝。這比你在項(xiàng)目里手動(dòng)放兩個(gè)文件夾要可靠得多因?yàn)?Unity 會(huì)檢查版本兼容性沖突時(shí)會(huì)直接報(bào)錯(cuò)而不是靜默覆蓋。最重要的變化是邊界。包內(nèi)部可以定義自己的 asmdefAssembly Definition它只暴露你想暴露的內(nèi)容其他內(nèi)部實(shí)現(xiàn)全部私有化。這其實(shí)是在代碼層面畫(huà)了一條清晰的線模塊外部只能通過(guò)約定好的公開(kāi) API 來(lái)使用模塊不能隨手改動(dòng)內(nèi)部結(jié)構(gòu)。在多人團(tuán)隊(duì)里這條邊界極其重要它能防止公共代碼被項(xiàng)目里的臨時(shí)需求越改越亂。我個(gè)人的感受是自定義包把“這段代碼是這個(gè)項(xiàng)目的一部分”徹底變成了“這個(gè)項(xiàng)目的一部分取決于這段代碼”。依賴(lài)關(guān)系被顯式記錄、版本被管理、邊界被定義后面所有協(xié)作和迭代都建立在這個(gè)基礎(chǔ)上心里踏實(shí)很多。2. 制作一個(gè)自定義包的最小可運(yùn)行流程理解概念之后我們直接動(dòng)手。對(duì)一個(gè) Unity 開(kāi)發(fā)者來(lái)說(shuō)第一次建自定義包不需要把結(jié)構(gòu)想得非常復(fù)雜。你只需要準(zhǔn)備一個(gè)文件夾、一個(gè) package.json、幾個(gè)腳本然后在項(xiàng)目里把這個(gè)包注冊(cè)上即可。走通這條路再慢慢增加資源和工具。2.1 package.json 的字段說(shuō)明和一份最小樣例自定義包的核心注冊(cè)文件是 package.json它放在包根目錄下。Unity 從 2019.1 開(kāi)始全面使用 Package Manager這個(gè)文件就是包的身份證。下面是一份最小可用的 package.json{ name: com.example.savesystem, version: 1.0.0, displayName: Example Save System, description: 一個(gè)輕量的存檔管理模塊支持 Json 與 PlayerPrefs 兩種后端。, unity: 2021.3, dependencies: { com.unity.textmeshpro: 3.0.6 } }我逐個(gè)說(shuō)說(shuō)這些字段的實(shí)際含義。name包的全局唯一標(biāo)識(shí)格式必須像反向域名比如 com.company.module。這個(gè)字段一旦確定就不要輕易改因?yàn)轫?xiàng)目 manifest.json 里記錄的就是這個(gè)值改名等于換包所有引用方都要更新。version語(yǔ)義化版本號(hào)一般遵循主版本.次版本.修訂號(hào)的規(guī)則。UPM 在解決依賴(lài)時(shí)會(huì)參考這個(gè)版本號(hào)所以不要亂填。displayName顯示在 Package Manager 窗口里的包名可以寫(xiě)成用戶(hù)友好的名字。description包的說(shuō)明文字會(huì)展示在包詳情面板。寫(xiě)清楚它負(fù)責(zé)什么功能依賴(lài)哪些外圍條件對(duì)團(tuán)隊(duì)其他成員幫助很大。unity聲明這個(gè)包支持的 Unity 版本。實(shí)測(cè)下來(lái)如果包使用了某些僅高版本支持的 API這里就寫(xiě)對(duì)應(yīng)版本否則不寫(xiě)也行。dependencies包的依賴(lài)列表。UPM 會(huì)自動(dòng)解析比一個(gè)人手動(dòng)安裝依賴(lài)要可靠得多。要注意的是這里填的依賴(lài)版本是一個(gè)區(qū)間表達(dá)式比如 1.0.0 表示精確版本1.2.3 表示至少這個(gè)版本實(shí)際解析規(guī)則以 Unity 在 UPM 中的取值約定為準(zhǔn)。除了這些包可能還會(huì)用到 author作者信息、keywords搜索關(guān)鍵詞、hideInEditor是否在包列表里隱藏等字段。新手階段知道這些就夠用了后面按需擴(kuò)展。2.2 把腳本按 Runtime 和 Editor 分開(kāi)放包建成之后腳本不是隨便丟進(jìn)文件夾就完事。由于包會(huì)被 UPM 納入項(xiàng)目的編譯流程你最好從一開(kāi)始就把代碼按照運(yùn)行時(shí)機(jī)拆分清楚否則日后會(huì)有很多意想不到的編譯問(wèn)題和包體大小問(wèn)題。常規(guī)做法是在包根目錄下建 Runtime 和 Editor 兩個(gè)文件夾。Runtime 里放最終運(yùn)行時(shí)執(zhí)行的代碼比如存檔管理器、對(duì)象池、網(wǎng)絡(luò)客戶(hù)端、視頻播放組件。Editor 里放只在編輯器環(huán)境下運(yùn)行的代碼比如編輯器窗口、自定義 Inspector、菜單命令、資源導(dǎo)入輔助工具。Editor 文件夾里的代碼如果被放進(jìn)了 RuntimeUnity 不會(huì)主動(dòng)報(bào)錯(cuò)但打包時(shí)這些編輯器 API 會(huì)被帶進(jìn)最終程序變大嚴(yán)重時(shí)還會(huì)因?yàn)?UnityEngine.Range 等異常直接編譯失敗。在 Unity 社區(qū)里一些老教程喜歡把包代碼直接用 Assets/ 作為目錄名這是歷史遺留習(xí)慣。新版 UPM 更推薦用 Runtime/Editor 這種明確命名的目錄因?yàn)樗c asmdef 的默認(rèn)規(guī)則完全一致放在 Runtime 下的程序集默認(rèn)只參與運(yùn)行時(shí)編譯Editor 下的程序集默認(rèn)標(biāo)記為 EditorOnly彼此隔離互不干擾。你不需要額外手寫(xiě)任何判斷只要目錄對(duì)了后面的構(gòu)建行為基本都是合理默認(rèn)。2.2.1 私有程序集與 asmdef 設(shè)計(jì)如果你希望包內(nèi)部結(jié)構(gòu)再?lài)?yán)謹(jǐn)一點(diǎn)就需要在 Runtime 和 Editor 下分別放置 asmdef 文件。asmdef 是 Unity 的程序集定義文件它把代碼編譯成一個(gè)獨(dú)立的程序集從而控制引用關(guān)系。最常見(jiàn)的做法是建兩個(gè) asmdef一個(gè)叫 com.example.savesystem.Runtime.asmdef一個(gè)叫 com.example.savesystem.Editor.asmdef。Runtime 程序集只聲明對(duì) UnityEngine 核心模塊和它實(shí)際依賴(lài)的第三方包的引用Editor 程序集則要在 references 里額外引用 Runtime 程序集。這樣設(shè)計(jì)的好處是你想讓包的公開(kāi) API 區(qū)域和內(nèi)部實(shí)現(xiàn)區(qū)域徹底隔離外部代碼能看到的就是你在 Runtime 程序集里標(biāo)記為 public 的那部分。內(nèi)部輔助類(lèi)即使寫(xiě)成 public但程序集名不同外部引用通常不會(huì)亂進(jìn)。asmdef 文件本身是 JSON內(nèi)容不長(zhǎng)。如果你不想完全手寫(xiě)可以直接在 Unity 里右鍵文件夾創(chuàng)建 Assembly Definition然后通過(guò) Inspector 配置引用。不過(guò)我還是推薦了解一下手寫(xiě)結(jié)構(gòu)下面的例子可以作為參考{ name: ExampleSaveSystem.Runtime, rootNamespace: Example.Saves, references: [], includePlatforms: [], excludePlatforms: [], allowUnsafeCode: false, overrideReferences: false, precompiledReferences: [], autoReferenced: true, defineConstraints: [], versionDefines: [], noEngineReferences: false }其中的 rootNamespace 很有用它會(huì)讓新生成的代碼文件自動(dòng)帶命名空間前綴省去很多手動(dòng)添加命名空間的工作。2.3 把本地的包注冊(cè)進(jìn) Unity 項(xiàng)目包做出來(lái)后第一次注冊(cè)到項(xiàng)目里的方式有三種我逐個(gè)說(shuō)一下適用場(chǎng)景。第一種是通過(guò) Package Manager 窗口添加本地包。打開(kāi) Window Package Manager點(diǎn)擊左上角加號(hào)選擇 Add package from disk然后定位到包的根目錄選中 package.json 即可。這種方式適合你正在桌面某個(gè)目錄里開(kāi)發(fā)包要多項(xiàng)目聯(lián)調(diào)的情況。它會(huì)把包加入 manifest.json 的 dependencies記錄為 file: 協(xié)議路徑。第二種是直接在 manifest.json 里寫(xiě)入本地路徑。例如{ dependencies: { com.example.savesystem: file:../../Packages/ExampleSaveSystem } }這種方式適合用文本編輯器手動(dòng)管理依賴(lài)或者想在腳本里批量添加依賴(lài)的場(chǎng)景。路徑可以是絕對(duì)路徑但我建議用相對(duì)路徑這樣整個(gè)項(xiàng)目目錄被挪動(dòng)時(shí)依賴(lài)仍能正常工作。第三種是作為一個(gè)鏈接方式放在項(xiàng)目的 Packages 文件夾下直接作為 embedded package。在 Unity 中工程根目錄下默認(rèn)有 Packages/manifest.json而 Packages 文件夾本身也可以直接放自定義包的目錄。如果包就躺在那里Unity 會(huì)自動(dòng)把它視為 embedded這個(gè)包的狀態(tài)會(huì)被固定住不會(huì)因?yàn)?manifest.json 的解析結(jié)果而改變。對(duì)于本地開(kāi)發(fā)階段我個(gè)人最喜歡 Add package from disk 的方式它會(huì)直接在項(xiàng)目里生成顯式的 file: 依賴(lài)包更新時(shí)只需要替換目錄內(nèi)容并點(diǎn)擊刷新就能看到最新代碼。切記不要把 file: 路徑依賴(lài)提交到需要多人協(xié)作的倉(cāng)庫(kù)除非你對(duì)路徑的穩(wěn)定性非常有把握否則它很容易在不同開(kāi)發(fā)機(jī)上失效。3. 從實(shí)用角度設(shè)計(jì)包內(nèi)模塊包能跑起來(lái)之后關(guān)鍵的思維轉(zhuǎn)變是你現(xiàn)在不是在給某個(gè)項(xiàng)目寫(xiě)代碼而是在設(shè)計(jì)一個(gè)可以被多個(gè)項(xiàng)目復(fù)用的獨(dú)立模塊。這要求你從命名空間、公共 API、資源組織、示例代碼等維度重新思考包的結(jié)構(gòu)。3.1 一個(gè)完整的存檔模塊包案例分析我拿一個(gè)存檔模塊為例來(lái)說(shuō)因?yàn)樗鼛缀趺總€(gè)項(xiàng)目都能用到結(jié)構(gòu)也足夠有代表性。包的目錄結(jié)構(gòu)可以是ExampleSaveSystem/ ├── package.json ├── Runtime/ │ ├── ExampleSaveSystem.Runtime.asmdef │ ├── SaveManager.cs │ ├── SaveData.cs │ └── Storage/ │ ├── IDataStorage.cs │ ├── JsonStorage.cs │ └── PlayerPrefsStorage.cs ├── Editor/ │ ├── ExampleSaveSystem.Editor.asmdef │ ├── SaveConfigWindow.cs │ └── SaveDataInspector.cs ├── Samples/ │ └── BasicSave/ │ ├── ExampleSaveUsage.cs │ └── ExampleSaveUsage.unity └── Documentation/ └── README.md我們關(guān)注幾個(gè)設(shè)計(jì)細(xì)節(jié)。SaveManager.cs 里我要做一個(gè)公開(kāi)門(mén)面類(lèi)團(tuán)隊(duì)所有項(xiàng)目都只通過(guò)它來(lái)讀寫(xiě)存檔不直接接觸 Storage 接口。這相當(dāng)于把包的內(nèi)部實(shí)現(xiàn)變化與外部調(diào)用隔離。今天我用 PlayerPrefs 存明天改成 Json 文件存只要 SaveManager 的 API 不變其他項(xiàng)目一行都不用改。這種設(shè)計(jì)是模塊化開(kāi)發(fā)的精髓。至于 SaveData 這種數(shù)據(jù)類(lèi)我通常會(huì)做成可序列化的基礎(chǔ)類(lèi)。由于存檔數(shù)據(jù)在多個(gè)項(xiàng)目里差異很大我不打算在包里寫(xiě)死字段而是讓使用方繼承自己的數(shù)據(jù)模型。這要求包的公開(kāi) API 里預(yù)留泛型方法比如 Save (string key, T data) 和 Load (string key)。在包內(nèi)實(shí)現(xiàn)時(shí)注意反射和序列化的性能避免在頻繁存檔的幀里做過(guò)多額外處理。這個(gè)包還引出一個(gè)重要理念包不應(yīng)該知道業(yè)務(wù)項(xiàng)目里的細(xì)節(jié)。如果一個(gè)包依賴(lài)了某個(gè)項(xiàng)目自定義的 MonoBehaviour這個(gè)包基本上就不可能被復(fù)用到其他項(xiàng)目了。因此設(shè)計(jì)包時(shí)你要反復(fù)問(wèn)自己這一層邏輯是通用能力還是業(yè)務(wù)邏輯通用能力放包里業(yè)務(wù)邏輯留在項(xiàng)目里這是包設(shè)計(jì)最核心的分界。3.2 把 Prefab 和 Shader 資源也放進(jìn)包里包不只是裝代碼它也完全可以裝 Prefab、材質(zhì)、Shader、ScriptableObject、紋理等資源。這對(duì)做 UI 組件庫(kù)、特效庫(kù)、工具庫(kù)的人來(lái)說(shuō)尤其重要。在包內(nèi)放置資源時(shí)有一個(gè)必須注意的點(diǎn)包內(nèi)一切資源都使用 GUID 引用。也就是說(shuō)你在包的某個(gè) Prefab 里引用了一份材質(zhì)、一個(gè)腳本或另一個(gè) Prefab它們只要都從屬于同一個(gè)項(xiàng)目Unity 會(huì)自動(dòng)通過(guò) GUID 解析。只要包在項(xiàng)目里被正常安裝資源引用就不會(huì)斷。這比復(fù)制粘貼方式下經(jīng)常出現(xiàn)的“引用找不到”問(wèn)題要穩(wěn)定得多。為了測(cè)試包內(nèi)資源是否完全孤立可復(fù)用我習(xí)慣用一個(gè)小技巧把所有依賴(lài)項(xiàng)和資源放到一個(gè)臨時(shí)空項(xiàng)目里只通過(guò) manifest 安裝這個(gè)包然后打開(kāi)其中資源隨意點(diǎn)擊。如果編輯器控制臺(tái)沒(méi)有任何缺失引用的報(bào)錯(cuò)這個(gè)包就是健康可分發(fā)的。如果出現(xiàn)引用丟失多半是包內(nèi)某個(gè)資源引用了包外的對(duì)象或者 asmdef 的引用配置有遺漏。對(duì)于比較重的資源比如多個(gè) 4K 貼圖、大量光照貼圖我不建議直接塞進(jìn)包主體因?yàn)槊總€(gè)項(xiàng)目安裝這個(gè)包時(shí)都會(huì)被迫導(dǎo)入它們。更好的做法是把這些資源放到 Samples 文件夾里讓使用者按需添加。UPM 的 Samples 是包的示范資源目錄項(xiàng)目里可以通過(guò) Package Manager 窗口單獨(dú) Import 某個(gè) Sample這樣既提供了演示又不強(qiáng)制占用項(xiàng)目體積。很多知名 UI 插件包就是這么做的例如 Toony Colors Pro 的樣例場(chǎng)景。3.3 順勢(shì)聊兩個(gè)常見(jiàn)的實(shí)際擴(kuò)展場(chǎng)景外部模型導(dǎo)入和視頻流模塊如果你日常經(jīng)常處理 SolidWorks 之類(lèi)的外部 CAD 模型導(dǎo)入也會(huì)發(fā)現(xiàn)自定義包是個(gè)好載體。你可以把模型導(dǎo)入工具鏈封裝成一個(gè) Editor 包里面包含導(dǎo)入配置向?qū)А⒏袷綑z測(cè)、材質(zhì)映射規(guī)則以及常用的批處理命令。這樣當(dāng)你的團(tuán)隊(duì)從 SolidWorks 導(dǎo)出細(xì)分模型再導(dǎo)入 Unity 時(shí)走的都是同一套標(biāo)準(zhǔn)化流程生成的資源明顯更可控。相比讓每個(gè)人手動(dòng)拖入模型、再手工調(diào)參數(shù)這個(gè)包的價(jià)值就在于把經(jīng)驗(yàn)固化成了自動(dòng)化邏輯。做游戲里的視頻流或者動(dòng)態(tài)內(nèi)容展示時(shí)也同樣如此。把視頻解碼、播放、字幕同步、事件回調(diào)封裝成一個(gè) Runtime 包項(xiàng)目只需簡(jiǎn)單傳入 VideoClip 或視頻地址就能得到統(tǒng)一的播放接口。視頻解碼涉及很多平臺(tái)差異封裝成包后平臺(tái)相關(guān)代碼被隔離在包內(nèi)部的編譯分支里項(xiàng)目代碼看起來(lái)就非常干凈。用的時(shí)候你的項(xiàng)目處于移動(dòng)端還是 PC 后臺(tái)不需要感知這些差異包自己會(huì)在合適的平臺(tái)分支上做處理。我并不是建議你一味追求抽象而是想說(shuō)清楚只要一個(gè)功能有可能被多個(gè)項(xiàng)目復(fù)用就應(yīng)該考慮把它從項(xiàng)目代碼里剝離成包。這不是過(guò)度設(shè)計(jì)而是對(duì)自己未來(lái)工作量的明確減負(fù)。4. 把自定義包變成團(tuán)隊(duì)基礎(chǔ)設(shè)施當(dāng)包在自己的項(xiàng)目里穩(wěn)定運(yùn)行之后下一步就可以考慮把它發(fā)布到 Git 倉(cāng)庫(kù)讓團(tuán)隊(duì)成員按需引用。這一節(jié)講的是把本地包升級(jí)為 Git 依賴(lài)的完整做法以及這個(gè)過(guò)程中的版本管理策略。4.1 推送到 Git 倉(cāng)庫(kù)并用 URL 安裝目前 Unity 支持通過(guò) Git URL 直接把包作為依賴(lài)安裝這是團(tuán)隊(duì)協(xié)作最容易上手的發(fā)布方式。你需要先把包目錄變成一個(gè)獨(dú)立的 Git 倉(cāng)庫(kù)然后推送到遠(yuǎn)程服務(wù)器。操作步驟很簡(jiǎn)單我先說(shuō) Git 側(cè)的做法在本地創(chuàng)建一個(gè)新目錄把包的 package.json、Runtime、Editor、Samples 等全部放進(jìn)去。在包根目錄執(zhí)行 git init添加遠(yuǎn)程倉(cāng)庫(kù)地址提交初始代碼。把包推送到遠(yuǎn)程倉(cāng)庫(kù)例如 git push -u origin main。為關(guān)鍵的穩(wěn)定版本打 tag比如 git tag v1.2.0然后推送 tag。然后在項(xiàng)目側(cè)你可以通過(guò) Package Manager 窗口操作也可以直接修改 manifest.json。如果使用 Git URL 引用文檔里常見(jiàn)兩種寫(xiě)法{ dependencies: { com.example.savesystem: https://github.com/example/ExampleSaveSystem.git#v1.2.0 } }也可以加通配符版本范圍不過(guò)推薦固定 tag因?yàn)檫@樣項(xiàng)目的依賴(lài)是可復(fù)現(xiàn)的。對(duì)穩(wěn)定性要求很高的項(xiàng)目固定 tag 是不二之選如果你比較追求多項(xiàng)目同步更新也可以直接指向分支名風(fēng)險(xiǎn)自負(fù)。這里要特別說(shuō)一個(gè)坑如果你把包含 file: 路徑的 manifest.json 提交到團(tuán)隊(duì)倉(cāng)庫(kù)其他人拉下來(lái)時(shí)會(huì)發(fā)現(xiàn)包根本不存在因?yàn)槁窂街赶虻氖悄阕约簷C(jī)器的目錄。這大概是所有自定義包落地時(shí)最容易出現(xiàn)的協(xié)作事故。所以團(tuán)隊(duì)協(xié)作一定要優(yōu)先使用 Git URL 的引用方式把路徑依賴(lài)留給單機(jī)開(kāi)發(fā)或聯(lián)調(diào)階段。4.2 版本號(hào)策略與依賴(lài)沖突處理包一旦有多個(gè)項(xiàng)目引用版本就成了團(tuán)隊(duì)協(xié)作的核心語(yǔ)言。版本號(hào)不是隨便填的它的語(yǔ)義直接影響依賴(lài)解析。按語(yǔ)義化版本規(guī)則來(lái)說(shuō)修復(fù) Bug 和內(nèi)部實(shí)現(xiàn)優(yōu)化應(yīng)該升修訂號(hào)例如 1.0.0 到 1.0.1新增不破壞原有 API 的功能應(yīng)該升次版本號(hào)例如 1.0.1 到 1.1.0破壞性 API 修改必須升主版本號(hào)例如 1.1.0 到 2.0.0。為什么這么講究因?yàn)?UPM 在解析依賴(lài)時(shí)有一套自己的規(guī)則。假如項(xiàng)目已經(jīng)安裝了版本 1.1.2 的包 A而另一個(gè)包 B 要求包 A 至少 1.2.0只要 1.2.0 與 1.1.2 不是破壞性變更UPM 大概率會(huì)解析出更高版本。但如果你在主版本號(hào)做了破壞性改動(dòng)卻沒(méi)有升級(jí)主版本整個(gè)依賴(lài)樹(shù)就亂了多個(gè)包之間會(huì)出現(xiàn)莫名其妙的 API 不匹配。我自己踩過(guò)最大的坑是包 A 依賴(lài)包 B而項(xiàng)目里包 A 和包 B 是從兩個(gè)不同開(kāi)發(fā)者的倉(cāng)庫(kù)直接裝的。由于沒(méi)有統(tǒng)一版本策略最終項(xiàng)目在編譯階段出現(xiàn)了大量重名類(lèi)、重復(fù)命名空間沖突。處理辦法只能回滾依賴(lài)版本。所以從第一天起團(tuán)隊(duì)就要規(guī)定發(fā)布包版本前必須寫(xiě) changelog 并遵守語(yǔ)義化版本號(hào)否則協(xié)作越深入越難收拾。4.2.1 內(nèi)網(wǎng)私有 Git 倉(cāng)庫(kù)的補(bǔ)充建議如果你的團(tuán)隊(duì)在局域網(wǎng)內(nèi)開(kāi)發(fā)不希望把代碼推到公網(wǎng)也可以用自建的 Git 服務(wù)比如 GitLab CE 或 Gitea。Unity 的 Git URL 依賴(lài)只要是一個(gè)可以被正常 clone 的 Git 地址都行不區(qū)分是否公網(wǎng)。需要提醒的是URL 中如果包含認(rèn)證信息Unity 編輯器自身對(duì)賬號(hào)認(rèn)證的支持比較有限推薦在開(kāi)發(fā)機(jī)上提前配置好 SSH 密鑰這樣 UPM 拉取包的時(shí)候不會(huì)遇到權(quán)限卡頓。4.3 包內(nèi)容之外文檔和變更日志團(tuán)隊(duì)級(jí)的自定義包一定要配套文檔。我在包內(nèi)固定維護(hù) Documentation/ 和 CHANGELOG.md。文檔負(fù)責(zé)講清 API 用法、依賴(lài)關(guān)系和常見(jiàn)配置變更日志負(fù)責(zé)記錄每個(gè)版本的改動(dòng)點(diǎn)。這兩樣?xùn)|西平時(shí)看起來(lái)不產(chǎn)生代碼但團(tuán)隊(duì)里任何一個(gè)人接手時(shí)說(shuō)“這個(gè)包怎么用”你不需要口頭解釋只需要甩出文檔位置溝通成本能降一大截。另外一個(gè)常被忽略的點(diǎn)是包的 Sample 示例。Sample 里的代碼質(zhì)量一定要高因?yàn)樗莿e人在編輯器里按 Import 按鈕后看到的第一印象。如果 Sample 里堆滿(mǎn)了舊 API 或讓人困惑的寫(xiě)法使用者會(huì)直接對(duì)包的可靠性產(chǎn)生懷疑。5. 常見(jiàn)問(wèn)題與排查實(shí)錄自定義包并不神秘但它畢竟是加在 Unity 項(xiàng)目上的一層組織方式總會(huì)有一些容易踩的坑。這些坑大多不致命但排查起來(lái)很影響心情。下面這節(jié)我按自己實(shí)操中遇到的高頻問(wèn)題做了一份速查記錄也附上了排查思路。5.1 編譯錯(cuò)誤程序集引用不明確最常見(jiàn)的錯(cuò)誤是包里的代碼報(bào)錯(cuò)找不到類(lèi)型或方法這通常是 asmdef 的引用配置出了問(wèn)題。舉個(gè)例子你可能在 Runtime 腳本里用了 Newtonsoft.Json但包的 asmdef references 里沒(méi)有添加 Newtonsoft.Json。這時(shí)編譯會(huì)報(bào)“當(dāng)前上下文中不存在名稱(chēng) JsonConvert”即便這個(gè)包在 Unity 默認(rèn)程序集里能正常使用。為什么因?yàn)?asmdef 一旦生效包內(nèi)代碼的可見(jiàn)引用范圍就受程序集約束了它不會(huì)自動(dòng)引用項(xiàng)目里的其他程序集除非你在 asmdef 里顯式添加。排查思路很簡(jiǎn)單先打開(kāi)包的 asmdef 文件檢查 references 列表里有沒(méi)有包含需要引用的程序集名。如果是第三方 DLL還需要確認(rèn) precompiledReferences 或 UnityEngine 模塊引用是否完備。也可以先在 Unity 里點(diǎn)選報(bào)錯(cuò)的腳本看 Inspector 里那個(gè)三角形的警告它會(huì)直接告訴你這個(gè)腳本屬于哪個(gè)程序集以及有哪些引用缺失。另外要留意循環(huán)依賴(lài)。如果你的包 A 引用了包 B而包 B 又引用了包 AUPM 在編譯階段會(huì)報(bào)程序集循環(huán)引用錯(cuò)誤。解決這種問(wèn)題需要重新審視包的功能邊界盡量保證依賴(lài)方向是單向的或者把相互引用的公共部分抽離成更底層的包。5.2 包顯示狀態(tài)不對(duì)embedded、local、git 傻傻分不清Package Manager 窗口里有些包顯示 for development有些顯示 Source: Local有些顯示 Source: Git。這些狀態(tài)差異不是隨機(jī)的。for development 通常意味著包被嵌入到項(xiàng)目 Packages 目錄也就是 embeddedLocal 通常意味著來(lái)自 file: 路徑Git 則代表來(lái)自遠(yuǎn)程 Git 倉(cāng)庫(kù)。排查時(shí)最常遇到的問(wèn)題是把包從 Git 切換到了本地 file: 路徑但 Package Manager 里版本始終還是舊的。這個(gè)現(xiàn)象往往是你沒(méi)有刪除鎖文件。Unity 在項(xiàng)目的 Packages/packages-lock.json 中記錄了每個(gè)包的解析結(jié)果包括實(shí)際版本和來(lái)源地址。如果你修改了 manifest.json 里某個(gè)包的來(lái)源但沒(méi)有讓 UPM 重新解析它可能繼續(xù)使用鎖文件中的舊記錄。此時(shí)可以刪除 packages-lock.json 后重新打開(kāi)項(xiàng)目強(qiáng)制 UPM 重新解析所有依賴(lài)。不過(guò)這個(gè)操作影響全局依賴(lài)執(zhí)行前最好確認(rèn)沒(méi)有其他同事正在同時(shí)改動(dòng)依賴(lài)。5.3 資源導(dǎo)入失敗和刷新不及時(shí)的避坑記錄修改包內(nèi)腳本后有時(shí)你會(huì)發(fā)現(xiàn)項(xiàng)目里的調(diào)用方還停留在舊版 API或者新代碼編譯了半天還在報(bào)錯(cuò)。這大概率是包沒(méi)有及時(shí)刷新特別是當(dāng)包目錄不在項(xiàng)目?jī)?nèi)部時(shí)Unity 的自動(dòng)監(jiān)視機(jī)制偶爾不會(huì)立即感知外部目錄變化。我在實(shí)際工作里會(huì)形成兩個(gè)習(xí)慣一是在包目錄和項(xiàng)目目錄同時(shí)打開(kāi)編輯器窗口修改包后直接切回 Unity等右下角編譯轉(zhuǎn)圈結(jié)束再運(yùn)行二是遇到頑固不刷新時(shí)手動(dòng)執(zhí)行 Assets Refresh或按 CtrlR必要時(shí)關(guān)閉并重新打開(kāi)項(xiàng)目。千萬(wàn)別在編輯器還在編譯時(shí)強(qiáng)行改包文件會(huì)導(dǎo)致下一次 import 偶爾出現(xiàn)半寫(xiě)入的臨時(shí)狀態(tài)寧愿等穩(wěn)定了再動(dòng)。5.4 閱讀 locked file 的注意事項(xiàng)UPM 默認(rèn)的 packages-lock.json 對(duì)團(tuán)隊(duì)版本一起步是非常重要的。它保證了不同開(kāi)發(fā)者機(jī)器上安裝的依賴(lài)版本完全一致。我自己會(huì)在項(xiàng)目開(kāi)新分支時(shí)特意看一眼 packages-lock.json 的 diff如果某個(gè)同事升級(jí)了一個(gè)包這個(gè)文件通常會(huì)被改動(dòng)。保持這個(gè)文件的追蹤狀態(tài)你就能對(duì)項(xiàng)目依賴(lài)變化歷史一目了然。順帶一提如果團(tuán)隊(duì)采用 Git 依賴(lài)我強(qiáng)烈建議不要輕易把 packages-lock.json 加入 .gitignore。一旦忽略它你就會(huì)失去依賴(lài)解析的一致性保護(hù)。一個(gè)開(kāi)發(fā)機(jī)上的包版本是 1.2.0另一個(gè)開(kāi)發(fā)機(jī)卻裝上了 1.3.0最終問(wèn)題定位時(shí)間會(huì)成倍增加。6. 我個(gè)人實(shí)踐中的一點(diǎn)體會(huì)和下一步思路折騰自定義包很多次之后我的核心體會(huì)是這個(gè)功能不是給項(xiàng)目代碼做“搬家”而是強(qiáng)迫你拿出一套管理模塊邊界的標(biāo)準(zhǔn)。沒(méi)有自定義包時(shí)我寫(xiě)代碼憑感覺(jué)公共代碼散落在項(xiàng)目各處有了自定義包后我會(huì)下意識(shí)先問(wèn)自己“這段代碼將來(lái)會(huì)不會(huì)被別的項(xiàng)目用到”。這個(gè)思維轉(zhuǎn)變對(duì)代碼質(zhì)量的影響比表面看到的那層目錄結(jié)構(gòu)大得多。如果你是第一次嘗試我建議不要一上來(lái)就把現(xiàn)有項(xiàng)目拆得七零八落。挑一個(gè)足夠簡(jiǎn)單又確實(shí)重復(fù)使用的模塊比如存檔、音頻管理或?qū)ο蟪匕阉?dú)立成一個(gè)包先走通本地流程再走通 Git 分發(fā)。這個(gè)過(guò)程里你自然會(huì)遇到命名空間、程序集引用、資源放置這些具體問(wèn)題解決這些問(wèn)題的經(jīng)驗(yàn)遠(yuǎn)比讀十篇概念分析文章更值錢(qián)。后續(xù)如果你愿意繼續(xù)擴(kuò)展可以研究一下用 UPM 提供的入口腳本自動(dòng)化生成包配置比如為每個(gè)新模塊一鍵生成 package.json 和 asmdef 文件。也可以為自己的自定義包寫(xiě)一套專(zhuān)門(mén)的生命周期測(cè)試在 CI 里構(gòu)建一個(gè)空項(xiàng)目再安裝包確保包的搭建信息在干凈環(huán)境下仍然成立。這些都是把模塊化開(kāi)發(fā)推向正規(guī)化的進(jìn)階方向但它仍然要建立在一個(gè)基礎(chǔ)之上先把自己的公共代碼從項(xiàng)目里解放出來(lái)放到一個(gè)帶著版本和邊界的獨(dú)立包里。這一步一旦邁出去后續(xù)的團(tuán)隊(duì)協(xié)作和項(xiàng)目迭代都會(huì)輕松很多。