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