上個(gè)月有個(gè)同行在群里發(fā)了張截圖一個(gè)公共的日志封裝模塊被三個(gè)業(yè)務(wù)項(xiàng)目各復(fù)制了一份半年下來(lái)三個(gè)副本的函數(shù)簽名全不一樣了。修一個(gè)時(shí)間格式化的 bug得在三個(gè)倉(cāng)庫(kù)里改三遍還漏了一次結(jié)果線上只有一個(gè)項(xiàng)目生效。這種場(chǎng)面我見(jiàn)過(guò)太多次幾乎每個(gè)團(tuán)隊(duì)發(fā)展到一定規(guī)模都會(huì)撞上同一個(gè)坎——公共代碼到底該怎么在多個(gè) Git 版本庫(kù)之間共享。Git 原生給了兩套思路完全不同的解法子模塊submodule和子樹(shù)subtree。前者把另一個(gè)倉(cāng)庫(kù)當(dāng)成一個(gè)指針釘死在你當(dāng)前倉(cāng)庫(kù)的某個(gè)提交上后者把另一個(gè)倉(cāng)庫(kù)的內(nèi)容連同歷史一起揉進(jìn)你自己的倉(cāng)庫(kù)。兩者都能讓公共代碼只保留一份源頭但在日常協(xié)作里的表現(xiàn)、坑位、維護(hù)成本差異極大。這篇就圍繞版本庫(kù)之間的依賴這個(gè)主題把兩種機(jī)制的存儲(chǔ)模型、完整操作流、高危動(dòng)作和選型邏輯拆開(kāi)講清楚。不管你是剛開(kāi)始拆分公共庫(kù)還是已經(jīng)被子模塊坑過(guò)一次打算換方案應(yīng)該都能從中找到能直接抄的東西。1. 從復(fù)制粘貼到依賴管理中間隔著的到底是什么問(wèn)題1.1 三個(gè)副本的宿命從先用著到誰(shuí)也說(shuō)不清先說(shuō)復(fù)制粘貼這條路為什么一定會(huì)崩。它的問(wèn)題不在于懶而在于復(fù)制的那一刻就把同源關(guān)系給切斷了。假設(shè)項(xiàng)目 A 在三月復(fù)制了一份工具庫(kù)項(xiàng)目 B 在五月復(fù)制了一份項(xiàng)目 C 在九月復(fù)制了一份。這三次復(fù)制的起點(diǎn)其實(shí)已經(jīng)是三個(gè)不同的版本了只是當(dāng)時(shí)沒(méi)人意識(shí)到。后面修 bug 時(shí)A 的維護(hù)者改了dateFormat的時(shí)區(qū)處理B 的維護(hù)者加了緩存C 的維護(hù)者什么都沒(méi)動(dòng)。等到需要統(tǒng)一升級(jí)某個(gè)底層依賴時(shí)你面對(duì)的是三段互不相干的歷史沒(méi)有任何機(jī)制能告訴你這三個(gè)文件曾經(jīng)是同一個(gè)東西。比這更隱蔽的問(wèn)題是職責(zé)歸屬。復(fù)制之后每個(gè)項(xiàng)目團(tuán)隊(duì)都會(huì)覺(jué)得這是我們的代碼于是開(kāi)始按自己的需求改。公共庫(kù)那邊提出一個(gè)改進(jìn)沒(méi)人愿意跟進(jìn)公共庫(kù)提了一個(gè)不兼容的 API 變更三個(gè)項(xiàng)目各自打補(bǔ)丁。一年之后公共庫(kù)和三個(gè)副本已經(jīng)是四個(gè)不同的項(xiàng)目了只是長(zhǎng)得有點(diǎn)像。版本庫(kù)之間的依賴管理本質(zhì)就是解決兩件事代碼歸屬清晰源頭只有一個(gè)和版本可控每個(gè)消費(fèi)者明確知道自己用的是哪個(gè)版本。這兩件事聽(tīng)起來(lái)簡(jiǎn)單但它們的實(shí)現(xiàn)方式是互相拉扯的——你越想鎖定版本升級(jí)就越痛苦你越想跟隨最新穩(wěn)定性就越差。1.2 鎖指針與并歷史Git 給出的兩條路線Git 的兩種機(jī)制正好對(duì)應(yīng)這兩種取舍。子模塊走的是鎖指針路線。父?jìng)}庫(kù)里記錄的不是子模塊的文件內(nèi)容而是一個(gè)指向子模塊某個(gè)具體提交的引用。這個(gè)引用在 Git 的索引里表現(xiàn)為一個(gè)特殊的條目對(duì)象類型是commit權(quán)限位是160000。翻譯成人話就是父?jìng)}庫(kù)只記得這個(gè)目錄應(yīng)該是某某倉(cāng)庫(kù)的第幾個(gè)提交至于那個(gè)目錄下面有什么文件它一概不管。子樹(shù)走的是并歷史路線。它把對(duì)方倉(cāng)庫(kù)的內(nèi)容直接復(fù)制到你倉(cāng)庫(kù)的一個(gè)子目錄里作為一個(gè)普通的提交合進(jìn)來(lái)。合完之后那些文件就是你倉(cāng)庫(kù)的一部分了正常 clone 就能拿到?jīng)]有任何額外步驟。代價(jià)是倉(cāng)庫(kù)體積會(huì)變大歷史會(huì)混在一起。這兩條路線的分歧點(diǎn)從第一秒就決定了后面所有的操作方式和坑位分布。理解這一點(diǎn)比記住那幾條命令重要得多。2. submodule 的存儲(chǔ)模型父?jìng)}庫(kù)里究竟存了些什么2.1 一個(gè) gitlink、一個(gè)配置文件、一個(gè)獨(dú)立對(duì)象庫(kù)很多人第一次用子模塊會(huì)懵因?yàn)榭床坏筋A(yù)期的文件。執(zhí)行完添加命令之后父?jìng)}庫(kù)里多了三樣?xùn)|西位置和作用各不相同第一樣是索引中的一個(gè) gitlink 條目。它躺在父?jìng)}庫(kù)的索引里記錄路徑 → 提交 SHA這條映射。你用git ls-tree能看到它git ls-tree HEAD vendor/lib-shared # 160000 commit 8a3f9c2e1b7d4a5f6e8c9d0b1a2f3e4d5c6b7a8f vendor/lib-shared注意那個(gè)160000這是 Git 專門為子模塊保留的文件模式含義是這里不是文件也不是目錄是指向另一個(gè)倉(cāng)庫(kù)的引用。第二樣是倉(cāng)庫(kù)根目錄的.gitmodules文件。這個(gè)是唯一被父?jìng)}庫(kù)正常跟蹤的配置文件里面記錄了子模塊的路徑和 URL還可以指定跟蹤哪個(gè)分支[submodule vendor/lib-shared] path vendor/lib-shared url https://example.com/lib-shared.git branch main第三樣是父?jìng)}庫(kù).git/modules/下的一份獨(dú)立對(duì)象庫(kù)。子模塊的提交對(duì)象、分支、遠(yuǎn)端配置都存在這里而不是寫在子目錄自己的.git里。子目錄下的.git其實(shí)是一個(gè)文本文件內(nèi)容就一行g(shù)itdir: ../../.git/modules/vendor/lib-shared這個(gè)設(shè)計(jì)的意義在于父?jìng)}庫(kù)的.git目錄被完整搬走或備份時(shí)子模塊的歷史也跟著走。但也正因?yàn)檫@樣刪除子模塊時(shí)如果只刪目錄.git/modules/里的殘留會(huì)一直掛著后面同名添加會(huì)報(bào)錯(cuò)。把這三樣?xùn)|西記清楚后面的所有問(wèn)題你都能定位到根上。2.2 從零添加一個(gè)子模塊的完整命令流假設(shè)現(xiàn)在要把一個(gè)公共工具庫(kù)掛到項(xiàng)目的vendor/lib-shared下面# 1. 添加子模塊同時(shí)會(huì)在 .gitmodules 里寫入配置 git submodule add https://example.com/lib-shared.git vendor/lib-shared # 2. 如果需要它跟蹤某個(gè)分支而不是默認(rèn)分支 git config -f .gitmodules submodule.vendor/lib-shared.branch main # 3. 提交這兩處變更.gitmodules 和索引中的 gitlink git add .gitmodules vendor/lib-shared git commit -m chore: 引入公共工具庫(kù)作為子模塊這里有個(gè)細(xì)節(jié)值得說(shuō)一下git submodule add會(huì)自動(dòng)把子模塊的 HEAD 設(shè)置成遠(yuǎn)端默認(rèn)分支的最新提交但它不會(huì)自動(dòng)切換到那個(gè)分支上。子模塊在添加完之后處于游離頭指針detached HEAD狀態(tài)這是正常設(shè)計(jì)——父?jìng)}庫(kù)鎖定的是一個(gè)具體提交而不是一個(gè)分支名。如果你不確定git submodule status會(huì)在提交 SHA 前面沒(méi)有任何前綴表示狀態(tài)正常。如果我是在一個(gè)已經(jīng)有內(nèi)容的老項(xiàng)目里加還得注意目標(biāo)路徑不能已存在且非空否則命令會(huì)直接拒絕。要么換個(gè)路徑要么先把老內(nèi)容清掉。2.3 克隆方要做的事以及漏做之后看到的現(xiàn)象這是子模塊最容易翻車的地方。默認(rèn)的git clone不會(huì)拉取子模塊的內(nèi)容你 clone 下來(lái)看到的是一個(gè)空目錄或者一個(gè)只有.git文件的空殼。正確的做法有兩種。一次性的是git clone --recurse-submodules https://example.com/project-a.git已經(jīng) clone 完了才想起來(lái)那就補(bǔ)一刀git submodule update --init --recursive--init的作用是根據(jù).gitmodules把配置寫進(jìn)本地配置--recursive是處理子模塊里面還嵌套子模塊的情況。少寫--init時(shí)會(huì)報(bào)錯(cuò)說(shuō)子模塊未注冊(cè)少寫--recursive時(shí)外層好了里層還是空的。還有一種情況你已經(jīng) clone 了也 init 過(guò)了但是父?jìng)}庫(kù)的維護(hù)者后來(lái)把子模塊的指針推到了一個(gè)新提交。這時(shí)候git pull只會(huì)更新父?jìng)}庫(kù)的 gitlink子目錄里的文件還是舊的。git submodule status會(huì)在這個(gè)子模塊前面顯示一個(gè)號(hào)意思是工作區(qū)的 HEAD 和索引記錄的提交不一致。補(bǔ)一條git submodule update就同步了。我見(jiàn)過(guò)最典型的事故是 CI 流水線。構(gòu)建腳本里寫了git clone后面直接跑單元測(cè)試結(jié)果測(cè)試引用的那個(gè)模塊目錄是空的報(bào)一堆 import 錯(cuò)誤。排查的人花了兩個(gè)小時(shí)以為是依賴安裝的問(wèn)題。后來(lái)做了一件事在所有項(xiàng)目的 CI 配置里統(tǒng)一加上submodule: true或者在 clone 步驟顯式帶--recurse-submodules這類問(wèn)題就絕跡了。3. 子模塊的高危動(dòng)作與日常維護(hù)紀(jì)律3.1 改了子模塊代碼卻忘記回父?jìng)}庫(kù)提交指針這個(gè)坑的觸發(fā)率我估摸著有七成以上。場(chǎng)景是這樣的你在子模塊目錄里改了一行代碼進(jìn)去git add、git commit、git push一氣呵成覺(jué)得沒(méi)問(wèn)題了。然后回到父?jìng)}庫(kù)看到git status顯示vendor/lib-shared有變化modified: vendor/lib-shared (new commits)你可能順手就git checkout .給還原了或者壓根沒(méi)注意就切分支走人了。結(jié)果就是子模塊上游有了新提交但父?jìng)}庫(kù)的鎖定指針還停在舊位置。別人 clone 下來(lái)拿到的還是舊版本然后來(lái)問(wèn)你你改的東西在哪呢。正確的收尾動(dòng)作是固定的三步# 在子模塊內(nèi)完成改動(dòng)并推送 cd vendor/lib-shared git add . git commit -m fix: 修正時(shí)區(qū)解析 git push origin HEAD:main # 回到父?jìng)}庫(kù)把新的指針提交上去 cd ../.. git add vendor/lib-shared git commit -m chore: 同步公共庫(kù)至最新提交 git pushgit add vendor/lib-shared這一步加進(jìn)去的不是文件內(nèi)容而是那個(gè)新的提交 SHA。父?jìng)}庫(kù)這次提交之后所有 clone 的人才知道應(yīng)該檢出哪個(gè)版本。提示提交前養(yǎng)成git submodule status看一眼的習(xí)慣帶前綴就說(shuō)明指針沒(méi)同步。3.2 分支切換引發(fā)的指針錯(cuò)位和游離頭指針父?jìng)}庫(kù)在不同分支上鎖定的子模塊提交可能不一樣。當(dāng)你在兩個(gè)分支之間來(lái)回切時(shí)Git 會(huì)自動(dòng)更新 gitlink但不會(huì)自動(dòng)更新工作區(qū)里子模塊的實(shí)際內(nèi)容。于是你會(huì)看到狀態(tài)一直是子目錄里的代碼和當(dāng)前分支預(yù)期的版本對(duì)不上。解決辦法是在切分支時(shí)帶上遞歸git checkout feature-x --recurse-submodules # 或者在切換后立刻 git submodule update --recursive第二個(gè)容易懵的點(diǎn)是游離頭指針。在子模塊里直接git status會(huì)看到一行提示說(shuō)當(dāng)前不在任何分支上。這不算錯(cuò)誤但如果你在子模塊里改了東西又沒(méi)有先建分支切走之后提交會(huì)丟。我的習(xí)慣是進(jìn)子模塊改代碼前先執(zhí)行g(shù)it switch -c fix/timezone-parse改完推送再按上一節(jié)的三步走。多花三秒省掉一次深夜找提交。還有一種邊界情況兩個(gè)分支對(duì)同一個(gè)子模塊鎖定的提交差得很遠(yuǎn)切過(guò)去之后 Git 可能會(huì)拒絕切換說(shuō)會(huì)覆蓋未跟蹤的文件。這時(shí)候要么先git submodule update把工作區(qū)清干凈要么把改動(dòng) stash 掉。強(qiáng)推-f不是好主意因?yàn)樽幽K里的未提交改動(dòng)會(huì)被直接抹掉找不回來(lái)。3.3 批量操作、遞歸配置與嵌套子模塊的處理項(xiàng)目大了之后子模塊可能有五六個(gè)手動(dòng)一個(gè)一個(gè) update 效率太低。這時(shí)候有兩個(gè)工具。第一個(gè)是git submodule foreach遍歷所有子模塊執(zhí)行命令# 一次性把所有子模塊切到 main 分支并拉取最新 git submodule foreach git switch main git pull # 查看所有子模塊當(dāng)前的狀態(tài)和遠(yuǎn)端地址 git submodule foreach git remote -v git log -1 --oneline第二個(gè)是全局開(kāi)啟遞歸。Git 支持把一些命令默認(rèn)變成遞歸模式# 讓 checkout / fetch 等命令默認(rèn)處理子模塊 git config --global submodule.recurse true # pull 時(shí)按需拉取子模塊哪個(gè)指針變了拉哪個(gè)省時(shí)間 git pull --recurse-submoduleson-demandon-demand這個(gè)選項(xiàng)值得單獨(dú)說(shuō)。默認(rèn)的遞歸拉取會(huì)把所有子模塊都 fetch 一遍項(xiàng)目里子模塊多了光 fetch 就要幾十秒。on-demand只處理父?jìng)}庫(kù)指針發(fā)生變化的那些速度快很多。嵌套子模塊的處理原則是所有命令都帶--recursive包括 clone、update、foreach。子模塊里再掛子模塊雖然能用但維護(hù)成本直線上升超過(guò)兩層我個(gè)人建議直接換方案或者把最內(nèi)層改成包管理器分發(fā)。權(quán)限方面也有個(gè)坑如果子模塊指向的是需要單獨(dú)授權(quán)的倉(cāng)庫(kù)CI 環(huán)境里的憑據(jù)可能只配了主倉(cāng)庫(kù)。表現(xiàn)是 clone 主倉(cāng)庫(kù)成功update 子模塊時(shí)提示認(rèn)證失敗。這時(shí)候要么給 CI 配能訪問(wèn)所有相關(guān)倉(cāng)庫(kù)的憑據(jù)要么把子模塊改成公開(kāi)可讀的形式。批量刪除子模塊的步驟也順手記在這里這個(gè)操作必須按順序來(lái)少一步都會(huì)留垃圾git submodule deinit -f vendor/lib-shared git rm -f vendor/lib-shared rm -rf .git/modules/vendor/lib-shared4. subtree把對(duì)方的提交歷史揉進(jìn)自己的倉(cāng)庫(kù)4.1 add、pull、push 三段式的操作流程子樹(shù)的核心思想很樸素不搞指針直接把對(duì)方的文件復(fù)制進(jìn)來(lái)作為一次普通提交合入。這意味著你 clone 之后什么都不用做代碼就在那兒。第一次引入git subtree add --prefixlibs/lib-shared \ https://example.com/lib-shared.git main --squash--prefix指定落地目錄--squash表示把上游的整段歷史壓成一個(gè)提交塞進(jìn)來(lái)。不加這個(gè)參數(shù)會(huì)把上游所有提交都并入你的歷史可追溯性更好但倉(cāng)庫(kù)會(huì)明顯變大。后續(xù)同步上游更新git subtree pull --prefixlibs/lib-shared \ https://example.com/lib-shared.git main --squash反過(guò)來(lái)你在本地這個(gè)目錄里改了東西想推回上游git subtree push --prefixlibs/lib-shared \ https://example.com/lib-shared.git main這條命令背后做的事比看起來(lái)復(fù)雜它會(huì)從你的整個(gè)提交歷史里把所有影響libs/lib-shared這個(gè)前綴的提交挑出來(lái)重新組織成一段干凈的歷史再推給上游。所以如果倉(cāng)庫(kù)歷史很長(zhǎng)subtree push會(huì)明顯慢有時(shí)候要等十幾秒甚至更久。這是子樹(shù)方案最容易被吐槽的點(diǎn)但它也確實(shí)解決了雙向同步這個(gè)問(wèn)題。一個(gè)實(shí)操建議把這三個(gè)命令寫成腳本或者 git alias別每次手敲。比如git config alias.spull subtree pull --prefixlibs/lib-shared git config alias.spush subtree push --prefixlibs/lib-shared4.2 split 與 squash 的取舍以及合并沖突怎么處理git subtree split是子樹(shù)的另一個(gè)核心能力——把一個(gè)子目錄的歷史單獨(dú)抽出來(lái)變成一個(gè)獨(dú)立分支git subtree split --prefixlibs/lib-shared -b shared-only這條命令產(chǎn)生的分支歷史里只包含影響那個(gè)目錄的提交其他提交全部被過(guò)濾掉。它的典型用途是把一個(gè)項(xiàng)目里的公共部分剝離出去獨(dú)立成庫(kù)。--squash用不用取決于你是想保留上游的完整提交記錄還是只關(guān)心內(nèi)容快照。我的判斷標(biāo)準(zhǔn)是這樣的如果是內(nèi)部團(tuán)隊(duì)維護(hù)的公共庫(kù)雙方都要雙向提交那不加 squash歷史完整出問(wèn)題時(shí)能查到具體是哪次提交引入的如果是引用的第三方代碼基本只讀那加 squash倉(cāng)庫(kù)干凈體積也可控。沖突處理上子樹(shù)跟普通 merge 完全一樣。git subtree pull遇到?jīng)_突會(huì)停下來(lái)你在工作區(qū)解決git add然后git commit完成合并。有個(gè)小細(xì)節(jié)沖突標(biāo)記里的路徑是帶前綴的完整路徑看一眼就知道是哪個(gè)文件在打架。解決完不需要額外操作比子模塊那套進(jìn)去出來(lái)再提交指針的流程省心不少。4.3 子樹(shù)方案那些不會(huì)寫在文檔里的隱性成本子樹(shù)看起來(lái)很美好但有幾筆賬得提前算。第一筆是倉(cāng)庫(kù)體積。每次subtree pull都會(huì)在你的倉(cāng)庫(kù)里增加提交不管你加沒(méi)加 squash。一個(gè)每天都同步的項(xiàng)目一年下來(lái)倉(cāng)庫(kù)能胖出好幾百兆。如果你在意 clone 速度這個(gè)成本會(huì)慢慢顯現(xiàn)。第二筆是歷史噪音。不加 squash 時(shí)上游的每個(gè)提交都會(huì)出現(xiàn)在你的git log里作者是別人提交信息跟你項(xiàng)目的規(guī)范也對(duì)不上。做 blame 分析的時(shí)候會(huì)被干擾。第三筆是push 的可靠性。subtree push在歷史復(fù)雜時(shí)容易發(fā)生奇怪的情況比如推送被拒絕但報(bào)錯(cuò)信息看不出原因。最常見(jiàn)的觸發(fā)條件是你本地這個(gè)目錄的提交里有合并提交split 出來(lái)的歷史無(wú)法線性應(yīng)用。遇到時(shí)可以先git subtree split出一個(gè)中間分支檢查一下里面的提交是否合理再?gòu)哪莻€(gè)分支推。第四筆是前后綴的一致性。--prefix一旦定下來(lái)就最好別改因?yàn)?split 的邏輯完全依賴路徑匹配。改了目錄名等于把歷史斷了后續(xù) pull 會(huì)當(dāng)成一個(gè)全新的目錄來(lái)合并產(chǎn)生大量重復(fù)文件。這四筆賬不是說(shuō)子樹(shù)不好而是說(shuō)它更適合單向引用為主、偶爾回推的場(chǎng)景。雙向高頻同步子樹(shù)的摩擦?xí)黠@。5. 兩種依賴方式的橫向?qū)φ张c選型判斷5.1 把差異攤成一張表我在團(tuán)隊(duì)里做選型評(píng)審時(shí)習(xí)慣用一張表把所有維度擺出來(lái)避免討論跑偏維度子模塊 submodule子樹(shù) subtree存儲(chǔ)方式父?jìng)}庫(kù)只存提交指針完整內(nèi)容并入庫(kù)clone 后的可用性需 extra 步驟才能拿到內(nèi)容直接可用版本鎖定精確鎖定到提交無(wú)鎖定同步時(shí)才更新倉(cāng)庫(kù)體積幾乎不增加隨同步次數(shù)增長(zhǎng)歷史清晰度各自獨(dú)立互不干擾混在一起需要 prefix 區(qū)分上游更新拉取update --remote或手動(dòng)切subtree pull本地改動(dòng)回推上游進(jìn)子模塊提交推送即可subtree push歷史復(fù)雜時(shí)慢沖突處理少見(jiàn)因?yàn)椴还蚕砦募?jí)歷史常見(jiàn)按普通 merge 處理團(tuán)隊(duì)上手成本較高容易漏步驟較低跟普通目錄沒(méi)差別CI 配置必須顯式加遞歸參數(shù)無(wú)需額外配置刪除干凈程度需要四步清理刪目錄加提交即可適合場(chǎng)景依賴穩(wěn)定、版本強(qiáng)約束需要頻繁雙向同步這張表里最容易被低估的是clone 后的可用性這一行。它帶來(lái)的連鎖反應(yīng)很大新人入職第一次拉代碼失敗問(wèn)一圈沒(méi)人說(shuō)得清外部合作方拿到倉(cāng)庫(kù)打不開(kāi)臨時(shí)在別的機(jī)器上驗(yàn)證一個(gè)問(wèn)題還得額外折騰一遍。而版本鎖定這一行是子模塊最大的價(jià)值。它意味著父?jìng)}庫(kù)的每一次提交都精確對(duì)應(yīng)著所有依賴的確定版本。這在需要嚴(yán)格復(fù)現(xiàn)歷史構(gòu)建的場(chǎng)景里非常關(guān)鍵——比如要給半年前的一個(gè)版本打補(bǔ)丁你檢出的那一刻所有依賴的版本都自動(dòng)還原到當(dāng)時(shí)的模樣。子樹(shù)做不到這一點(diǎn)因?yàn)閮?nèi)容已經(jīng)混進(jìn)來(lái)了你只能靠 commit 時(shí)間來(lái)猜。5.2 按團(tuán)隊(duì)形態(tài)和發(fā)布節(jié)奏做決定拋開(kāi)表格我給幾條更實(shí)用的判斷標(biāo)準(zhǔn)。看團(tuán)隊(duì)的 Git 熟練度。如果隊(duì)伍里有相當(dāng)比例的人對(duì) Git 的理解停在add / commit / push三件套子模塊會(huì)持續(xù)制造問(wèn)題。每次切分支、每次拉代碼、每次進(jìn)子模塊改東西都是一個(gè)新的出錯(cuò)點(diǎn)。子樹(shù)在這點(diǎn)上友好得多因?yàn)閷?duì)使用者來(lái)說(shuō)它就是一個(gè)普通目錄?？匆蕾嚨淖兏l率。公共庫(kù)一個(gè)月發(fā)一次版子模塊很合適升級(jí)時(shí)手動(dòng) update 一次明確可控。公共庫(kù)每天都在改而且多個(gè)項(xiàng)目都要跟著改那子樹(shù)的同步成本更低?？窗l(fā)布產(chǎn)物是否需要自包含。如果交付物是一個(gè)可以獨(dú)立部署的包需要把源碼整體打包給對(duì)方子樹(shù)更省事因?yàn)榇a本來(lái)就在倉(cāng)庫(kù)里。子模塊打包時(shí)得額外處理或者干脆不走源碼交付?？词欠裼袃?nèi)部包管理體系。如果團(tuán)隊(duì)已經(jīng)有一套成熟的包發(fā)布流程私有 registry、版本號(hào)語(yǔ)義化、依賴鎖文件那最合適的其實(shí)是既不用子模塊也不用子樹(shù)直接用包管理器。Git 的這兩種機(jī)制是沒(méi)有包管理時(shí)的替代方案不是更優(yōu)解。這點(diǎn)我踩過(guò)坑——曾經(jīng)用一個(gè)子模塊當(dāng)依賴管理結(jié)果版本升級(jí)完全靠人記后來(lái)上了包倉(cāng)庫(kù)整套流程順暢十倍。6. 從復(fù)制粘貼遷移到依賴管理的落地路徑6.1 拆出公共代碼的四個(gè)階段存量項(xiàng)目切換到依賴管理最怕的是一步到位。我的經(jīng)驗(yàn)是分四步走每一步都可回退。第一階段識(shí)別與凍結(jié)。把三個(gè)項(xiàng)目里重復(fù)的那些模塊找出來(lái)逐個(gè)對(duì)比差異列一張差異清單。這一步不寫代碼純分析。差異超過(guò)三成的模塊先不動(dòng)因?yàn)楹喜⒊杀究赡芨哂谑找?。同時(shí)給選中的模塊定一個(gè)凍結(jié)時(shí)間點(diǎn)之后不再往舊副本里加新功能。第二階段建獨(dú)立倉(cāng)庫(kù)。選一個(gè)差異最小的副本作為基礎(chǔ)新建倉(cāng)庫(kù)把代碼放進(jìn)去加上必要的構(gòu)建配置和文檔。這個(gè)倉(cāng)庫(kù)最好是能獨(dú)立跑通測(cè)試的否則后面每次改動(dòng)都沒(méi)法驗(yàn)證。第三階段逐個(gè)項(xiàng)目接入。先在一個(gè)項(xiàng)目里接入用哪個(gè)方案看前面的選型判斷。接入之后跑一輪完整回歸確認(rèn)功能正常。跑通了再動(dòng)第二個(gè)項(xiàng)目。這一步千萬(wàn)別并行出了問(wèn)題不好定位是哪個(gè)接入引入的。第四階段清理舊副本。所有項(xiàng)目都切換完之后把原來(lái)的復(fù)制目錄刪掉同時(shí)在團(tuán)隊(duì)里公告這個(gè)模塊的源頭在某某倉(cāng)庫(kù)改代碼請(qǐng)?zhí)?PR。這一步很多人省了結(jié)果半年后又長(zhǎng)出新的副本。整個(gè)周期我給個(gè)參考三個(gè)項(xiàng)目、兩三個(gè)模塊的規(guī)模認(rèn)真做大概兩到三周。想一周搞定通常是在第三階段出問(wèn)題。6.2 日常維護(hù)里那幾條不能松的紀(jì)律機(jī)制選對(duì)了還得靠日常習(xí)慣兜底。以下幾條是我在實(shí)際項(xiàng)目里反復(fù)驗(yàn)證過(guò)的。提交信息帶上依賴變更說(shuō)明。父?jìng)}庫(kù)里那種同步子模塊的提交信息里要寫清楚從哪個(gè)版本到哪個(gè)版本改了哪些內(nèi)容。三個(gè)月后有人 bisect 找問(wèn)題時(shí)這條信息能救命。給子模塊指針變更單獨(dú)提交。不要把子模塊指針的變更和業(yè)務(wù)代碼混在同一個(gè)提交里。分開(kāi)之后回滾業(yè)務(wù)代碼不會(huì)誤傷依賴版本反之亦然。每次發(fā)版前跑一次全量同步檢查。針對(duì)子樹(shù)方案發(fā)版前確認(rèn)本地目錄和上游是不是一致的針對(duì)子模塊確認(rèn)所有指針是不是都已經(jīng)推到遠(yuǎn)端。這個(gè)檢查可以寫成腳本一行命令輸出所有子模塊的當(dāng)前提交和遠(yuǎn)端最新提交的差異。給 CI 加一條斷言。在流水線最開(kāi)始加一步檢查子模塊目錄是否非空或者檢查合并后的代碼里是否包含預(yù)期的版本標(biāo)記文件。這條斷言能在三十秒內(nèi)暴露大部分依賴?yán)?wèn)題比事后排查省太多時(shí)間。新成員文檔里寫清楚依賴?yán)〔襟E。不是寫請(qǐng)初始化子模塊而是給出可以直接復(fù)制的完整命令。文檔里那段命令我自己每季度會(huì)拿出來(lái)在一個(gè)全新環(huán)境里試一遍確認(rèn)還能用。如果非要在兩種機(jī)制里挑一個(gè)當(dāng)默認(rèn)我的傾向是能上包管理器就上包管理器不能上就優(yōu)先子樹(shù)只有在需要嚴(yán)格版本鎖定和依賴足夠穩(wěn)定的場(chǎng)景才用子模塊。這個(gè)排序是根據(jù)維護(hù)成本排的不是根據(jù)功能強(qiáng)弱排的。子模塊的機(jī)制本身很優(yōu)雅但它把復(fù)雜度轉(zhuǎn)嫁給了每一個(gè)使用倉(cāng)庫(kù)的人而子樹(shù)把復(fù)雜度集中在了少數(shù)幾次同步操作上——后者在團(tuán)隊(duì)協(xié)作里通常更容易被消化。