建標準化腳手架流水線)
t3code 這個名字真正定下來是因為那個下午我同時開著六個終端窗口在給部門里第六個 Node 服務做初始化。六個服務看起來長得都差不多實際上沒有兩個的配置完全一致ESLint 規(guī)則的版本差著兩個大版本、tsconfig 有的開了 strict、有的沒開、日志格式從 JSON 到純文本亂成一鍋粥。最諷刺的是我在第七個服務里又看到了三年前那批帶著過時依賴的模板代碼。就是那一刻我意識到我們?nèi)钡牟皇且粋€“新建文件夾”的腳本而是一套能把工程初始化這件事標準化、類型化、可驗證的流水線。t3code 就是在這個背景下出現(xiàn)的內(nèi)部工具。這個代號有兩層含義一是它堅持 TypeScript-first 的工程基線二是它把 template、transform、typecheck 三條原語作為整個工具的核心動作。如果你也在維護多個內(nèi)部項目或者正在糾結(jié)要不要自己寫一個腳手架這篇東西會記錄完整的架構(gòu)思路、核心實現(xiàn)細節(jié)以及從能用到好用之間必須踩過的那些坑。1. 為什么會有 t3code從復制粘貼式初始化到腳手架流水線1.1 復制粘貼式初始化的隱性成本復制粘貼初始化項目這件事短期看起來效率極高。從老服務里把 package.json、tsconfig.json、eslint.config.js 拖過來改一改包名馬上就能跑起來。但問題出在“改一改”這三個字上每復制一次總會有幾個字段被留在上一個項目的語境里。比如 private、name、依賴版本和腳本路徑這些東西在只有一個服務的時候都是對的一旦多出六七個服務差異就開始滾雪球。我說一個真實觀察團隊里有三個服務都號稱“嚴格遵守 ESLint 規(guī)則”但它們的 eslint 配置一個是.eslintrc風格、一個是eslint.config.js風格還有一個直接在 package.json 里裸寫 rules。最麻煩的是每個服務對應的 rule 版本都不一樣同一段代碼在這個倉庫報警、在那個倉庫不報。新成員入職之后根本不知道該以哪個倉庫為基線最后只能以自己入職時看到的那個為準這其實就是隱性技術(shù)債的開端。這類債務不會出現(xiàn)在監(jiān)控指標里但會體現(xiàn)在每次升級依賴、每次統(tǒng)一日志格式、每次遷移構(gòu)建工具的時候。你每多做一次“把 A 服務的配置同步到 B 服務”的操作就是在償還一次利息。t3code 出現(xiàn)之前我和團隊已經(jīng)這么還了兩年利息。1.2 t3code 的定位template、transform、typecheck 三條原語t3code 不打算做一個無所不包的生成器。它的核心定位是三個動作的流水線template模板是事實的來源所有標準配置只維護一份放在倉庫的 templates 目錄里。transform生成時必須允許插值、條件片段、文件級轉(zhuǎn)換而不是簡單的字符串 copy。typecheck生成之后的產(chǎn)物必須通過一次真實的類型檢查把錯誤擋在提交代碼之前。三條原語連起來就是一條完整的鏈路讀模板、套變量、寫文件、跑檢查。這是我后來覺得 t3code 這個名字貼切的原因t3 恰好同時是 TypeScript-first 的簡稱也是這三條原語的首字母集合。整個工具的走勢也證明了這個劃分是對的后續(xù)新增的功能幾乎都能歸到這三條原語之一。1.3 為什么不直接白嫖社區(qū)腳手架一定會有人問社區(qū)的 create-t3-app、create-next-app 之類的腳手架那么成熟為什么不直接用。原因是它們解決的是“創(chuàng)建一個標準的社區(qū)項目”的問題而內(nèi)部開發(fā)需要的是“創(chuàng)建一個符合團隊私有規(guī)范的項目”的問題。團隊的私有規(guī)范包括內(nèi)網(wǎng)鏡像地址、統(tǒng)一的日志攔截器、特定的 CI 流程這些沒法通過參數(shù)化一個社區(qū)腳手架實現(xiàn)而且社區(qū)腳手架的升級節(jié)奏我們也控制不了。如果只是把社區(qū)模板 fork 一份維護成本也扛不住上游每次大更新都要同步fork 之間還會出現(xiàn)分叉。t3code 從一開始就設計成面向自己的模板體系社區(qū)工具可以補位解決“項目初始化后的深層配置”但它不應該成為唯一依靠。2. 整體架構(gòu)設計一個微型模板引擎加一個命令調(diào)度器2.1 倉庫目錄結(jié)構(gòu)t3code 本身的倉庫結(jié)構(gòu)沒有用 monorepo因為一個 CLI 工具在相當長一段時間里都沒有拆分包的訴求。保持簡單反而更容易維護。實際目錄如下t3code/ ├── bin/ │ └── t3code.ts # CLI 入口負責解析命令和參數(shù) ├── src/ │ ├── commands/ # init/add/doctor/upgrade 四個命令 │ │ ├── init.ts │ │ ├── add.ts │ │ ├── doctor.ts │ │ └── upgrade.ts │ ├── engine/ # 模板渲染引擎 │ │ ├── render.ts │ │ ├── parse.ts │ │ └── ignore.ts │ ├── schema/ # zod schema 與類型導出 │ │ └── answers.ts │ └── utils/ # 路徑、日志、進程工具 ├── templates/ │ ├── service-api/ │ │ ├── template.json │ │ └── files/... │ └── lib/ │ ├── template.json │ └── files/... ├── tests/ │ ├── fixtures/ # 測試專用的最小模板 │ └── render.test.ts ├── package.json └── tsconfig.json命令層用 commander 解析交互層用 prompts。為什么要這兩個而不是自己手寫參數(shù)解析因為參數(shù)解析的問題是已經(jīng)被解決過的問題我不需要在引號、轉(zhuǎn)義、缺省值這些細節(jié)上重新犯錯。2.2 命令層init、add、doctor、upgrade四個命令對應四個高頻場景init用指定模板新建項目。最核心的路徑。add向已有項目追加模板片段比如給老服務補一個 eslint 配置。doctor檢查當前環(huán)境、模板完整性、已有項目和模板的漂移程度。upgrade升級 t3code 自身以及模板緩存。命令拆分的原則是初始化、增量變更、體檢、更新這四件事的失敗模式完全不同。init 失敗可以扔掉重來add 失敗卻可能破壞一個正在運行的項目。把命令拆開之后每一段的錯誤處理都可以更專注。2.3 模板注冊表與元數(shù)據(jù)每個模板目錄下必須有一個 template.json它是對模板自身的描述。這個文件我堅持用普通 JSON 而不是 JS/TS 文件理由是元數(shù)據(jù)必須可以被任何語言解析將來如果要做一個 Web 端的模板預覽JSON 是最沒有成本的格式。template.json 的字段設計如下{ name: service-api, version: 1.2.0, description: 標準 API 服務的初始化模板, vars: { projectName: { type: string, required: true }, strict: { type: boolean, default: true }, nodeVersion: { type: string, enum: [18, 20] } }, ignore: [files/node_modules, files/dist] }vars 字段其實就是變量的聲明。它和后面 zod schema 之間是一一對應的關(guān)系模板元數(shù)據(jù)描述“有哪些變量、大概是什么類型”zod schema 負責在運行時真正執(zhí)行校驗。兩者分開的理由會在第四章展開。3. 模板渲染硬核細節(jié)目錄遍歷、插值引擎與文件保護3.1 渲染引擎的選型與取舍在決定渲染引擎之前我把主流的方案過了一遍。mustache 語法簡單、心智負擔低但邏輯能力偏弱做條件判斷和循環(huán)還可以一旦要在渲染期動態(tài)拼路徑、動態(tài)決定哪幾個文件參與輸出就會很吃力。handlebars 能力強幾乎什么都能干但它把太多東西放進了模板模板會變得越來越不像“數(shù)據(jù)”更像一份可執(zhí)行代碼這和維護性相悖。最終我選擇手寫一個小型插值引擎只支持三種語法變量插值{{ var }}、條件塊{{#if var}}...{{/if}}、循環(huán)塊{{#each list}}...{{/each}}。這三個語法覆蓋了腳手架 95% 的需求剩下的用 transform 原語去做也就是在模板里寫一個 hook渲染完成后對指定文件做一次程序化修改。把“模板表達能力不夠”的問題從模板層抽到代碼層是我在這個項目里做過的最重要的取舍之一。3.2 目錄遍歷與文件屬性保持渲染一個目錄表面上是遞歸讀文件、寫文件實際操作時要處理不少細節(jié)。這里的 fs 是node:fs/promises的命名空間導入。renderDirectory 核心邏輯大概是這樣import { promises as fs } from node:fs; export async function renderDirectory( srcDir: string, targetDir: string, context: RenderContext ): Promisevoid { const entries await fs.readdir(srcDir, { withFileTypes: true }); for (const entry of entries) { const srcPath path.join(srcDir, entry.name); const relative path.relative(srcDir, srcPath); if (isIgnored(relative, context.ignore)) continue; if (entry.isDirectory()) { await renderDirectory(srcPath, path.join(targetDir, relative), context); } else { await renderFile(srcPath, path.join(targetDir, relative), context); } } }看起來平淡無奇真正的坑在于文件權(quán)限。很多模板里會放一個 deploy.sh它需要 755 權(quán)限。如果渲染邏輯只是 readFile 再 writeFile權(quán)限直接丟了。解決方法是先 stat 一下源文件的 mode寫入后 chmod 恢復。這個小細節(jié)我第一次完全沒考慮直到在 Linux 上生成的項目里跑 deploy.sh 出現(xiàn) Permission denied 才意識到。另一個細節(jié)是輸出目錄的清理策略。init 到一個非空目錄時我默認不覆蓋已存在的文件而是把沖突文件列表打印出來讓用戶選擇備份或跳過。這個做法比直接覆蓋溫和也比詢問“是否刪除整個目錄”安全。3.3 二進制文件與 dotfile 的守護這是模板渲染里最容易被忽略的一關(guān)。模板目錄里可能會有 .png、.ico、.woff2 之類的二進制資源如果都按文本讀進來再 UTF-8 編碼寫出去文件直接損壞。我的檢測策略是讀取文件頭部 512 字節(jié)如果發(fā)現(xiàn)空字節(jié)就判定為二進制function isBinary(buf: Buffer): boolean { return buf.subarray(0, 512).indexOf(0) ! -1; }這個方法簡單可靠文本文件在頭部出現(xiàn)空字節(jié)的概率幾乎為零。二進制文件直接走 stream copy不渲染。dotfile 的問題更隱蔽。模板里的.gitignore.tpl是一個必須渲染的文件因為它里面有{{ projectName }}這樣的變量但渲染完成后它要改名為.gitignore。如果模板里直接放.gitignoreGit 會試圖跟蹤它模板倉庫的版本控制就會變得混亂。我的約定是所有需要改名且以點開頭的文件統(tǒng)一加.tpl后綴渲染時剝掉后綴。3.4 從渲染環(huán)境到輸出目錄一次完整的渲染管線把上面這些串起來一次 init 的實際流程是解析參數(shù)和交互回答得到經(jīng)過 zod 校驗的變量對象掃描模板目錄按 ignore 規(guī)則過濾遞歸遍歷每個文件判斷 binary 還是 texttext 文件按擴展名和內(nèi)容特征決定是否插值最后統(tǒng)一刷新文件權(quán)限剝掉 .tpl 后綴生成 summary。summary 會列出生成的文件列表和后續(xù)還需要手動完成的步驟很多人覺得這個輸出多余但它其實是在給使用者一個明確的“下一步”錨點。4. 把變量和類型安全焊在一起zod schema 驅(qū)動的配置鏈路4.1 變量從哪來交互問答、命令行參數(shù)、配置文件模板需要的數(shù)據(jù)無非三個來源命令行參數(shù)、交互式問答、放在項目里的配置文件。t3code 的處理順序是先用命令行參數(shù)提供默認值再交給交互層補齊缺失字段最后把結(jié)果交給 zod 做整體校驗。為什么交互層不能直接跳過因為絕大多數(shù)使用者并不記得模板有哪些字段需要填交互一是補齊信息二是順便起到“引導使用者理解模板”的作用。交互問答是動態(tài)生成的。template.json 里的 vars 聲明決定 prompts 要展示哪些問題如果命令行參數(shù)已經(jīng)給出某個值對應的問題就不出現(xiàn)。這樣既支持t3code init service-api --projectName my-api這樣的無交互用法也支持什么都不帶直接回車。4.2 zod schema 作為唯一事實來源這一步是 t3code 和普通“復制文件工具”拉開差距的地方。template.json 里的 vars 只是聲明真正執(zhí)行校驗的是代碼里的 zod schemaimport { z } from zod; export const serviceApiSchema z.object({ projectName: z .string() .regex(/^[a-z][a-z0-9-]*$/, 項目名只能包含小寫字母、數(shù)字和短橫線), strict: z.boolean().default(true), nodeVersion: z.enum([18, 20]).default(20), }); export type ServiceApiAnswers z.infertypeof serviceApiSchema;把 schema 從模板元數(shù)據(jù)里抽出來放進代碼一開始看起來像重復勞動實際是必要的。模板元數(shù)據(jù)要被渲染引擎讀取它不能依賴 TypeScript 的運行時schema 卻需要強類型推導它必須活在 TS 的世界里。兩者之間用一份變量聲明同步是可行的我用的方法是寫一個測試用例遍歷所有模板把 template.json 里的 vars 和對應的 zod schema 逐個比對字段名和類型不一致直接報錯。4.3 類型安全的傳遞鏈路與模板內(nèi)聯(lián)類型校驗通過之后變量對象會在整個渲染過程中以ServiceApiAnswers類型傳遞這意味著模板里寫context.projectName時編輯器有自動補全寫錯字段名在編譯期就會暴露。對模板作者來說這是體驗上的質(zhì)變以前是在生成后才能發(fā)現(xiàn)變量名拼錯現(xiàn)在是寫模板的時候就發(fā)現(xiàn)了。更進一步的類型安全體現(xiàn)在模板內(nèi)容上。例如 Node 版本這個變量在模板里會生成一個.nvmrc文件內(nèi)容是v20。如果模板只寫{{ nodeVersion }}這個值的合法性完全依賴渲染前的校驗一旦校驗邏輯出 bug 就可能生成一個不存在的 Node 版本。我傾向于在模板里額外做一道約束用條件塊判斷 nodeVersion 是 18 還是 20分別生成對應內(nèi)容寧可讓模板多兩行也要把非法值擋在文件系統(tǒng)之外。5. typecheck 閘門生成之后的第一次體檢與常見失敗5.1 為什么腳手架必須內(nèi)置類型校驗t3code 生成的項目至少要達到一個底線安裝依賴之后tsc --noEmit必須能過。如果連這個底線都保證不了“腳手架”就退化成“文件復制器”生成的東西能不能跑完全看運氣。把 typecheck 放進腳手架流程等于把所有模板的合法性檢查前置任何模板改動都必須先讓所有基于它的項目通過類型檢查才能合入模板倉庫。這個閘門還有一個額外收益它逼著模板作者把依賴版本寫死。如果模板里typescript寫的是寬松范圍比如^5.4.0今天生成的項目的類型結(jié)果可能明天就變了typecheck 就失去了確定性。5.2 實現(xiàn)細節(jié)調(diào)用本地 tsc 而不是全局命令執(zhí)行類型檢查時最容易踩的坑是調(diào)全局 tsc。全局安裝的 TypeScript 版本和項目本地版本可能差很多用全局 tsc 校驗本地項目完全沒有代表性。正確做法是在生成的項目目錄里解析本地 typescriptimport { execFile } from node:child_process; import { promisify } from node:util; import { createRequire } from node:module; import path from node:path; const require createRequire(path.resolve(targetDir, package.json)); const tscBin require.resolve(typescript/bin/tsc); const execFileAsync promisify(execFile); const { stdout, stderr } await execFileAsync( process.execPath, [tscBin, --noEmit, --pretty, false], { cwd: targetDir } ); const output stdout stderr; if (output.trim()) { reportTypeErrors(output, targetDir); }為什么用process.execPath跑 tsc因為 bin 腳本本質(zhì)上是一個 Node 文件直接用 node 執(zhí)行它就是最穩(wěn)的方式也可以避免一些系統(tǒng)上 bin 鏈接配置的問題。check 之后如果輸出不為空把錯誤按文件分組輸出并給出常見的修復提示。我刻意沒有做“自動修復”因為自動修改生成的代碼既危險又不可控tsc 的錯誤信息已經(jīng)足夠人類工程師定位問題腳手架的職責是盡早暴露問題而不是替工程師決定怎么改。5.3 常見失敗與自動修復嘗試實際跑過那么多模板之后typecheck 失敗集中在幾類strict 模式下對可能為 null 的值做運算、某個 import 的路徑大小寫寫錯、新版本 TypeScript 對某些 API 的默認類型收窄。前兩類是模板本身的問題改模板就好。第三類是依賴抖動這部分到第六章詳細說它背后的根因不是模板錯了而是依賴版本沒有鎖住。對于第一類失敗一個可用的緩解策略是模板里統(tǒng)一使用satisfies和顯式類型注解讓潛在問題在模板編譯階段就暴露。這不能根治問題但它能把“生成一個壞項目”的概率壓到更低。6. 從能用到好用之間隔著這些坑6.1 Windows 路徑與 CRLF一次跨平臺故障的完整排查t3code 早期基本只有我在用跑在 macOS 上。直到一個 Windows 同事試用后發(fā)來截圖生成的配置文件里路徑變成了D:\repo\service-api\src\config然后.env文件每行結(jié)尾帶著奇怪的^M。排查的第一步是復現(xiàn)。我在 Windows 虛擬機上跑了一遍同樣的 init確認問題穩(wěn)定存在。第二步是定位范圍。我分別測試了“從模板讀取文件后直接寫入”“中間經(jīng)過插值引擎”“插值且變量包含路徑”三種場景最終確認問題出在插值階段從命令行傳入的 Windows 路徑會帶反斜杠模板里用{{ projectDir }}渲染后反斜杠在部分上下文里被解釋成轉(zhuǎn)義符產(chǎn)生了亂碼。至于^M則是模板文件本身以 CRLF 保存讀取后我按 UTF-8 原樣寫入Windows 環(huán)境下 Git 又自動加了 CRLF導致雙重轉(zhuǎn)換。修復方案分兩層插值引擎對傳入的字符串統(tǒng)一做一次路徑規(guī)范化把反斜杠轉(zhuǎn)成正斜杠所有文本文件寫入前統(tǒng)一把換行符規(guī)范化為\n并借助.gitattributes里的text eollf約定把模板倉庫的換行符鎖死。這之后 Windows 上生成的代碼行為才完全和 macOS 一致。這個坑教會我的不是“怎么處理路徑”而是“跨平臺工具必須讓核心渲染管線與操作系統(tǒng)無關(guān)”。路徑是操作系統(tǒng)的方言方言應該在邊界處被翻譯而不是在管道里到處穿。6.2 占位符被渲染函數(shù)誤傷變量命名引發(fā)的連鎖反應第二個坑更難發(fā)現(xiàn)。有一天我用 t3code 生成一個內(nèi)部管理后臺模板里有一行 Vue 代碼span{{ userName }}/span。渲染完一看userName 變成了空字符串。我第一反應是變量沒傳進去排查了很久才意識到問題根本不是變量缺失而是自己的插值引擎把模板里本來就存在的 Vue 插值語法{{ userName }}當成 t3code 的變量占位符執(zhí)行了替換而渲染環(huán)境里根本沒有 userName 這個變量于是它被替換成了空。這個問題的本質(zhì)是占位符定界符沖突。任何一門模板語言都可能引入{{ }}語法你的腳手架只要生成 Vue、Angular、Handlebars 相關(guān)的代碼遲早會撞上。我的解決方案是給插值引擎增加一層轉(zhuǎn)義語義\{{表示字面量{{渲染時保留原樣同時把渲染結(jié)果標記為“已渲染”禁止對已渲染的文本再次執(zhí)行插值。這條規(guī)則雖然簡單但當時是在踩過坑之后才補上的。如果讓我重新設計一次我會在一開始就把定界符改成不那么容易沖突的[[ ]]而不是沿用 mustache 風格的{{ }}。兼容社區(qū)習慣帶來了一點便利卻換來了和下游模板語法長期共存的風險這個賬其實是不劃算的。6.3 依賴抖動本地的綠燈CI 的紅燈typecheck 集成之后有一段時間我在本地怎么跑都是綠的CI 卻時不時飄紅。最開始以為又是 Windows 的問題直到我在 CI 日志里看到typescript每次解析到的版本都不一樣才反應過來模板里的依賴聲明寫的是^5.4.0這類范圍版本每次 install 都會重新解析最新小版本TypeScript 的小版本升級偶爾會帶來更嚴格的類型檢查于是同一個模板今天能過、明天就可能不能過。排查和修復的過程不復雜模板里所有關(guān)鍵依賴改成精確版本或~范圍提交 lockfileCI 使用pnpm install --frozen-lockfile。真正值得反思的是為什么這個問題拖了這么久才暴露因為我給 t3code 的測試用例都是在本地跑本地 node_modules 早就鎖死了版本根本不會重現(xiàn)“全新環(huán)境安裝”的場景。后來我在 CI 上加了一個每晚執(zhí)行的“從零生成并 typecheck”的任務才真正把這類抖動擋在合并之前。6.4 測試策略用 fixture 而不是拿真實業(yè)務當小白鼠t3code 的測試大概可以分成三層。第一層是渲染引擎的單元測試覆蓋插值、條件、循環(huán)、轉(zhuǎn)義、二進制保護這些純函數(shù)。第二層是命令層的集成測試在臨時目錄里跑完整的 init然后對照快照檢查生成文件的路徑、內(nèi)容和權(quán)限。第三層是跨平臺矩陣在 GitHub Actions 的 ubuntu、macos、windows 三個 runner 上跑同一套測試用例。fixture 模板和真實模板必須分開。真實模板會隨業(yè)務演進拿來當測試基線會讓測試跟著模板一起變最終退化成“確認現(xiàn)狀沒變”。fixture 模板小而穩(wěn)定只服務測試這樣引擎的測試結(jié)果才可靠。也是因為有了這一層 fixture后面改渲染引擎時才敢做重構(gòu)。7. 從個人工具到團隊基建t3code 的成長路線7.1 離線緩存與自動升級t3code 作為內(nèi)部工具一開始沒有考慮離線環(huán)境。但內(nèi)網(wǎng)開發(fā)環(huán)境經(jīng)常在一個隔離網(wǎng)絡里npm install 需要走內(nèi)部鏡像。為此我在模板目錄里增加了一個 lock 文件記錄模板期望的鏡像地址和依賴版本組合init 之后自動改寫 package.json 里的 registry 配置。這一步看似不起眼實際上讓內(nèi)網(wǎng)同事的初始化時間從十幾分鐘降到幾十秒。自動升級用的是一個簡單的版本檢查每次 init 前請求一次模板注冊表接口把本地模板版本和遠程版本做對比有新版就提示。我把這個檢查的開關(guān)默認設為關(guān)閉原因是內(nèi)網(wǎng)環(huán)境不是都有公網(wǎng)出口把一個可選的網(wǎng)絡請求做成強制會得罪所有人。7.2 自己吃自己的狗糧Dogfooding 對腳手架工具的驗證效果比任何測試都強。我把 t3code 本身也納入模板管理每次從模板生成一個最小 CLI 項目然后在這個項目上繼續(xù)加功能。這個循環(huán)能強制發(fā)現(xiàn)模板里的所有問題如果一個模板連它自己的作者都無法流暢使用那說明模板里還有未消化的復雜度。7.3 下一步從代碼工程到代碼規(guī)范如果 t3code 繼續(xù)演進我期望的方向是 AST 級改造。目前的 transform 原語還是基于字符串替換它能做 90% 的工作但對“統(tǒng)一 import 順序”“強制導出一個入口函數(shù)”這類結(jié)構(gòu)化改造很吃力。AST 級 transform 會讓模板深入很多但復雜度也會顯著上升?，F(xiàn)階段我更傾向于保持三條原語的簡單性把復雜模板拆成分層文件而不是把一個模板做成一個萬能機器。最后分享一個我在實際維護中一直堅持的小習慣每次給 t3code 增加一個新能力先要求它“生成后的項目必須能在兩分鐘內(nèi)被新同事看懂”做不到就把能力砍掉。腳手架不是給自己秀操作的地方它服務的對象永遠是下一個打開代碼倉庫的人。這個標準聽起來模糊但它幫我擋掉過不少華而不實的功能提案。 從復制粘貼到類型安全：t3code 如何構(gòu)建標準化腳手架流水線
t3code 這個名字真正定下來是因為那個下午我同時開著六個終端窗口在給部門里第六個 Node 服務做初始化。六個服務看起來長得都差不多實際上沒有兩個的配置完全一致ESLint 規(guī)則的版本差著兩個大版本、tsconfig 有的開了 strict、有的沒開、日志格式從 JSON 到純文本亂成一鍋粥。最諷刺的是我在第七個服務里又看到了三年前那批帶著過時依賴的模板代碼。就是那一刻我意識到我們?nèi)钡牟皇且粋€“新建文件夾”的腳本而是一套能把工程初始化這件事標準化、類型化、可驗證的流水線。t3code 就是在這個背景下出現(xiàn)的內(nèi)部工具。這個代號有兩層含義一是它堅持 TypeScript-first 的工程基線二是它把 template、transform、typecheck 三條原語作為整個工具的核心動作。如果你也在維護多個內(nèi)部項目或者正在糾結(jié)要不要自己寫一個腳手架這篇東西會記錄完整的架構(gòu)思路、核心實現(xiàn)細節(jié)以及從能用到好用之間必須踩過的那些坑。1. 為什么會有 t3code從復制粘貼式初始化到腳手架流水線1.1 復制粘貼式初始化的隱性成本復制粘貼初始化項目這件事短期看起來效率極高。從老服務里把 package.json、tsconfig.json、eslint.config.js 拖過來改一改包名馬上就能跑起來。但問題出在“改一改”這三個字上每復制一次總會有幾個字段被留在上一個項目的語境里。比如 private、name、依賴版本和腳本路徑這些東西在只有一個服務的時候都是對的一旦多出六七個服務差異就開始滾雪球。我說一個真實觀察團隊里有三個服務都號稱“嚴格遵守 ESLint 規(guī)則”但它們的 eslint 配置一個是.eslintrc風格、一個是eslint.config.js風格還有一個直接在 package.json 里裸寫 rules。最麻煩的是每個服務對應的 rule 版本都不一樣同一段代碼在這個倉庫報警、在那個倉庫不報。新成員入職之后根本不知道該以哪個倉庫為基線最后只能以自己入職時看到的那個為準這其實就是隱性技術(shù)債的開端。這類債務不會出現(xiàn)在監(jiān)控指標里但會體現(xiàn)在每次升級依賴、每次統(tǒng)一日志格式、每次遷移構(gòu)建工具的時候。你每多做一次“把 A 服務的配置同步到 B 服務”的操作就是在償還一次利息。t3code 出現(xiàn)之前我和團隊已經(jīng)這么還了兩年利息。1.2 t3code 的定位template、transform、typecheck 三條原語t3code 不打算做一個無所不包的生成器。它的核心定位是三個動作的流水線template模板是事實的來源所有標準配置只維護一份放在倉庫的 templates 目錄里。transform生成時必須允許插值、條件片段、文件級轉(zhuǎn)換而不是簡單的字符串 copy。typecheck生成之后的產(chǎn)物必須通過一次真實的類型檢查把錯誤擋在提交代碼之前。三條原語連起來就是一條完整的鏈路讀模板、套變量、寫文件、跑檢查。這是我后來覺得 t3code 這個名字貼切的原因t3 恰好同時是 TypeScript-first 的簡稱也是這三條原語的首字母集合。整個工具的走勢也證明了這個劃分是對的后續(xù)新增的功能幾乎都能歸到這三條原語之一。1.3 為什么不直接白嫖社區(qū)腳手架一定會有人問社區(qū)的 create-t3-app、create-next-app 之類的腳手架那么成熟為什么不直接用。原因是它們解決的是“創(chuàng)建一個標準的社區(qū)項目”的問題而內(nèi)部開發(fā)需要的是“創(chuàng)建一個符合團隊私有規(guī)范的項目”的問題。團隊的私有規(guī)范包括內(nèi)網(wǎng)鏡像地址、統(tǒng)一的日志攔截器、特定的 CI 流程這些沒法通過參數(shù)化一個社區(qū)腳手架實現(xiàn)而且社區(qū)腳手架的升級節(jié)奏我們也控制不了。如果只是把社區(qū)模板 fork 一份維護成本也扛不住上游每次大更新都要同步fork 之間還會出現(xiàn)分叉。t3code 從一開始就設計成面向自己的模板體系社區(qū)工具可以補位解決“項目初始化后的深層配置”但它不應該成為唯一依靠。2. 整體架構(gòu)設計一個微型模板引擎加一個命令調(diào)度器2.1 倉庫目錄結(jié)構(gòu)t3code 本身的倉庫結(jié)構(gòu)沒有用 monorepo因為一個 CLI 工具在相當長一段時間里都沒有拆分包的訴求。保持簡單反而更容易維護。實際目錄如下t3code/ ├── bin/ │ └── t3code.ts # CLI 入口負責解析命令和參數(shù) ├── src/ │ ├── commands/ # init/add/doctor/upgrade 四個命令 │ │ ├── init.ts │ │ ├── add.ts │ │ ├── doctor.ts │ │ └── upgrade.ts │ ├── engine/ # 模板渲染引擎 │ │ ├── render.ts │ │ ├── parse.ts │ │ └── ignore.ts │ ├── schema/ # zod schema 與類型導出 │ │ └── answers.ts │ └── utils/ # 路徑、日志、進程工具 ├── templates/ │ ├── service-api/ │ │ ├── template.json │ │ └── files/... │ └── lib/ │ ├── template.json │ └── files/... ├── tests/ │ ├── fixtures/ # 測試專用的最小模板 │ └── render.test.ts ├── package.json └── tsconfig.json命令層用 commander 解析交互層用 prompts。為什么要這兩個而不是自己手寫參數(shù)解析因為參數(shù)解析的問題是已經(jīng)被解決過的問題我不需要在引號、轉(zhuǎn)義、缺省值這些細節(jié)上重新犯錯。2.2 命令層init、add、doctor、upgrade四個命令對應四個高頻場景init用指定模板新建項目。最核心的路徑。add向已有項目追加模板片段比如給老服務補一個 eslint 配置。doctor檢查當前環(huán)境、模板完整性、已有項目和模板的漂移程度。upgrade升級 t3code 自身以及模板緩存。命令拆分的原則是初始化、增量變更、體檢、更新這四件事的失敗模式完全不同。init 失敗可以扔掉重來add 失敗卻可能破壞一個正在運行的項目。把命令拆開之后每一段的錯誤處理都可以更專注。2.3 模板注冊表與元數(shù)據(jù)每個模板目錄下必須有一個 template.json它是對模板自身的描述。這個文件我堅持用普通 JSON 而不是 JS/TS 文件理由是元數(shù)據(jù)必須可以被任何語言解析將來如果要做一個 Web 端的模板預覽JSON 是最沒有成本的格式。template.json 的字段設計如下{ name: service-api, version: 1.2.0, description: 標準 API 服務的初始化模板, vars: { projectName: { type: string, required: true }, strict: { type: boolean, default: true }, nodeVersion: { type: string, enum: [18, 20] } }, ignore: [files/node_modules, files/dist] }vars 字段其實就是變量的聲明。它和后面 zod schema 之間是一一對應的關(guān)系模板元數(shù)據(jù)描述“有哪些變量、大概是什么類型”zod schema 負責在運行時真正執(zhí)行校驗。兩者分開的理由會在第四章展開。3. 模板渲染硬核細節(jié)目錄遍歷、插值引擎與文件保護3.1 渲染引擎的選型與取舍在決定渲染引擎之前我把主流的方案過了一遍。mustache 語法簡單、心智負擔低但邏輯能力偏弱做條件判斷和循環(huán)還可以一旦要在渲染期動態(tài)拼路徑、動態(tài)決定哪幾個文件參與輸出就會很吃力。handlebars 能力強幾乎什么都能干但它把太多東西放進了模板模板會變得越來越不像“數(shù)據(jù)”更像一份可執(zhí)行代碼這和維護性相悖。最終我選擇手寫一個小型插值引擎只支持三種語法變量插值{{ var }}、條件塊{{#if var}}...{{/if}}、循環(huán)塊{{#each list}}...{{/each}}。這三個語法覆蓋了腳手架 95% 的需求剩下的用 transform 原語去做也就是在模板里寫一個 hook渲染完成后對指定文件做一次程序化修改。把“模板表達能力不夠”的問題從模板層抽到代碼層是我在這個項目里做過的最重要的取舍之一。3.2 目錄遍歷與文件屬性保持渲染一個目錄表面上是遞歸讀文件、寫文件實際操作時要處理不少細節(jié)。這里的 fs 是node:fs/promises的命名空間導入。renderDirectory 核心邏輯大概是這樣import { promises as fs } from node:fs; export async function renderDirectory( srcDir: string, targetDir: string, context: RenderContext ): Promisevoid { const entries await fs.readdir(srcDir, { withFileTypes: true }); for (const entry of entries) { const srcPath path.join(srcDir, entry.name); const relative path.relative(srcDir, srcPath); if (isIgnored(relative, context.ignore)) continue; if (entry.isDirectory()) { await renderDirectory(srcPath, path.join(targetDir, relative), context); } else { await renderFile(srcPath, path.join(targetDir, relative), context); } } }看起來平淡無奇真正的坑在于文件權(quán)限。很多模板里會放一個 deploy.sh它需要 755 權(quán)限。如果渲染邏輯只是 readFile 再 writeFile權(quán)限直接丟了。解決方法是先 stat 一下源文件的 mode寫入后 chmod 恢復。這個小細節(jié)我第一次完全沒考慮直到在 Linux 上生成的項目里跑 deploy.sh 出現(xiàn) Permission denied 才意識到。另一個細節(jié)是輸出目錄的清理策略。init 到一個非空目錄時我默認不覆蓋已存在的文件而是把沖突文件列表打印出來讓用戶選擇備份或跳過。這個做法比直接覆蓋溫和也比詢問“是否刪除整個目錄”安全。3.3 二進制文件與 dotfile 的守護這是模板渲染里最容易被忽略的一關(guān)。模板目錄里可能會有 .png、.ico、.woff2 之類的二進制資源如果都按文本讀進來再 UTF-8 編碼寫出去文件直接損壞。我的檢測策略是讀取文件頭部 512 字節(jié)如果發(fā)現(xiàn)空字節(jié)就判定為二進制function isBinary(buf: Buffer): boolean { return buf.subarray(0, 512).indexOf(0) ! -1; }這個方法簡單可靠文本文件在頭部出現(xiàn)空字節(jié)的概率幾乎為零。二進制文件直接走 stream copy不渲染。dotfile 的問題更隱蔽。模板里的.gitignore.tpl是一個必須渲染的文件因為它里面有{{ projectName }}這樣的變量但渲染完成后它要改名為.gitignore。如果模板里直接放.gitignoreGit 會試圖跟蹤它模板倉庫的版本控制就會變得混亂。我的約定是所有需要改名且以點開頭的文件統(tǒng)一加.tpl后綴渲染時剝掉后綴。3.4 從渲染環(huán)境到輸出目錄一次完整的渲染管線把上面這些串起來一次 init 的實際流程是解析參數(shù)和交互回答得到經(jīng)過 zod 校驗的變量對象掃描模板目錄按 ignore 規(guī)則過濾遞歸遍歷每個文件判斷 binary 還是 texttext 文件按擴展名和內(nèi)容特征決定是否插值最后統(tǒng)一刷新文件權(quán)限剝掉 .tpl 后綴生成 summary。summary 會列出生成的文件列表和后續(xù)還需要手動完成的步驟很多人覺得這個輸出多余但它其實是在給使用者一個明確的“下一步”錨點。4. 把變量和類型安全焊在一起zod schema 驅(qū)動的配置鏈路4.1 變量從哪來交互問答、命令行參數(shù)、配置文件模板需要的數(shù)據(jù)無非三個來源命令行參數(shù)、交互式問答、放在項目里的配置文件。t3code 的處理順序是先用命令行參數(shù)提供默認值再交給交互層補齊缺失字段最后把結(jié)果交給 zod 做整體校驗。為什么交互層不能直接跳過因為絕大多數(shù)使用者并不記得模板有哪些字段需要填交互一是補齊信息二是順便起到“引導使用者理解模板”的作用。交互問答是動態(tài)生成的。template.json 里的 vars 聲明決定 prompts 要展示哪些問題如果命令行參數(shù)已經(jīng)給出某個值對應的問題就不出現(xiàn)。這樣既支持t3code init service-api --projectName my-api這樣的無交互用法也支持什么都不帶直接回車。4.2 zod schema 作為唯一事實來源這一步是 t3code 和普通“復制文件工具”拉開差距的地方。template.json 里的 vars 只是聲明真正執(zhí)行校驗的是代碼里的 zod schemaimport { z } from zod; export const serviceApiSchema z.object({ projectName: z .string() .regex(/^[a-z][a-z0-9-]*$/, 項目名只能包含小寫字母、數(shù)字和短橫線), strict: z.boolean().default(true), nodeVersion: z.enum([18, 20]).default(20), }); export type ServiceApiAnswers z.infertypeof serviceApiSchema;把 schema 從模板元數(shù)據(jù)里抽出來放進代碼一開始看起來像重復勞動實際是必要的。模板元數(shù)據(jù)要被渲染引擎讀取它不能依賴 TypeScript 的運行時schema 卻需要強類型推導它必須活在 TS 的世界里。兩者之間用一份變量聲明同步是可行的我用的方法是寫一個測試用例遍歷所有模板把 template.json 里的 vars 和對應的 zod schema 逐個比對字段名和類型不一致直接報錯。4.3 類型安全的傳遞鏈路與模板內(nèi)聯(lián)類型校驗通過之后變量對象會在整個渲染過程中以ServiceApiAnswers類型傳遞這意味著模板里寫context.projectName時編輯器有自動補全寫錯字段名在編譯期就會暴露。對模板作者來說這是體驗上的質(zhì)變以前是在生成后才能發(fā)現(xiàn)變量名拼錯現(xiàn)在是寫模板的時候就發(fā)現(xiàn)了。更進一步的類型安全體現(xiàn)在模板內(nèi)容上。例如 Node 版本這個變量在模板里會生成一個.nvmrc文件內(nèi)容是v20。如果模板只寫{{ nodeVersion }}這個值的合法性完全依賴渲染前的校驗一旦校驗邏輯出 bug 就可能生成一個不存在的 Node 版本。我傾向于在模板里額外做一道約束用條件塊判斷 nodeVersion 是 18 還是 20分別生成對應內(nèi)容寧可讓模板多兩行也要把非法值擋在文件系統(tǒng)之外。5. typecheck 閘門生成之后的第一次體檢與常見失敗5.1 為什么腳手架必須內(nèi)置類型校驗t3code 生成的項目至少要達到一個底線安裝依賴之后tsc --noEmit必須能過。如果連這個底線都保證不了“腳手架”就退化成“文件復制器”生成的東西能不能跑完全看運氣。把 typecheck 放進腳手架流程等于把所有模板的合法性檢查前置任何模板改動都必須先讓所有基于它的項目通過類型檢查才能合入模板倉庫。這個閘門還有一個額外收益它逼著模板作者把依賴版本寫死。如果模板里typescript寫的是寬松范圍比如^5.4.0今天生成的項目的類型結(jié)果可能明天就變了typecheck 就失去了確定性。5.2 實現(xiàn)細節(jié)調(diào)用本地 tsc 而不是全局命令執(zhí)行類型檢查時最容易踩的坑是調(diào)全局 tsc。全局安裝的 TypeScript 版本和項目本地版本可能差很多用全局 tsc 校驗本地項目完全沒有代表性。正確做法是在生成的項目目錄里解析本地 typescriptimport { execFile } from node:child_process; import { promisify } from node:util; import { createRequire } from node:module; import path from node:path; const require createRequire(path.resolve(targetDir, package.json)); const tscBin require.resolve(typescript/bin/tsc); const execFileAsync promisify(execFile); const { stdout, stderr } await execFileAsync( process.execPath, [tscBin, --noEmit, --pretty, false], { cwd: targetDir } ); const output stdout stderr; if (output.trim()) { reportTypeErrors(output, targetDir); }為什么用process.execPath跑 tsc因為 bin 腳本本質(zhì)上是一個 Node 文件直接用 node 執(zhí)行它就是最穩(wěn)的方式也可以避免一些系統(tǒng)上 bin 鏈接配置的問題。check 之后如果輸出不為空把錯誤按文件分組輸出并給出常見的修復提示。我刻意沒有做“自動修復”因為自動修改生成的代碼既危險又不可控tsc 的錯誤信息已經(jīng)足夠人類工程師定位問題腳手架的職責是盡早暴露問題而不是替工程師決定怎么改。5.3 常見失敗與自動修復嘗試實際跑過那么多模板之后typecheck 失敗集中在幾類strict 模式下對可能為 null 的值做運算、某個 import 的路徑大小寫寫錯、新版本 TypeScript 對某些 API 的默認類型收窄。前兩類是模板本身的問題改模板就好。第三類是依賴抖動這部分到第六章詳細說它背后的根因不是模板錯了而是依賴版本沒有鎖住。對于第一類失敗一個可用的緩解策略是模板里統(tǒng)一使用satisfies和顯式類型注解讓潛在問題在模板編譯階段就暴露。這不能根治問題但它能把“生成一個壞項目”的概率壓到更低。6. 從能用到好用之間隔著這些坑6.1 Windows 路徑與 CRLF一次跨平臺故障的完整排查t3code 早期基本只有我在用跑在 macOS 上。直到一個 Windows 同事試用后發(fā)來截圖生成的配置文件里路徑變成了D:\repo\service-api\src\config然后.env文件每行結(jié)尾帶著奇怪的^M。排查的第一步是復現(xiàn)。我在 Windows 虛擬機上跑了一遍同樣的 init確認問題穩(wěn)定存在。第二步是定位范圍。我分別測試了“從模板讀取文件后直接寫入”“中間經(jīng)過插值引擎”“插值且變量包含路徑”三種場景最終確認問題出在插值階段從命令行傳入的 Windows 路徑會帶反斜杠模板里用{{ projectDir }}渲染后反斜杠在部分上下文里被解釋成轉(zhuǎn)義符產(chǎn)生了亂碼。至于^M則是模板文件本身以 CRLF 保存讀取后我按 UTF-8 原樣寫入Windows 環(huán)境下 Git 又自動加了 CRLF導致雙重轉(zhuǎn)換。修復方案分兩層插值引擎對傳入的字符串統(tǒng)一做一次路徑規(guī)范化把反斜杠轉(zhuǎn)成正斜杠所有文本文件寫入前統(tǒng)一把換行符規(guī)范化為\n并借助.gitattributes里的text eollf約定把模板倉庫的換行符鎖死。這之后 Windows 上生成的代碼行為才完全和 macOS 一致。這個坑教會我的不是“怎么處理路徑”而是“跨平臺工具必須讓核心渲染管線與操作系統(tǒng)無關(guān)”。路徑是操作系統(tǒng)的方言方言應該在邊界處被翻譯而不是在管道里到處穿。6.2 占位符被渲染函數(shù)誤傷變量命名引發(fā)的連鎖反應第二個坑更難發(fā)現(xiàn)。有一天我用 t3code 生成一個內(nèi)部管理后臺模板里有一行 Vue 代碼span{{ userName }}/span。渲染完一看userName 變成了空字符串。我第一反應是變量沒傳進去排查了很久才意識到問題根本不是變量缺失而是自己的插值引擎把模板里本來就存在的 Vue 插值語法{{ userName }}當成 t3code 的變量占位符執(zhí)行了替換而渲染環(huán)境里根本沒有 userName 這個變量于是它被替換成了空。這個問題的本質(zhì)是占位符定界符沖突。任何一門模板語言都可能引入{{ }}語法你的腳手架只要生成 Vue、Angular、Handlebars 相關(guān)的代碼遲早會撞上。我的解決方案是給插值引擎增加一層轉(zhuǎn)義語義\{{表示字面量{{渲染時保留原樣同時把渲染結(jié)果標記為“已渲染”禁止對已渲染的文本再次執(zhí)行插值。這條規(guī)則雖然簡單但當時是在踩過坑之后才補上的。如果讓我重新設計一次我會在一開始就把定界符改成不那么容易沖突的[[ ]]而不是沿用 mustache 風格的{{ }}。兼容社區(qū)習慣帶來了一點便利卻換來了和下游模板語法長期共存的風險這個賬其實是不劃算的。6.3 依賴抖動本地的綠燈CI 的紅燈typecheck 集成之后有一段時間我在本地怎么跑都是綠的CI 卻時不時飄紅。最開始以為又是 Windows 的問題直到我在 CI 日志里看到typescript每次解析到的版本都不一樣才反應過來模板里的依賴聲明寫的是^5.4.0這類范圍版本每次 install 都會重新解析最新小版本TypeScript 的小版本升級偶爾會帶來更嚴格的類型檢查于是同一個模板今天能過、明天就可能不能過。排查和修復的過程不復雜模板里所有關(guān)鍵依賴改成精確版本或~范圍提交 lockfileCI 使用pnpm install --frozen-lockfile。真正值得反思的是為什么這個問題拖了這么久才暴露因為我給 t3code 的測試用例都是在本地跑本地 node_modules 早就鎖死了版本根本不會重現(xiàn)“全新環(huán)境安裝”的場景。后來我在 CI 上加了一個每晚執(zhí)行的“從零生成并 typecheck”的任務才真正把這類抖動擋在合并之前。6.4 測試策略用 fixture 而不是拿真實業(yè)務當小白鼠t3code 的測試大概可以分成三層。第一層是渲染引擎的單元測試覆蓋插值、條件、循環(huán)、轉(zhuǎn)義、二進制保護這些純函數(shù)。第二層是命令層的集成測試在臨時目錄里跑完整的 init然后對照快照檢查生成文件的路徑、內(nèi)容和權(quán)限。第三層是跨平臺矩陣在 GitHub Actions 的 ubuntu、macos、windows 三個 runner 上跑同一套測試用例。fixture 模板和真實模板必須分開。真實模板會隨業(yè)務演進拿來當測試基線會讓測試跟著模板一起變最終退化成“確認現(xiàn)狀沒變”。fixture 模板小而穩(wěn)定只服務測試這樣引擎的測試結(jié)果才可靠。也是因為有了這一層 fixture后面改渲染引擎時才敢做重構(gòu)。7. 從個人工具到團隊基建t3code 的成長路線7.1 離線緩存與自動升級t3code 作為內(nèi)部工具一開始沒有考慮離線環(huán)境。但內(nèi)網(wǎng)開發(fā)環(huán)境經(jīng)常在一個隔離網(wǎng)絡里npm install 需要走內(nèi)部鏡像。為此我在模板目錄里增加了一個 lock 文件記錄模板期望的鏡像地址和依賴版本組合init 之后自動改寫 package.json 里的 registry 配置。這一步看似不起眼實際上讓內(nèi)網(wǎng)同事的初始化時間從十幾分鐘降到幾十秒。自動升級用的是一個簡單的版本檢查每次 init 前請求一次模板注冊表接口把本地模板版本和遠程版本做對比有新版就提示。我把這個檢查的開關(guān)默認設為關(guān)閉原因是內(nèi)網(wǎng)環(huán)境不是都有公網(wǎng)出口把一個可選的網(wǎng)絡請求做成強制會得罪所有人。7.2 自己吃自己的狗糧Dogfooding 對腳手架工具的驗證效果比任何測試都強。我把 t3code 本身也納入模板管理每次從模板生成一個最小 CLI 項目然后在這個項目上繼續(xù)加功能。這個循環(huán)能強制發(fā)現(xiàn)模板里的所有問題如果一個模板連它自己的作者都無法流暢使用那說明模板里還有未消化的復雜度。7.3 下一步從代碼工程到代碼規(guī)范如果 t3code 繼續(xù)演進我期望的方向是 AST 級改造。目前的 transform 原語還是基于字符串替換它能做 90% 的工作但對“統(tǒng)一 import 順序”“強制導出一個入口函數(shù)”這類結(jié)構(gòu)化改造很吃力。AST 級 transform 會讓模板深入很多但復雜度也會顯著上升?，F(xiàn)階段我更傾向于保持三條原語的簡單性把復雜模板拆成分層文件而不是把一個模板做成一個萬能機器。最后分享一個我在實際維護中一直堅持的小習慣每次給 t3code 增加一個新能力先要求它“生成后的項目必須能在兩分鐘內(nèi)被新同事看懂”做不到就把能力砍掉。腳手架不是給自己秀操作的地方它服務的對象永遠是下一個打開代碼倉庫的人。這個標準聽起來模糊但它幫我擋掉過不少華而不實的功能提案。