1. 為什么自定義包值得研究很多 Unity 開發(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)端的有做編輯器工具的也有專門做原型驗(yàn)證的小項(xiàng)目。過(guò)去我習(xí)慣把公共代碼復(fù)制進(jìn)每個(gè)項(xiàng)目比如對(duì)象池、存檔模塊、UI 框架、網(wǎng)絡(luò)連接管理。一開始確實(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è)試開銷極其巨大。這還沒(méi)算上那些藏在 Assets 里的 prefab、shader、材質(zhì)球復(fù)制粘貼根本無(wú)法自動(dòng)追蹤依賴關(guān)系。自定義包正是解決這個(gè)痛點(diǎn)的標(biāo)準(zhǔn)化方案。它把代碼、資源、配置、程序和文檔統(tǒng)一到一個(gè)帶有版本信息的包里由 Unity 自帶的 UPM 統(tǒng)一管理。你可以把包放到本地磁盤某個(gè)目錄也可以推到 Git 倉(cāng)庫(kù)然后在任意項(xiàng)目的 manifest.json 里添加一行依賴約定整個(gè)包就自動(dòng)被安裝并參與編譯。更新的流程也變得清晰改包發(fā)版本項(xiàng)目方自己決定什么時(shí)候升級(jí)依賴。這個(gè)方案非常適合這幾類人經(jīng)常重復(fù)造輪子的獨(dú)立游戲開發(fā)者、想把公共模塊統(tǒng)一管理的開發(fā)團(tuán)隊(duì)、需要把編輯器小工具分發(fā)給同事的技術(shù)美術(shù)或工具開發(fā)者。如果你只是在一個(gè)小游戲項(xiàng)目里寫幾段一次性腳本那自定義包確實(shí)不是剛需但只要你開始跨項(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)法保證它們一致。其次是資源依賴被撕開。Unity 的開發(fā)特點(diǎn)是代碼和資源深度綁定公共模塊往往不只是腳本還有對(duì)應(yīng)的 shader、材質(zhì)、ScriptableObject 配置、動(dòng)畫控制器。你用復(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)切換分支、重新打開項(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)目在用哪版代碼打開文件就能看到。包的依賴關(guān)系也是顯式的。如果這個(gè)包依賴另一個(gè)包比如對(duì)象池包依賴一個(gè)數(shù)學(xué)工具包你可以在 package.json 里聲明UPM 會(huì)自動(dòng)把依賴包一并解析安裝。這比你在項(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í)是在代碼層面畫了一條清晰的線模塊外部只能通過(guò)約定好的公開 API 來(lái)使用模塊不能隨手改動(dòng)內(nèi)部結(jié)構(gòu)。在多人團(tuán)隊(duì)里這條邊界極其重要它能防止公共代碼被項(xiàng)目里的臨時(shí)需求越改越亂。我個(gè)人的感受是自定義包把“這段代碼是這個(gè)項(xiàng)目的一部分”徹底變成了“這個(gè)項(xiàng)目的一部分取決于這段代碼”。依賴關(guān)系被顯式記錄、版本被管理、邊界被定義后面所有協(xié)作和迭代都建立在這個(gè)基礎(chǔ)上心里踏實(shí)很多。2. 制作一個(gè)自定義包的最小可運(yùn)行流程理解概念之后我們直接動(dòng)手。對(duì)一個(gè) Unity 開發(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 開始全面使用 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 在解決依賴時(shí)會(huì)參考這個(gè)版本號(hào)所以不要亂填。displayName顯示在 Package Manager 窗口里的包名可以寫成用戶友好的名字。description包的說(shuō)明文字會(huì)展示在包詳情面板。寫清楚它負(fù)責(zé)什么功能依賴哪些外圍條件對(duì)團(tuán)隊(duì)其他成員幫助很大。unity聲明這個(gè)包支持的 Unity 版本。實(shí)測(cè)下來(lái)如果包使用了某些僅高版本支持的 API這里就寫對(duì)應(yīng)版本否則不寫也行。dependencies包的依賴列表。UPM 會(huì)自動(dòng)解析比一個(gè)人手動(dòng)安裝依賴要可靠得多。要注意的是這里填的依賴版本是一個(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 分開放包建成之后腳本不是隨便丟進(jìn)文件夾就完事。由于包會(huì)被 UPM 納入項(xiàng)目的編譯流程你最好從一開始就把代碼按照運(yùn)行時(shí)機(jī)拆分清楚否則日后會(huì)有很多意想不到的編譯問(wèn)題和包體大小問(wèn)題。常規(guī)做法是在包根目錄下建 Runtime 和 Editor 兩個(gè)文件夾。Runtime 里放最終運(yùn)行時(shí)執(zhí)行的代碼比如存檔管理器、對(duì)象池、網(wǎng)絡(luò)客戶端、視頻播放組件。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彼此隔離互不干擾。你不需要額外手寫任何判斷只要目錄對(duì)了后面的構(gòu)建行為基本都是合理默認(rèn)。2.2.1 私有程序集與 asmdef 設(shè)計(jì)如果你希望包內(nèi)部結(jié)構(gòu)再嚴(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í)際依賴的第三方包的引用Editor 程序集則要在 references 里額外引用 Runtime 程序集。這樣設(shè)計(jì)的好處是你想讓包的公開 API 區(qū)域和內(nèi)部實(shí)現(xiàn)區(qū)域徹底隔離外部代碼能看到的就是你在 Runtime 程序集里標(biāo)記為 public 的那部分。內(nèi)部輔助類即使寫成 public但程序集名不同外部引用通常不會(huì)亂進(jìn)。asmdef 文件本身是 JSON內(nèi)容不長(zhǎng)。如果你不想完全手寫可以直接在 Unity 里右鍵文件夾創(chuàng)建 Assembly Definition然后通過(guò) Inspector 配置引用。不過(guò)我還是推薦了解一下手寫結(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 窗口添加本地包。打開 Window Package Manager點(diǎn)擊左上角加號(hào)選擇 Add package from disk然后定位到包的根目錄選中 package.json 即可。這種方式適合你正在桌面某個(gè)目錄里開發(fā)包要多項(xiàng)目聯(lián)調(diào)的情況。它會(huì)把包加入 manifest.json 的 dependencies記錄為 file: 協(xié)議路徑。第二種是直接在 manifest.json 里寫入本地路徑。例如{ dependencies: { com.example.savesystem: file:../../Packages/ExampleSaveSystem } }這種方式適合用文本編輯器手動(dòng)管理依賴或者想在腳本里批量添加依賴的場(chǎng)景。路徑可以是絕對(duì)路徑但我建議用相對(duì)路徑這樣整個(gè)項(xiàng)目目錄被挪動(dòng)時(shí)依賴仍能正常工作。第三種是作為一個(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ì)于本地開發(fā)階段我個(gè)人最喜歡 Add package from disk 的方式它會(huì)直接在項(xiàng)目里生成顯式的 file: 依賴包更新時(shí)只需要替換目錄內(nèi)容并點(diǎn)擊刷新就能看到最新代碼。切記不要把 file: 路徑依賴提交到需要多人協(xié)作的倉(cāng)庫(kù)除非你對(duì)路徑的穩(wěn)定性非常有把握否則它很容易在不同開發(fā)機(jī)上失效。3. 從實(shí)用角度設(shè)計(jì)包內(nèi)模塊包能跑起來(lái)之后關(guān)鍵的思維轉(zhuǎn)變是你現(xiàn)在不是在給某個(gè)項(xiàng)目寫代碼而是在設(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è)公開門面類團(tuán)隊(duì)所有項(xiàng)目都只通過(guò)它來(lái)讀寫存檔不直接接觸 Storage 接口。這相當(dāng)于把包的內(nèi)部實(shí)現(xiàn)變化與外部調(diào)用隔離。今天我用 PlayerPrefs 存明天改成 Json 文件存只要 SaveManager 的 API 不變其他項(xiàng)目一行都不用改。這種設(shè)計(jì)是模塊化開發(fā)的精髓。至于 SaveData 這種數(shù)據(jù)類我通常會(huì)做成可序列化的基礎(chǔ)類。由于存檔數(shù)據(jù)在多個(gè)項(xiàng)目里差異很大我不打算在包里寫死字段而是讓使用方繼承自己的數(shù)據(jù)模型。這要求包的公開 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è)包依賴了某個(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è)小技巧把所有依賴項(xiàng)和資源放到一個(gè)臨時(shí)空項(xiàng)目里只通過(guò) manifest 安裝這個(gè)包然后打開其中資源隨意點(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 之類的外部 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 依賴的完整做法以及這個(gè)過(guò)程中的版本管理策略。4.1 推送到 Git 倉(cāng)庫(kù)并用 URL 安裝目前 Unity 支持通過(guò) Git URL 直接把包作為依賴安裝這是團(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)兩種寫法{ dependencies: { com.example.savesystem: https://github.com/example/ExampleSaveSystem.git#v1.2.0 } }也可以加通配符版本范圍不過(guò)推薦固定 tag因?yàn)檫@樣項(xiàng)目的依賴是可復(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 的引用方式把路徑依賴留給單機(jī)開發(fā)或聯(lián)調(diào)階段。4.2 版本號(hào)策略與依賴沖突處理包一旦有多個(gè)項(xiàng)目引用版本就成了團(tuán)隊(duì)協(xié)作的核心語(yǔ)言。版本號(hào)不是隨便填的它的語(yǔ)義直接影響依賴解析。按語(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 在解析依賴時(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è)依賴樹就亂了多個(gè)包之間會(huì)出現(xiàn)莫名其妙的 API 不匹配。我自己踩過(guò)最大的坑是包 A 依賴包 B而項(xiàng)目里包 A 和包 B 是從兩個(gè)不同開發(fā)者的倉(cāng)庫(kù)直接裝的。由于沒(méi)有統(tǒng)一版本策略最終項(xiàng)目在編譯階段出現(xiàn)了大量重名類、重復(fù)命名空間沖突。處理辦法只能回滾依賴版本。所以從第一天起團(tuán)隊(duì)就要規(guī)定發(fā)布包版本前必須寫 changelog 并遵守語(yǔ)義化版本號(hào)否則協(xié)作越深入越難收拾。4.2.1 內(nèi)網(wǎng)私有 Git 倉(cāng)庫(kù)的補(bǔ)充建議如果你的團(tuán)隊(duì)在局域網(wǎng)內(nèi)開發(fā)不希望把代碼推到公網(wǎng)也可以用自建的 Git 服務(wù)比如 GitLab CE 或 Gitea。Unity 的 Git URL 依賴只要是一個(gè)可以被正常 clone 的 Git 地址都行不區(qū)分是否公網(wǎng)。需要提醒的是URL 中如果包含認(rèn)證信息Unity 編輯器自身對(duì)賬號(hào)認(rèn)證的支持比較有限推薦在開發(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 用法、依賴關(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 里堆滿了舊 API 或讓人困惑的寫法使用者會(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ò)找不到類型或方法這通常是 asmdef 的引用配置出了問(wèn)題。舉個(gè)例子你可能在 Runtime 腳本里用了 Newtonsoft.Json但包的 asmdef references 里沒(méi)有添加 Newtonsoft.Json。這時(shí)編譯會(huì)報(bào)“當(dāng)前上下文中不存在名稱 JsonConvert”即便這個(gè)包在 Unity 默認(rèn)程序集里能正常使用。為什么因?yàn)?asmdef 一旦生效包內(nèi)代碼的可見(jiàn)引用范圍就受程序集約束了它不會(huì)自動(dòng)引用項(xiàng)目里的其他程序集除非你在 asmdef 里顯式添加。排查思路很簡(jiǎn)單先打開包的 asmdef 文件檢查 references 列表里有沒(méi)有包含需要引用的程序集名。如果是第三方 DLL還需要確認(rèn) precompiledReferences 或 UnityEngine 模塊引用是否完備。也可以先在 Unity 里點(diǎn)選報(bào)錯(cuò)的腳本看 Inspector 里那個(gè)三角形的警告它會(huì)直接告訴你這個(gè)腳本屬于哪個(gè)程序集以及有哪些引用缺失。另外要留意循環(huán)依賴。如果你的包 A 引用了包 B而包 B 又引用了包 AUPM 在編譯階段會(huì)報(bào)程序集循環(huán)引用錯(cuò)誤。解決這種問(wèn)題需要重新審視包的功能邊界盡量保證依賴方向是單向的或者把相互引用的公共部分抽離成更底層的包。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 后重新打開項(xiàng)目強(qiáng)制 UPM 重新解析所有依賴。不過(guò)這個(gè)操作影響全局依賴執(zhí)行前最好確認(rèn)沒(méi)有其他同事正在同時(shí)改動(dòng)依賴。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í)打開編輯器窗口修改包后直接切回 Unity等右下角編譯轉(zhuǎn)圈結(jié)束再運(yùn)行二是遇到頑固不刷新時(shí)手動(dòng)執(zhí)行 Assets Refresh或按 CtrlR必要時(shí)關(guān)閉并重新打開項(xiàng)目。千萬(wàn)別在編輯器還在編譯時(shí)強(qiáng)行改包文件會(huì)導(dǎo)致下一次 import 偶爾出現(xiàn)半寫入的臨時(shí)狀態(tài)寧愿等穩(wěn)定了再動(dòng)。5.4 閱讀 locked file 的注意事項(xiàng)UPM 默認(rèn)的 packages-lock.json 對(duì)團(tuán)隊(duì)版本一起步是非常重要的。它保證了不同開發(fā)者機(jī)器上安裝的依賴版本完全一致。我自己會(huì)在項(xiàng)目開新分支時(shí)特意看一眼 packages-lock.json 的 diff如果某個(gè)同事升級(jí)了一個(gè)包這個(gè)文件通常會(huì)被改動(dòng)。保持這個(gè)文件的追蹤狀態(tài)你就能對(duì)項(xiàng)目依賴變化歷史一目了然。順帶一提如果團(tuán)隊(duì)采用 Git 依賴我強(qiáng)烈建議不要輕易把 packages-lock.json 加入 .gitignore。一旦忽略它你就會(huì)失去依賴解析的一致性保護(hù)。一個(gè)開發(fā)機(jī)上的包版本是 1.2.0另一個(gè)開發(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í)我寫代碼憑感覺(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)比讀十篇概念分析文章更值錢。后續(xù)如果你愿意繼續(xù)擴(kuò)展可以研究一下用 UPM 提供的入口腳本自動(dòng)化生成包配置比如為每個(gè)新模塊一鍵生成 package.json 和 asmdef 文件。也可以為自己的自定義包寫一套專門的生命周期測(cè)試在 CI 里構(gòu)建一個(gè)空項(xiàng)目再安裝包確保包的搭建信息在干凈環(huán)境下仍然成立。這些都是把模塊化開發(fā)推向正規(guī)化的進(jìn)階方向但它仍然要建立在一個(gè)基礎(chǔ)之上先把自己的公共代碼從項(xiàng)目里解放出來(lái)放到一個(gè)帶著版本和邊界的獨(dú)立包里。這一步一旦邁出去后續(xù)的團(tuán)隊(duì)協(xié)作和項(xiàng)目迭代都會(huì)輕松很多。