你的團(tuán)隊(duì)有47個(gè)倉庫共用同一套構(gòu)建腳本嗎？GitHub Actions用戶平均每個(gè)組織維護(hù)23份重復(fù)的YAML配置，而官方4年前就埋了解法。

這套解法叫Custom Actions（自定義動(dòng)作）。不是新功能，是大多數(shù)團(tuán)隊(duì)直到CI/CD復(fù)雜度爆炸才想起來的基礎(chǔ)設(shè)施。今天把三種技術(shù)路線、選型陷阱和發(fā)布流程一次說清。

Composite：不會(huì)JS也能造輪子

最被低估的類型。Composite Action（組合動(dòng)作）允許你把多個(gè)workflow步驟打包成一個(gè)可復(fù)用單元，零JavaScript代碼。

典型場(chǎng)景：每個(gè)Node項(xiàng)目都要重復(fù)「裝Node→選包管理器→配緩存→裝依賴→構(gòu)建」這五步。復(fù)制粘貼23次后，任何緩存策略調(diào)整都是災(zāi)難。

Composite的解法是把這五步變成一行調(diào)用：

```yaml name: 'Setup Node Project' inputs: node-version: default: '20' package-manager: default: 'npm' outputs: cache-hit: value: ${{ steps.cache.outputs.cache-hit }} runs: using: composite steps: - uses: actions/setup-node@v4 with: node-version: ${{ inputs.node-version }} # 條件分支處理pnpm/yarn/npm三種包管理器 # 動(dòng)態(tài)計(jì)算緩存目錄路徑 - uses: actions/cache@v4 with: path: ${{ steps.cache-dir.outputs.dir }} key: ${{ runner.os }}-${{ inputs.package-manager }}-${{ hashFiles('**/lockfile') }} ```

關(guān)鍵設(shè)計(jì)：inputs（輸入?yún)?shù)）和outputs（輸出值）讓這個(gè)動(dòng)作像函數(shù)一樣被調(diào)用。調(diào)用方只關(guān)心「給我Node環(huán)境」，不關(guān)心內(nèi)部是pnpm還是yarn。

限制也很明確：Composite不能跑后臺(tái)服務(wù)，不能跨runner執(zhí)行，復(fù)雜邏輯需要借助shell腳本。但對(duì)于「步驟復(fù)用」這個(gè)單一問題，它是維護(hù)成本最低的選擇。

JavaScript Action：需要跑在GitHub托管機(jī)上的邏輯

當(dāng)Composite的shell腳本變得難以維護(hù)，或者需要調(diào)用GitHub API、處理異步操作時(shí)，切到JavaScript Action（JavaScript動(dòng)作）。

技術(shù)棧固定：Node.js 20，@actions/core工具包，@actions/github獲取上下文。打包方式有兩種——

方案A：把node_modules全提交進(jìn)倉庫。簡(jiǎn)單，但倉庫體積膨脹。

方案B：用@vercel/ncc把依賴打包成單文件。推薦，但要多一步構(gòu)建流程。

一個(gè)常被忽略的細(xì)節(jié)：JavaScript Action在GitHub托管的runner（運(yùn)行器）上執(zhí)行，能直接操作runner的文件系統(tǒng)、環(huán)境變量和網(wǎng)絡(luò)。這是它和Docker Action的核心差異。

選型信號(hào)：如果你的邏輯需要「在runner環(huán)境里做點(diǎn)什么」，選JS；如果需要「帶一個(gè)完整環(huán)境去做點(diǎn)什么」，看下面。

Docker Action：環(huán)境隔離的終極手段

Docker Action（Docker動(dòng)作）把整個(gè)運(yùn)行時(shí)打包進(jìn)鏡像。適合兩種極端場(chǎng)景：依賴特定操作系統(tǒng)工具鏈（比如某個(gè)Linux發(fā)行版的原生庫），或者對(duì)環(huán)境隔離有強(qiáng)需求（比如跑不可信代碼）。

代價(jià)明顯：每次調(diào)用都要拉鏡像，冷啟動(dòng)慢。GitHub建議用預(yù)構(gòu)建鏡像而非Dockerfile現(xiàn)場(chǎng)構(gòu)建，能把啟動(dòng)時(shí)間從分鐘級(jí)壓到秒級(jí)。

三種類型對(duì)比表（決策用）：

| 維度 | Composite | JavaScript | Docker | |:---|:---|:---|:---| | 啟動(dòng)速度 | 即時(shí) | 秒級(jí) | 分鐘級(jí)（無緩存）| | 環(huán)境依賴 | 繼承runner | Node.js 20 | 任意 | | 適用場(chǎng)景 | 步驟復(fù)用 | 復(fù)雜邏輯+API調(diào)用 | 環(huán)境隔離+特殊工具鏈 | | 維護(hù)成本 | 最低 | 中等 | 最高 |

版本策略：v1標(biāo)簽背后的陷阱

發(fā)布到GitHub Marketplace（應(yīng)用市場(chǎng)）只是第一步。真正的坑在版本管理。

GitHub官方推薦「浮動(dòng)標(biāo)簽+固定提交」雙軌制：

? 用戶側(cè)寫`uses: your-action@v1`，享受自動(dòng)更新

? 維護(hù)側(cè)同時(shí)打`v1`標(biāo)簽和`v1.2.3`語義化標(biāo)簽，重大變更時(shí)把`v1`指向新版本

但這套機(jī)制有個(gè)反直覺的漏洞：標(biāo)簽是可變的。如果攻擊者劫持了你的倉庫，能把`v1`指向惡意提交。供應(yīng)鏈安全團(tuán)隊(duì)更推薦讓用戶鎖死SHA（提交哈希），代價(jià)是失去自動(dòng)更新。

折中方案：提供`v1`便利標(biāo)簽，同時(shí)在README用大號(hào)字體標(biāo)注「生產(chǎn)環(huán)境建議鎖定SHA」。

測(cè)試：本地能跑通才算完成

Actions的測(cè)試一直是痛點(diǎn)。官方?jīng)]給本地模擬器，社區(qū)方案有三類——

nektos/act：用Docker在本地跑GitHub Actions，最接近真實(shí)環(huán)境，但鏡像體積大、部分功能缺失。

@github/local-action：官方實(shí)驗(yàn)性工具，只支持JavaScript Action，調(diào)試體驗(yàn)尚可。

最務(wù)實(shí)的路線：把核心邏輯抽成純函數(shù)，用Jest/Vitest單元測(cè)試覆蓋；Action本體只做「參數(shù)解析+函數(shù)調(diào)用」的薄封裝。這樣即使沒法本地跑完整workflow，邏輯正確性也有保障。

一個(gè)來自GitHub工程師的實(shí)操建議：在Action倉庫里建`.github/workflows/test.yml`，用矩陣策略（matrix strategy）測(cè)試多平臺(tái)（ubuntu/windows/macos）和多版本組合。這比本地模擬更可靠，缺點(diǎn)是推送才能觸發(fā)。

發(fā)布前的檢查清單：action.yml元數(shù)據(jù)完整（name/description/inputs/outputs/runs）、README含完整調(diào)用示例、LICENSE文件存在（MIT最通用）、版本標(biāo)簽已打。Marketplace的審核是自動(dòng)的，但缺失任一項(xiàng)都會(huì)導(dǎo)致搜索排名靠后。

最后問一句：你們團(tuán)隊(duì)的CI/CD配置現(xiàn)在有多少份重復(fù)代碼？如果超過10份，Composite Action可能是最快見效的還債方案。