棧腳手架：t3code的工程化實(shí)踐與踩坑記錄)
1. 項(xiàng)目緣起放著現(xiàn)成腳手架不用我為什么自己寫了 t3code大概半年前我開(kāi)始動(dòng)手寫 t3code 這個(gè)項(xiàng)目——一個(gè)基于 T3 技術(shù)棧TypeScript、Tailwind CSS、tRPC 加 Next.js的項(xiàng)目腳手架生成工具。起因特別簡(jiǎn)單團(tuán)隊(duì)里新項(xiàng)目初始化太慢每次手動(dòng)補(bǔ)齊的內(nèi)容都一模一樣重復(fù)勞動(dòng)多了人就容易產(chǎn)生干脆寫個(gè)工具把這事自動(dòng)化的沖動(dòng)。t3code 這個(gè)名字沒(méi)花什么心思T3 棧加 code 生成器拆開(kāi)念就是 t3-code順手就在 npm 上搜了一下沒(méi)有重名直接發(fā)布。1.1 從 T3 技術(shù)棧說(shuō)起先給不熟悉的讀者簡(jiǎn)單交代一下背景。T3 技術(shù)棧是這幾年在 React 全棧開(kāi)發(fā)里很流行的一套組合TypeScript 提供類型安全Tailwind CSS 負(fù)責(zé)樣式tRPC 讓你在不寫 REST 接口文檔的情況下實(shí)現(xiàn)前后端類型共享應(yīng)用框架用的是 Next.js。這個(gè)組合最大的好處是端到端類型安全——你改一個(gè)后端返回字段的類型前端編輯器里立刻就能報(bào)錯(cuò)不用等聯(lián)調(diào)。我第一次用 create-t3-app 拉起項(xiàng)目的時(shí)候體驗(yàn)確實(shí)很好幾分鐘就能得到一個(gè)帶完整 tRPC 鏈路和 Tailwind 樣板的工程。但用得多了問(wèn)題就浮出來(lái)了。create-t3-app 是大眾的腳手架它的默認(rèn)配置面向最通用的場(chǎng)景而團(tuán)隊(duì)工程實(shí)踐一旦有自己的約定這套默認(rèn)配置就不夠用了。我們團(tuán)隊(duì)的要求包括每個(gè)新項(xiàng)目必須帶 docs 目錄、必須用 pnpm 而不是 npm、ESLint 必須開(kāi) import 排序規(guī)則、依賴要鎖定精確版本號(hào)、必須包含 .env.example 模板、CI 腳本要用統(tǒng)一的 Node 版本。這些約定說(shuō)多不多說(shuō)少不少每次初始化完 create-t3-app 都要手動(dòng)改一遍改完還要手動(dòng)建目錄、拷公共工具函數(shù)。一次兩次能忍十次二十次就非常煩躁了。我還見(jiàn)過(guò)更糟的情況有同事初始化完項(xiàng)目以后忘了補(bǔ) .env.example直接把帶真實(shí)數(shù)據(jù)庫(kù)連接串的配置提交到了倉(cāng)庫(kù)雖然最后及時(shí)改了回來(lái)但這種風(fēng)險(xiǎn)不應(yīng)該靠人的記憶力去兜底。所以我的核心訴求非常清楚要把團(tuán)隊(duì)自己的工程約定固化成一個(gè)可復(fù)現(xiàn)的腳本讓新建一個(gè)符合團(tuán)隊(duì)規(guī)范的 T3 項(xiàng)目從半小時(shí)縮減到兩分鐘。t3code 就是在這個(gè)背景下誕生的。1.2 現(xiàn)成腳手架的三個(gè)痛點(diǎn)在決定自研之前我把市面上能找的腳手架都過(guò)了一遍包括 create-t3-app、create-next-app、各種社區(qū)模板倉(cāng)庫(kù)。它們的痛點(diǎn)歸納起來(lái)有三個(gè)。第一模板不可定制或定制成本高。create-t3-app 雖然提供了不少配置選項(xiàng)但它不開(kāi)放模板機(jī)制你想加自己的 CI 腳本、自己的工具函數(shù)目錄只能生成之后手動(dòng)改。社區(qū)模板倉(cāng)庫(kù)倒是可以 fork但 fork 之后每次上游更新都要手動(dòng)合并追版本追得心累。第二團(tuán)隊(duì)約定無(wú)法沉淀。腳手架工具本質(zhì)上是工程經(jīng)驗(yàn)的載體但現(xiàn)成工具承載的是作者的工程經(jīng)驗(yàn)不是你的。團(tuán)隊(duì)里的目錄規(guī)范、代碼風(fēng)格、提交規(guī)范、環(huán)境變量管理方式這些只有自己人最清楚指望一個(gè)社區(qū)工具替你管理根本不現(xiàn)實(shí)。第三生成產(chǎn)物黑盒。很多腳手架生成完之后用戶對(duì)項(xiàng)目里每一份文件的出處一無(wú)所知。出了問(wèn)題只能整個(gè)刪掉重建沒(méi)辦法針對(duì)性地修某一處模板邏輯。對(duì)于需要長(zhǎng)期維護(hù)的團(tuán)隊(duì)工程基線來(lái)說(shuō)這不是小事。1.3 我想要的工程化基線因此我給 t3code 定下的目標(biāo)很明確它不是一個(gè)通用的代碼生成器而是團(tuán)隊(duì)工程化基線的一個(gè)載體。具體要做到四件事——交互收集參數(shù)、拷貝模板文件、渲染動(dòng)態(tài)內(nèi)容、執(zhí)行收尾動(dòng)作。后面所有設(shè)計(jì)決策都是圍繞這四件事展開(kāi)的。范圍定小了復(fù)雜度自然就下來(lái)了核心邏輯加起來(lái)不到一千行剩下全是模板代碼。這篇文章會(huì)把設(shè)計(jì)思路、核心實(shí)現(xiàn)和踩坑記錄完整寫出來(lái)。如果你在團(tuán)隊(duì)里做前端基建或者想給自己的團(tuán)隊(duì)落地一套內(nèi)部腳手架又或者只是好奇一個(gè) CLI 工具是怎么從零做出來(lái)的應(yīng)該都能從中找到一些可以復(fù)用的經(jīng)驗(yàn)。內(nèi)容不需要多高深Node.js 基礎(chǔ)加一點(diǎn)模板引擎知識(shí)就能看懂。2. 整體設(shè)計(jì)思路腳手架工具要解決的四個(gè)問(wèn)題2.1 先想清楚t3code 不是什么比它是什么更重要?jiǎng)邮种拔易龅淖钪匾囊患率墙o自己劃界線。t3code 不是低代碼平臺(tái)不是代碼生成器更不是要替代 create-t3-app 的通用方案。它就是項(xiàng)目初始化加速器把創(chuàng)建項(xiàng)目過(guò)程中的重復(fù)勞動(dòng)壓縮成一條命令。這個(gè)定位聽(tīng)起來(lái)簡(jiǎn)單但它直接影響后面每一個(gè)設(shè)計(jì)選擇范圍不擴(kuò)大復(fù)雜度就可控模板只在團(tuán)隊(duì)內(nèi)部用就不需要做復(fù)雜的遠(yuǎn)程拉取用戶都是有經(jīng)驗(yàn)的開(kāi)發(fā)者就不需要做圖形化界面。明確了定位之后核心功能就清晰了。t3code 做的事包括四件第一交互收集參數(shù)包括項(xiàng)目名、包名、是否啟用 CI、是否初始化 Git、選擇哪個(gè)業(yè)務(wù)模板第二拷貝模板文件把內(nèi)置模板目錄完整復(fù)制到目標(biāo)目錄第三渲染動(dòng)態(tài)內(nèi)容把項(xiàng)目名、版本號(hào)、npm registry 地址等變量替換進(jìn)模板文件第四執(zhí)行收尾動(dòng)作自動(dòng)安裝依賴、初始化 Git、打印啟動(dòng)命令。這四件事每一件拆開(kāi)都不復(fù)雜但組合起來(lái)加上各種邊緣情況的處理就是完整的工具了。我見(jiàn)過(guò)不少腳手架工具交互做得很花哨結(jié)果復(fù)制文件時(shí)不處理隱藏文件、不處理 .gitignore生成出來(lái)的項(xiàng)目根本不是用戶預(yù)期的樣子。所以 t3code 從第一天起就刻意保持小體積小到核心邏輯出了問(wèn)題能一眼定位。2.2 技術(shù)選型為什么是 Node.js Commander而不是 Go、Rust 或 Shell選型這件事我糾結(jié)過(guò)兩天。做一個(gè)腳手架工具擺面前有幾條路。第一條是用 Go 或 Rust 寫編譯型二進(jìn)制優(yōu)點(diǎn)是沒(méi)有運(yùn)行時(shí)依賴、啟動(dòng)速度快可以做成一條命令直接放在任意機(jī)器上跑但缺點(diǎn)是模板分發(fā)麻煩模板如果打包進(jìn)二進(jìn)制那么每改一次模板就要重新編譯團(tuán)隊(duì)里非 Go 開(kāi)發(fā)者想貢獻(xiàn)模板要先裝工具鏈這門檻對(duì)前端團(tuán)隊(duì)來(lái)說(shuō)太高了。第二條路是寫 Shell 腳本。簡(jiǎn)單場(chǎng)景下 Shell 完全夠用比如 mkdir、cp、sed 一把梭。但只要涉及到交互式問(wèn)答、跨平臺(tái)路徑處理、JSON 變量替換、錯(cuò)誤重試這些操作Shell 很快就會(huì)變成一團(tuán)亂麻。尤其是 macOS 的 zsh 和 Linux 的 bash 行為還有差異Windows 更是直接勸退。第三條路是用 Node.js 寫一個(gè) npm 包類型的 CLI這也是我最終的選擇。原因很實(shí)際團(tuán)隊(duì)里前端工程師人人都有 Node 環(huán)境npx t3code 一條命令就能跑起來(lái)模板直接打包在 npm 包里發(fā)布新模板就是發(fā)一個(gè)新版本包。模板文件對(duì)前端工程師來(lái)說(shuō)是純文本改起來(lái)沒(méi)有任何額外學(xué)習(xí)成本。Node.js 生態(tài)里 Commander、Inquirer、execa、Handlebars 這些庫(kù)都是久經(jīng)考驗(yàn)的完全不用重新造輪子。最終 t3code 的依賴清單如下commander命令行參數(shù)解析。inquirer交互式問(wèn)答。handlebars模板渲染。execa子進(jìn)程執(zhí)行安裝依賴、git 命令。fs-extra遞歸拷貝和文件操作。每個(gè)庫(kù)都放在自己最擅長(zhǎng)的位置上。commander 負(fù)責(zé)參數(shù)inquirer 負(fù)責(zé)問(wèn)答handlebars 負(fù)責(zé)渲染execa 負(fù)責(zé)外部命令fs-extra 負(fù)責(zé)文件系統(tǒng)操作。依賴雖然不少但沒(méi)有一個(gè)是可有可無(wú)的。2.3 模板目錄結(jié)構(gòu)約定優(yōu)于配置配置優(yōu)于代碼t3code 的模板不是簡(jiǎn)單的一堆文件它有明確的兩層結(jié)構(gòu)。第一層是項(xiàng)目級(jí)模板比如 next-trpc、next-plain、library每個(gè)模板對(duì)應(yīng)一類項(xiàng)目形態(tài)第二層是模板內(nèi)部的可選區(qū)塊比如某個(gè)模板里可以選擇是否生成 GitHub Actions 工作流、是否生成 Dockerfile。這么設(shè)計(jì)是為了讓按需生成成為可能同時(shí)不讓這種靈活性泛濫成災(zāi)。模板目錄的結(jié)構(gòu)大致是這樣的templates/ ├── next-trpc/ │ ├── base/ │ │ ├── .env.example │ │ ├── .eslintrc.cjs │ │ ├── package.json.j2 │ │ ├── tsconfig.json │ │ ├── next.config.mjs │ │ ├── src/ │ │ └── README.md.j2 │ ├── optional/ │ │ ├── ci-github/ │ │ ├── docker/ │ │ └── monorepo/ │ └── manifest.json ├── next-plain/ └── library/base 目錄下的文件是必選內(nèi)容optional 目錄下都是可選的增量文件。manifest.json 聲明了這個(gè)模板支持哪些可選區(qū)塊、哪些文件需要渲染、默認(rèn)推薦選項(xiàng)是什么。模板里以 .j2 結(jié)尾的文件表示需要經(jīng)過(guò) Handlebars 渲染其他文件一律原樣拷貝。這個(gè)約定的好處是模板作者一眼就能看出哪些文件會(huì)被動(dòng)態(tài)處理哪些不會(huì)。模板即代碼是我在這個(gè)項(xiàng)目里最堅(jiān)持的原則。業(yè)務(wù)方想加一段自定義配置不需要改 t3code 的源碼只需要在 templates 目錄下新增一個(gè) optional 區(qū)塊然后更新 manifest.json 的描述文案。后來(lái)我們團(tuán)隊(duì)干脆把模板倉(cāng)庫(kù)單獨(dú)拆了出去通過(guò) git submodule 的方式在發(fā)版本時(shí)同步進(jìn)主倉(cāng)庫(kù)模板的維護(hù)和 CLI 代碼的維護(hù)徹底解耦。這一步讓我體會(huì)到模板結(jié)構(gòu)設(shè)計(jì)得清晰很多后續(xù)的流程問(wèn)題都會(huì)自動(dòng)消失。3. 核心實(shí)現(xiàn)拆解從用戶輸入到項(xiàng)目落地的完整鏈路3.1 入口命令與參數(shù)解析t3code 的命令入口是 package.json 的 bin 字段指向的 JS 文件。我用 Commander 定義了三個(gè)子命令init 是交互式創(chuàng)建項(xiàng)目list 列出所有可用模板doctor 檢查當(dāng)前環(huán)境是否滿足生成條件。三個(gè)命令各有定位init 是日常主力list 讓用戶知道有哪些選擇doctor 則是排障專用的環(huán)境有問(wèn)題時(shí)先跑一下它。下面貼 init 命令的解析邏輯這是整個(gè)工具的主入口#!/usr/bin/env node const { Command } require(commander); const program new Command(); program .name(t3code) .description(T3 技術(shù)棧項(xiàng)目腳手架生成器) .version(1.4.2); program .command(init) .description(初始化一個(gè) T3 項(xiàng)目) .argument([projectName], 項(xiàng)目目錄名稱例如 my-app) .option(-t, --template name, 指定模板例如 next-trpc) .option(--no-git, 跳過(guò) git init) .option(--no-install, 跳過(guò)依賴安裝) .option(-r, --registry url, 指定 npm registry 地址) .action((projectName, options) { runInit(projectName, options).catch((err) { console.error([t3code] 初始化失敗:, err.message); process.exit(1); }); }); program.parse(process.argv);Commander 的 argument 和 option 分離得很清晰。項(xiàng)目名是位置參數(shù)可以寫在命令后面模板、registry 等是選項(xiàng)參數(shù)用短橫線語(yǔ)法傳。這里我考慮過(guò)要不要加一個(gè) --yes 參數(shù)跳過(guò)所有交互直接使用默認(rèn)值后來(lái)決定不支持。原因是我見(jiàn)過(guò)太多腳手架默認(rèn)值藏在文檔里用戶完全不知道自己在用什么。t3code 面向的是有一定經(jīng)驗(yàn)的開(kāi)發(fā)者把關(guān)鍵選項(xiàng)問(wèn)清楚比快速跳過(guò)重要得多。3.2 交互式問(wèn)答把決策放在用戶眼前把校驗(yàn)做在輸入之前如果用戶沒(méi)有在命令行里指定項(xiàng)目名或模板init 流程就會(huì)進(jìn)入 Inquirer 的問(wèn)答環(huán)節(jié)。我把問(wèn)答分成兩層第一層是項(xiàng)目基本信息第二層是根據(jù) manifest.json 動(dòng)態(tài)生成的可選區(qū)塊問(wèn)題。第一層的問(wèn)題非常直接但校驗(yàn)必須嚴(yán)格。比如項(xiàng)目名的校驗(yàn)const basicQuestions [ { type: input, name: projectName, message: 項(xiàng)目目錄名稱:, validate: (input) { if (!input.trim()) return 項(xiàng)目名不能為空; if (!/^[a-z0-9-]$/.test(input)) return 只能包含小寫字母、數(shù)字和中劃線; return true; }, }, { type: input, name: packageName, message: npm 包名默認(rèn)與項(xiàng)目名一致:, default: (answers) answers.projectName, validate: (input) { if (!/^[a-z0-9-]$/.test(input)) return 包名只能包含小寫字母、數(shù)字和中劃線; return true; }, }, ];這個(gè)校驗(yàn)規(guī)則是我踩坑踩出來(lái)的。第一版只做了非空校驗(yàn)結(jié)果有同事輸入了中文項(xiàng)目名后面生成的 next.config.mjs 直接被 Node.js 解析報(bào)錯(cuò)還得手動(dòng)改一堆文件名。從那之后所有用戶輸入都必須過(guò)規(guī)則校驗(yàn)。寧可在 prompt 階段多問(wèn)一遍也不要在生成之后返工。正則限定得嚴(yán)一點(diǎn)沒(méi)有壞處因?yàn)轫?xiàng)目名和包名都會(huì)進(jìn)入后續(xù)的模板變量一旦出現(xiàn)非法字符問(wèn)題往往不止一處。第二層問(wèn)題來(lái)自模板的 manifest.json。比如模板聲明了 ci-github 這個(gè)可選區(qū)塊init 流程就會(huì)自動(dòng)生成一個(gè)確認(rèn)類型的問(wèn)題是否生成 GitHub Actions 工作流。這層邏輯雖然只用了幾行代碼但它的意義在于模板能力擴(kuò)展不再需要修改代碼只要改 manifest.json交互層就是通用的。3.3 模板渲染為什么選 Handlebars而不是字符串拼接模板渲染是整個(gè)工具的技術(shù)核心。最初我想過(guò)最簡(jiǎn)單的方式在模板里寫PROJECT_NAME之類的占位符然后用字符串 replace 替換成實(shí)際值。這個(gè)方案實(shí)現(xiàn)最快但有一個(gè)致命問(wèn)題——如果配置內(nèi)容需要根據(jù)用戶選項(xiàng)條件性地出現(xiàn)字符串拼接就完全無(wú)力了。舉個(gè)例子package.json 里如果用戶選擇了 Docker 區(qū)塊scripts 里就要多一個(gè) docker:build 命令如果選擇了 CI 區(qū)塊devDependencies 里就要多幾個(gè)包。用字符串拼接去組織這些條件邏輯代碼會(huì)迅速腐爛。所以我改用 Handlebars。它有三個(gè)好處語(yǔ)法簡(jiǎn)單模板作者不需要學(xué)一門新語(yǔ)言原生支持 #if 條件判斷和 #each 循環(huán)覆蓋了我 99% 的需求有完整的轉(zhuǎn)義機(jī)制不會(huì)出現(xiàn)模板變量破壞 JSON 格式的問(wèn)題。下面是一個(gè)真實(shí)模板片段來(lái)自 next-trpc 模板的 package.json.j2{ name: {{packageName}}, version: 0.1.0, scripts: { dev: next dev, build: next build, start: next start, lint: next lint, {{#if withDocker}} docker:build: docker build -t {{projectName}}:latest ., {{/if}} typecheck: tsc --noEmit }, devDependencies: { typescript: ^5.4.0, tailwindcss: ^3.4.0, eslint: ^8.57.0, eslint-config-next: ^14.1.0, {{#if withCI}} changesets/cli: ^2.27.0, {{/if}} eslint-plugin-tailwindcss: ^0.5.0 } }渲染的時(shí)候把前面收集到的所有答案整理成一個(gè)大的 context 對(duì)象傳給 Handlebars 編譯之后的函數(shù)const Handlebars require(handlebars); const context { projectName: my-app, packageName: my-app, withDocker: true, withCI: false, author: your-name, registry: https://registry.npmjs.org, }; const source await fs.readFile(templateFile, utf-8); const render Handlebars.compile(source); const output render(context);這里有一個(gè)我從實(shí)際使用中總結(jié)出來(lái)的關(guān)鍵經(jīng)驗(yàn)?zāi)０逦募彩?.json 結(jié)尾的渲染完成之后必須通過(guò) JSON.parse 校驗(yàn)才能落盤。因?yàn)?Handlebars 的 #if 塊如果縮進(jìn)或者逗號(hào)位置處理不當(dāng)很容易在 JSON 文件里多出一個(gè)逗號(hào)或者少一個(gè)閉合括號(hào)。我在 renderFile 函數(shù)里加了一個(gè)鉤子如果源文件擴(kuò)展名是 .json渲染結(jié)果必須 JSON.parse 成功否則直接報(bào)錯(cuò)并且把渲染結(jié)果連同原始模板一起打印出來(lái)。這個(gè)鉤子幫我攔下了很多模板編寫不規(guī)范的問(wèn)題。3.4 文件落盤與目錄創(chuàng)建最容易翻車的環(huán)節(jié)渲染完成之后就該寫文件了。這個(gè)環(huán)節(jié)看起來(lái)最沒(méi)有技術(shù)含量實(shí)際上最容易翻車。我用 fs-extra 的 copy 方法先把模板目錄完整復(fù)制到目標(biāo)目錄然后逐文件處理渲染。注意順序很重要先復(fù)制再渲染可以保證非模板文件比如圖片、字體、二進(jìn)制文件也能被原樣帶上如果先渲染再?gòu)?fù)制二進(jìn)制文件可能會(huì)在讀寫過(guò)程中損壞。核心代碼如下const fse require(fs-extra); await fse.copy(templateBaseDir, targetDir, { filter: (src) !src.includes(node_modules), }); // 遍歷目標(biāo)目錄渲染所有 .j2 結(jié)尾的文件 const files await findAllJ2Files(targetDir); for (const file of files) { const rendered await renderTemplateFile(file, context); const outputPath file.replace(/\.j2$/, ); await fse.outputFile(outputPath, rendered); await fse.remove(file); }有幾個(gè)細(xì)節(jié)必須強(qiáng)調(diào)。第一遍歷文件時(shí)要用 fs.readdir 的 withFileTypes 參數(shù)判斷目錄類型不能用簡(jiǎn)單的字符串包含判斷否則遇到名字里帶點(diǎn)的目錄比如 .next、.github會(huì)誤判成文件。第二隱藏文件在 copy 階段是正常處理的但如果你選了某些第三方復(fù)制庫(kù)要確認(rèn)它的過(guò)濾邏輯不會(huì)把隱藏文件丟掉。第三目標(biāo)目錄如果已經(jīng)存在且非空init 命令應(yīng)該直接拒絕執(zhí)行必須加一個(gè) --force 選項(xiàng)才能覆蓋。這個(gè)保護(hù)非常重要我因?yàn)樵缙谕藢戇@個(gè)檢查曾經(jīng)把同事一個(gè)正在開(kāi)發(fā)的目錄直接覆蓋了。項(xiàng)目?jī)?nèi)容沒(méi)丟但那次經(jīng)歷絕對(duì)不想再來(lái)一次。3.5 依賴安裝與 Git 初始化外部命令的靜默陷阱文件生成完畢最后一步是安裝依賴和初始化 Git。這里我用了 execa 而不是 Node.js 自帶的 child_process.exec原因是 execa 對(duì) Windows 的支持更好還支持超時(shí)時(shí)間和 stdio 模式設(shè)置。以下是依賴安裝和 Git 初始化的代碼const execa require(execa); async function installDependencies(targetDir, { registry }) { const args [install]; if (registry) { args.push(--registry, registry); } const subprocess execa(npm, args, { cwd: targetDir, stdio: inherit, timeout: 120000, }); try { await subprocess; } catch (err) { throw new Error(依賴安裝失敗: ${err.message}); } } async function initGit(targetDir) { if (!(await fse.exists(path.join(targetDir, .git)))) { await execa(git, [init, -b, main], { cwd: targetDir }); await execa(git, [add, .], { cwd: targetDir }); await execa(git, [commit, -m, chore: init project via t3code], { cwd: targetDir, }).catch(() { // 如果用戶全局 git 配置不全缺 name/emailcommit 會(huì)失敗 // 這里不做強(qiáng)制只留下提示 console.warn([t3code] 自動(dòng) commit 失敗請(qǐng)檢查 git 用戶配置); }); } }git init 之后要不要自動(dòng) commit我猶豫過(guò)。自動(dòng) commit 的好處是用戶拿到的是一個(gè)干凈的工作區(qū)可以直接開(kāi)新分支寫代碼壞處是如果用戶的全局 git 配置不全commit 失敗會(huì)中斷整個(gè)流程。后來(lái)我做了容錯(cuò)處理commit 失敗只打印警告不阻塞流程。同時(shí)用戶也可以用 --no-git 完全跳過(guò) Git 相關(guān)操作。依賴安裝這里我特意保留了 stdio: inherit讓 npm 的安裝日志直接打到終端上。有些腳手架喜歡把安裝過(guò)程藏起來(lái)只顯示一個(gè) spinner但實(shí)際經(jīng)驗(yàn)是安裝卡住的時(shí)候用戶最需要原始進(jìn)度信息。寧可輸出丑一點(diǎn)也要讓用戶知道它到底卡在哪一步。npm install 超過(guò)兩分鐘超時(shí)之后錯(cuò)誤信息會(huì)包含具體命令的完整輸出這比安裝失敗四個(gè)字有用得多。4. 實(shí)測(cè)過(guò)程從一條命令到完整可用的 T3 項(xiàng)目4.1 完整跑一遍 t3code init我拿一臺(tái)配置干凈的新電腦做了一次完整實(shí)測(cè)確保從空目錄到項(xiàng)目跑起來(lái)沒(méi)有斷點(diǎn)。執(zhí)行命令npx t3code init my-app -t next-trpc由于指定了模板交互問(wèn)答會(huì)自動(dòng)跳過(guò)模板選擇剩下的問(wèn)題只有四個(gè)npm 包名、是否生成 Dockerfile、是否生成 CI 工作流、是否自動(dòng)執(zhí)行依賴安裝和 git init。這四個(gè)問(wèn)題的默認(rèn)值我都做了認(rèn)真設(shè)計(jì)包名默認(rèn)等于項(xiàng)目名Dockerfile 默認(rèn)不生成CI 默認(rèn)生成安裝和 git init 默認(rèn)執(zhí)行。默認(rèn)值的選取原則是多數(shù)場(chǎng)景下不需要改而不是保守選項(xiàng)避免出錯(cuò)。選擇完成之后大概過(guò)了一分多鐘大部分時(shí)間是 npm install 在跑。等命令結(jié)束我用 tree 命令看了一眼生成的項(xiàng)目結(jié)構(gòu)my-app/ ├── .env.example ├── .eslintrc.cjs ├── .github/workflows/ci.yml ├── .gitignore ├── README.md ├── next.config.mjs ├── package.json ├── pnpm-lock.yaml ├── postcss.config.cjs ├── tailwind.config.ts ├── tsconfig.json └── src/ ├── app/ │ ├── api/trpc/[trpc]/route.ts │ ├── layout.tsx │ ├── page.tsx │ └── globals.css ├── server/api/root.ts ├── server/api/routers/post.ts ├── trpc/react.tsx └── trpc/server.ts然后執(zhí)行 npm run dev本機(jī) 3000 端口直接起了一個(gè)帶有 tRPC 完整鏈路的 Next.js 項(xiàng)目。從 React 組件到后端路由全類型安全新項(xiàng)目的第一個(gè) commit 就已經(jīng)是一個(gè)可以開(kāi)發(fā)的起點(diǎn)。整個(gè)流程走完我的感受是工具的價(jià)值不在于它生成了多少文件而在于它把想清楚再動(dòng)手這件事變成了默認(rèn)行為。新項(xiàng)目一創(chuàng)建目錄規(guī)范、命名規(guī)范、環(huán)境變量管理、CI 檢查全部就位。4.2 驗(yàn)證生成內(nèi)容的核心鏈路類型和 CI 都要真的能跑光能跑起來(lái)還不算數(shù)我特意做了兩件驗(yàn)證工作。第一件是驗(yàn)證端到端類型安全是否真的成立。我在 src/trpc/react.tsx 里調(diào)用 useQuery 獲取數(shù)據(jù)然后故意把服務(wù)端 router 返回的字段類型改掉編輯器里立刻出現(xiàn)了類型錯(cuò)誤。這說(shuō)明 tRPC 的端到端類型推斷在生成的樣板工程里是通的。這個(gè)驗(yàn)證很重要因?yàn)?t3code 的核心賣點(diǎn)之一就是類型安全如果模板里某個(gè)配置文件版本不匹配導(dǎo)致類型推斷斷裂整個(gè)項(xiàng)目的開(kāi)發(fā)體驗(yàn)會(huì)大打折扣。第二件是驗(yàn)證 CI 腳本能真正跑通。我把生成出來(lái)的 .github/workflows/ci.yml 放進(jìn)一個(gè) GitHub 倉(cāng)庫(kù)里觸發(fā)了一次流水線確認(rèn) lint、typecheck、build 三個(gè)步驟都能通過(guò)并且用的是模板里鎖定的 Node 版本。這兩項(xiàng)驗(yàn)證幫我發(fā)現(xiàn)了一個(gè)暗處的問(wèn)題模板里 .env.example 的 DATABASE_URL 用的是本地 localhost 默認(rèn)值但 CI 環(huán)境里根本沒(méi)有這個(gè)數(shù)據(jù)庫(kù)所以 CI 腳本里所有依賴數(shù)據(jù)庫(kù)的步驟我都提前加上了注釋用戶需要按自己的實(shí)際情況調(diào)整。這個(gè)問(wèn)題不算是 bug但它體現(xiàn)了模板作者該有的自覺(jué)——模板里必須留下足夠的注釋明確告訴使用者哪些地方必須改。4.3 參數(shù)化細(xì)節(jié)版本號(hào)為什么要統(tǒng)一管理生成出來(lái)的 package.json 里依賴版本號(hào)是精確鎖定的。這個(gè)決策當(dāng)時(shí)有同事反對(duì)覺(jué)得應(yīng)該用 latest 或者 ^ 前綴讓 npm 自動(dòng)解析到最新版。我堅(jiān)持用精確版本號(hào)原因很簡(jiǎn)單腳手架生成的項(xiàng)目是團(tuán)隊(duì)的長(zhǎng)期基線如果每次生成都拉到最新版某天某個(gè)依賴升級(jí)引入了 breaking change所有新項(xiàng)目同時(shí)中招問(wèn)題定位成本會(huì)非常高。精確鎖定版本讓升級(jí)這件事發(fā)生在可控的時(shí)間點(diǎn)比自動(dòng)最新穩(wěn)定得多。為此我在模板引擎里做了一個(gè)擴(kuò)展context 里注入一個(gè) versions 對(duì)象所有依賴版本都從一份統(tǒng)一的 versions.json 讀取。每次升級(jí)基礎(chǔ)依賴只需要改 versions.json 然后發(fā)布一個(gè)新版 t3code不用在一堆模板文件里翻找版本號(hào)。這是單一數(shù)據(jù)源原則在腳手架里的實(shí)際落地它保證了團(tuán)隊(duì)所有新項(xiàng)目用的基礎(chǔ)依賴版本完全一致不會(huì)出現(xiàn)張三的新項(xiàng)目用 React 18李四的新項(xiàng)目還在用 React 17 這種混亂情況。{ next: 14.1.0, react: 18.2.0, react-dom: 18.2.0, trpc/server: 10.45.0, trpc/client: 10.45.0, trpc/react-query: 10.45.0, trpc/next: 10.45.0, typescript: 5.4.0, tailwindcss: 3.4.1 }模板里引用版本號(hào)時(shí)寫成這樣{ dependencies: { next: {{versions.next}}, react: {{versions.react}}, trpc/server: {{versions.trpc-server}} } }versions.json 里的 key 和模板里的引用并不是靠約定來(lái)保證一致的我加了一個(gè)配套的單元測(cè)試模板文件里出現(xiàn)的所有 versions.xxx 引用必須在 versions.json 里有對(duì)應(yīng)定義否則測(cè)試直接失敗。這個(gè)測(cè)試是我踩了一次大坑之后才補(bǔ)上的。有一次我刪掉了某個(gè)不再需要的依賴版本定義但忘了模板里還在引用發(fā)布出去的版本生成的項(xiàng)目依賴直接失效排查了很久才定位到是版本錯(cuò)配。從那以后凡是模板和數(shù)據(jù)源之間的引用關(guān)系一律用自動(dòng)化測(cè)試兜底不再靠人肉記憶。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 模板渲染后 JSON 格式被破壞這是 t3code 用戶反饋?zhàn)疃嗟囊活悊?wèn)題。Handlebars 的 #if 塊在 JSON 文件里非常脆弱只要縮進(jìn)或者逗號(hào)位置不對(duì)渲染結(jié)果就是非法 JSON。舉一個(gè)真實(shí)例子。某個(gè)用戶自定義模板里寫了這樣的片段{ scripts: { dev: next dev, {{#if withE2E}} e2e: playwright test, {{/if}} build: next build } }如果 withE2E 為 false渲染結(jié)果會(huì)保留一個(gè)多余的空行JSON.parse 不一定失敗但可讀性很差。真正致命的是另一種寫法——把逗號(hào)放在 #if 塊前面{ scripts: { dev: next dev, {{#if withE2E}} e2e: playwright test {{/if}} } }當(dāng) withE2E 為 false 時(shí)dev: next dev, 后面直接跟著一個(gè) }這就是非法 JSON。解決這個(gè)問(wèn)題最穩(wěn)妥的方式是要求模板作者遵守一條約定任何可能被 #if 移除的條目它的前導(dǎo)逗號(hào)必須寫在 #if 塊內(nèi)部而不是寫在塊外面。我把這條約定寫進(jìn)了文檔同時(shí)保留了 JSON.parse 校驗(yàn)鉤子。雙保險(xiǎn)下來(lái)這類問(wèn)題基本絕跡了。5.2 Windows 兼容性三個(gè)高頻雷區(qū)我平時(shí)的主力開(kāi)發(fā)機(jī)是 macOS但團(tuán)隊(duì)里 Windows 同事不少。t3code 早期版本在 Windows 上的問(wèn)題集中出現(xiàn)在三處。第一是路徑分隔符。生成出來(lái)的某些配置需要寫路徑比如 Dockerfile 里的 COPY 命令。早期代碼直接用了 path.join 拼接路徑在 Windows 上會(huì)生成反斜杠Dockerfile 解析直接失敗。后來(lái)所有寫進(jìn)模板的路徑統(tǒng)一使用正斜杠只有真正操作文件系統(tǒng)的路徑才用 path.sep。第二是換行符。模板文件在 Windows 上被 Git 檢出后變成 CRLF渲染出來(lái)的文件也是 CRLF。Linux 容器或者 shell 腳本對(duì) CRLF 非常敏感會(huì)報(bào)一些莫名其妙的錯(cuò)誤。我在工具里加了一個(gè) lineEnding 配置項(xiàng)默認(rèn)按模板文件本身的行尾處理但允許用戶統(tǒng)一轉(zhuǎn)為 lf。第三是外部命令的調(diào)用方式。在 Windows 上通過(guò) Node.js 調(diào)用 npm.cmd 這類文件時(shí)execa 是安全的但如果直接用 child_process.exec 并且開(kāi)啟了 shell 選項(xiàng)很容易被路徑里的空格或特殊字符坑到。統(tǒng)一走 execa 之后這類問(wèn)題基本不再出現(xiàn)。5.3 依賴安裝超時(shí)和內(nèi)網(wǎng)源問(wèn)題生成項(xiàng)目之后的第一道坎往往就是 npm install。網(wǎng)絡(luò)環(huán)境不穩(wěn)定的時(shí)候安裝一個(gè)中等規(guī)模的項(xiàng)目動(dòng)輒幾十秒超過(guò)默認(rèn)超時(shí)時(shí)間就會(huì)失敗。t3code 把超時(shí)做成了可配置項(xiàng)同時(shí)在 init 命令里提供了一個(gè) -r 參數(shù)直接指定 npm registry。這個(gè)參數(shù)很實(shí)用比如在受限網(wǎng)絡(luò)環(huán)境下用戶可以傳一個(gè)鏡像地址不用去改全局 .npmrc。還有一個(gè)容易被忽略的細(xì)節(jié)如果用戶已經(jīng)配置了 .npmrc 里的 registryexeca 啟動(dòng) npm 時(shí)會(huì)自動(dòng)讀到這個(gè)配置。這個(gè)行為有好有壞。好的方面是用戶不需要額外配置壞的方面是如果用戶配了一個(gè)錯(cuò)誤的鏡像地址安裝失敗后第一時(shí)間不會(huì)懷疑 .npmrc而會(huì)認(rèn)為是 t3code 的問(wèn)題。我在安裝失敗的錯(cuò)誤信息里加了一行提示提醒用戶檢查 .npmrc 中的 registry 配置。這條提示幫我擋掉了不少重復(fù)的 issue也讓用戶排查問(wèn)題的路徑短了很多。5.4 模板分發(fā)與版本錯(cuò)配的教訓(xùn)t3code 的模板存儲(chǔ)在 npm 包內(nèi)模板和 CLI 代碼共享版本號(hào)。對(duì)于小項(xiàng)目來(lái)說(shuō)這個(gè)方案夠用但模板數(shù)量上來(lái)之后就會(huì)出現(xiàn)代碼沒(méi)變、模板更新也要發(fā)版本的情況。目前我的處理是遵循語(yǔ)義化版本規(guī)范模板改動(dòng)如果只是內(nèi)容層面的變化發(fā) minor 版本模板數(shù)據(jù)結(jié)構(gòu)變化比如 manifest.json 格式調(diào)整發(fā) major 版本。同時(shí)我做了一個(gè)雖然簡(jiǎn)單但非常有用的機(jī)制doctor 命令會(huì)檢查當(dāng)前 CLI 版本與最新版本之間的差異如果差異過(guò)大就提示用戶升級(jí)。這個(gè)檢查不是為了騷擾用戶而是因?yàn)槟０搴?CLI 強(qiáng)耦合版本不對(duì)齊會(huì)生成錯(cuò)誤的內(nèi)容。這個(gè)設(shè)計(jì)是真實(shí)事故換來(lái)的。有一次用戶用舊版 CLI 搭配新模板生成出來(lái)的 package.json 里引用了一個(gè)不存在的腳本排查了很久才發(fā)現(xiàn)是版本錯(cuò)配。現(xiàn)在 doctor 命令會(huì)在用戶跑 init 之前先做版本檢查不一致時(shí)給出明確提示。6. 后續(xù)擴(kuò)展的方向工具的生命力在于被真實(shí)使用最后聊一聊我接下來(lái)想做的事。t3code 目前的形態(tài)已經(jīng)能解決團(tuán)隊(duì)的日常問(wèn)題但它距離我理想中的工程基線工具還有一段路。我自己打算按下面幾個(gè)方向慢慢推進(jìn)也寫出來(lái)給大家做個(gè)參考。6.1 插件機(jī)制當(dāng)前可選區(qū)塊是寫在 manifest.json 里的靜態(tài)聲明數(shù)據(jù)和邏輯都不夠靈活。如果支持插件讓第三方通過(guò)一個(gè)鉤子函數(shù)注入自定義渲染邏輯t3code 就能變成一個(gè)更通用的工程能力平臺(tái)。比如有人做了一套企業(yè)級(jí)日志方案寫一個(gè)插件任何人在生成項(xiàng)目時(shí)都能一鍵接入。這個(gè)方向投入不小目前優(yōu)先級(jí)不算最高但長(zhǎng)期來(lái)看是讓工具突破單團(tuán)隊(duì)自用邊界的關(guān)鍵。6.2 模板遠(yuǎn)程化現(xiàn)在模板打包在 CLI 包里每次想加模板都要發(fā)一個(gè)版本。如果模板能放在 Git 倉(cāng)庫(kù)里CLI 通過(guò) URL 直接拉取指定 tag 的模板那么團(tuán)隊(duì)里的非前端同學(xué)也能通過(guò)維護(hù)倉(cāng)庫(kù)來(lái)更新模板完全不碰 CLI 代碼。這一步能把模板即代碼的理念貫徹得更徹底也是我比較看好的方向。6.3 生成后自動(dòng)校驗(yàn)?zāi)壳?t3code 生成完項(xiàng)目后只做了依賴安裝沒(méi)有對(duì)生成產(chǎn)物做深度校驗(yàn)。我打算加一個(gè) post-init 鉤子在目標(biāo)目錄里自動(dòng)跑一遍 typecheck 和 lint如果失敗直接指出哪些模板文件有問(wèn)題。這個(gè)能力的價(jià)值在于模板作者改完模板后能立刻知道模板本身引入了編譯錯(cuò)誤而不是等用戶創(chuàng)建項(xiàng)目之后才發(fā)現(xiàn)。6.4 更多項(xiàng)目模板t3code 的核心價(jià)值是 T3 技術(shù)棧的工程化基線但同樣的機(jī)制完全可以用于生成 NestJS 后端項(xiàng)目、React Native 項(xiàng)目甚至純 npm 庫(kù)的基線。底層邏輯都是一樣的交互收集參數(shù)、模板渲染、收尾動(dòng)作變的只是模板內(nèi)容。這個(gè)方向不復(fù)雜主要看團(tuán)隊(duì)實(shí)際需求什么時(shí)候出現(xiàn)。根據(jù)我個(gè)人的體會(huì)腳手架工具最怕的不是功能少而是功能沒(méi)人用。t3code 從立項(xiàng)到現(xiàn)在最大的收獲不是代碼量而是逼著我把團(tuán)隊(duì)里很多默認(rèn)大家都知道的工程約定寫成了文檔化的、可驗(yàn)證的模板。這個(gè)過(guò)程中很多原本模糊的規(guī)范變得清晰了很多原本靠口頭傳授的經(jīng)驗(yàn)變成了代碼。如果你也在維護(hù)團(tuán)隊(duì)的工程基建我真心建議試一次把自己的腳手架工具寫出來(lái)哪怕只服務(wù)三個(gè)人它帶來(lái)的規(guī)范沉淀也比任何現(xiàn)成工具都值。 從零自研T3技術(shù)棧腳手架：t3code的工程化實(shí)踐與踩坑記錄
1. 項(xiàng)目緣起放著現(xiàn)成腳手架不用我為什么自己寫了 t3code大概半年前我開(kāi)始動(dòng)手寫 t3code 這個(gè)項(xiàng)目——一個(gè)基于 T3 技術(shù)棧TypeScript、Tailwind CSS、tRPC 加 Next.js的項(xiàng)目腳手架生成工具。起因特別簡(jiǎn)單團(tuán)隊(duì)里新項(xiàng)目初始化太慢每次手動(dòng)補(bǔ)齊的內(nèi)容都一模一樣重復(fù)勞動(dòng)多了人就容易產(chǎn)生干脆寫個(gè)工具把這事自動(dòng)化的沖動(dòng)。t3code 這個(gè)名字沒(méi)花什么心思T3 棧加 code 生成器拆開(kāi)念就是 t3-code順手就在 npm 上搜了一下沒(méi)有重名直接發(fā)布。1.1 從 T3 技術(shù)棧說(shuō)起先給不熟悉的讀者簡(jiǎn)單交代一下背景。T3 技術(shù)棧是這幾年在 React 全棧開(kāi)發(fā)里很流行的一套組合TypeScript 提供類型安全Tailwind CSS 負(fù)責(zé)樣式tRPC 讓你在不寫 REST 接口文檔的情況下實(shí)現(xiàn)前后端類型共享應(yīng)用框架用的是 Next.js。這個(gè)組合最大的好處是端到端類型安全——你改一個(gè)后端返回字段的類型前端編輯器里立刻就能報(bào)錯(cuò)不用等聯(lián)調(diào)。我第一次用 create-t3-app 拉起項(xiàng)目的時(shí)候體驗(yàn)確實(shí)很好幾分鐘就能得到一個(gè)帶完整 tRPC 鏈路和 Tailwind 樣板的工程。但用得多了問(wèn)題就浮出來(lái)了。create-t3-app 是大眾的腳手架它的默認(rèn)配置面向最通用的場(chǎng)景而團(tuán)隊(duì)工程實(shí)踐一旦有自己的約定這套默認(rèn)配置就不夠用了。我們團(tuán)隊(duì)的要求包括每個(gè)新項(xiàng)目必須帶 docs 目錄、必須用 pnpm 而不是 npm、ESLint 必須開(kāi) import 排序規(guī)則、依賴要鎖定精確版本號(hào)、必須包含 .env.example 模板、CI 腳本要用統(tǒng)一的 Node 版本。這些約定說(shuō)多不多說(shuō)少不少每次初始化完 create-t3-app 都要手動(dòng)改一遍改完還要手動(dòng)建目錄、拷公共工具函數(shù)。一次兩次能忍十次二十次就非常煩躁了。我還見(jiàn)過(guò)更糟的情況有同事初始化完項(xiàng)目以后忘了補(bǔ) .env.example直接把帶真實(shí)數(shù)據(jù)庫(kù)連接串的配置提交到了倉(cāng)庫(kù)雖然最后及時(shí)改了回來(lái)但這種風(fēng)險(xiǎn)不應(yīng)該靠人的記憶力去兜底。所以我的核心訴求非常清楚要把團(tuán)隊(duì)自己的工程約定固化成一個(gè)可復(fù)現(xiàn)的腳本讓新建一個(gè)符合團(tuán)隊(duì)規(guī)范的 T3 項(xiàng)目從半小時(shí)縮減到兩分鐘。t3code 就是在這個(gè)背景下誕生的。1.2 現(xiàn)成腳手架的三個(gè)痛點(diǎn)在決定自研之前我把市面上能找的腳手架都過(guò)了一遍包括 create-t3-app、create-next-app、各種社區(qū)模板倉(cāng)庫(kù)。它們的痛點(diǎn)歸納起來(lái)有三個(gè)。第一模板不可定制或定制成本高。create-t3-app 雖然提供了不少配置選項(xiàng)但它不開(kāi)放模板機(jī)制你想加自己的 CI 腳本、自己的工具函數(shù)目錄只能生成之后手動(dòng)改。社區(qū)模板倉(cāng)庫(kù)倒是可以 fork但 fork 之后每次上游更新都要手動(dòng)合并追版本追得心累。第二團(tuán)隊(duì)約定無(wú)法沉淀。腳手架工具本質(zhì)上是工程經(jīng)驗(yàn)的載體但現(xiàn)成工具承載的是作者的工程經(jīng)驗(yàn)不是你的。團(tuán)隊(duì)里的目錄規(guī)范、代碼風(fēng)格、提交規(guī)范、環(huán)境變量管理方式這些只有自己人最清楚指望一個(gè)社區(qū)工具替你管理根本不現(xiàn)實(shí)。第三生成產(chǎn)物黑盒。很多腳手架生成完之后用戶對(duì)項(xiàng)目里每一份文件的出處一無(wú)所知。出了問(wèn)題只能整個(gè)刪掉重建沒(méi)辦法針對(duì)性地修某一處模板邏輯。對(duì)于需要長(zhǎng)期維護(hù)的團(tuán)隊(duì)工程基線來(lái)說(shuō)這不是小事。1.3 我想要的工程化基線因此我給 t3code 定下的目標(biāo)很明確它不是一個(gè)通用的代碼生成器而是團(tuán)隊(duì)工程化基線的一個(gè)載體。具體要做到四件事——交互收集參數(shù)、拷貝模板文件、渲染動(dòng)態(tài)內(nèi)容、執(zhí)行收尾動(dòng)作。后面所有設(shè)計(jì)決策都是圍繞這四件事展開(kāi)的。范圍定小了復(fù)雜度自然就下來(lái)了核心邏輯加起來(lái)不到一千行剩下全是模板代碼。這篇文章會(huì)把設(shè)計(jì)思路、核心實(shí)現(xiàn)和踩坑記錄完整寫出來(lái)。如果你在團(tuán)隊(duì)里做前端基建或者想給自己的團(tuán)隊(duì)落地一套內(nèi)部腳手架又或者只是好奇一個(gè) CLI 工具是怎么從零做出來(lái)的應(yīng)該都能從中找到一些可以復(fù)用的經(jīng)驗(yàn)。內(nèi)容不需要多高深Node.js 基礎(chǔ)加一點(diǎn)模板引擎知識(shí)就能看懂。2. 整體設(shè)計(jì)思路腳手架工具要解決的四個(gè)問(wèn)題2.1 先想清楚t3code 不是什么比它是什么更重要?jiǎng)邮种拔易龅淖钪匾囊患率墙o自己劃界線。t3code 不是低代碼平臺(tái)不是代碼生成器更不是要替代 create-t3-app 的通用方案。它就是項(xiàng)目初始化加速器把創(chuàng)建項(xiàng)目過(guò)程中的重復(fù)勞動(dòng)壓縮成一條命令。這個(gè)定位聽(tīng)起來(lái)簡(jiǎn)單但它直接影響后面每一個(gè)設(shè)計(jì)選擇范圍不擴(kuò)大復(fù)雜度就可控模板只在團(tuán)隊(duì)內(nèi)部用就不需要做復(fù)雜的遠(yuǎn)程拉取用戶都是有經(jīng)驗(yàn)的開(kāi)發(fā)者就不需要做圖形化界面。明確了定位之后核心功能就清晰了。t3code 做的事包括四件第一交互收集參數(shù)包括項(xiàng)目名、包名、是否啟用 CI、是否初始化 Git、選擇哪個(gè)業(yè)務(wù)模板第二拷貝模板文件把內(nèi)置模板目錄完整復(fù)制到目標(biāo)目錄第三渲染動(dòng)態(tài)內(nèi)容把項(xiàng)目名、版本號(hào)、npm registry 地址等變量替換進(jìn)模板文件第四執(zhí)行收尾動(dòng)作自動(dòng)安裝依賴、初始化 Git、打印啟動(dòng)命令。這四件事每一件拆開(kāi)都不復(fù)雜但組合起來(lái)加上各種邊緣情況的處理就是完整的工具了。我見(jiàn)過(guò)不少腳手架工具交互做得很花哨結(jié)果復(fù)制文件時(shí)不處理隱藏文件、不處理 .gitignore生成出來(lái)的項(xiàng)目根本不是用戶預(yù)期的樣子。所以 t3code 從第一天起就刻意保持小體積小到核心邏輯出了問(wèn)題能一眼定位。2.2 技術(shù)選型為什么是 Node.js Commander而不是 Go、Rust 或 Shell選型這件事我糾結(jié)過(guò)兩天。做一個(gè)腳手架工具擺面前有幾條路。第一條是用 Go 或 Rust 寫編譯型二進(jìn)制優(yōu)點(diǎn)是沒(méi)有運(yùn)行時(shí)依賴、啟動(dòng)速度快可以做成一條命令直接放在任意機(jī)器上跑但缺點(diǎn)是模板分發(fā)麻煩模板如果打包進(jìn)二進(jìn)制那么每改一次模板就要重新編譯團(tuán)隊(duì)里非 Go 開(kāi)發(fā)者想貢獻(xiàn)模板要先裝工具鏈這門檻對(duì)前端團(tuán)隊(duì)來(lái)說(shuō)太高了。第二條路是寫 Shell 腳本。簡(jiǎn)單場(chǎng)景下 Shell 完全夠用比如 mkdir、cp、sed 一把梭。但只要涉及到交互式問(wèn)答、跨平臺(tái)路徑處理、JSON 變量替換、錯(cuò)誤重試這些操作Shell 很快就會(huì)變成一團(tuán)亂麻。尤其是 macOS 的 zsh 和 Linux 的 bash 行為還有差異Windows 更是直接勸退。第三條路是用 Node.js 寫一個(gè) npm 包類型的 CLI這也是我最終的選擇。原因很實(shí)際團(tuán)隊(duì)里前端工程師人人都有 Node 環(huán)境npx t3code 一條命令就能跑起來(lái)模板直接打包在 npm 包里發(fā)布新模板就是發(fā)一個(gè)新版本包。模板文件對(duì)前端工程師來(lái)說(shuō)是純文本改起來(lái)沒(méi)有任何額外學(xué)習(xí)成本。Node.js 生態(tài)里 Commander、Inquirer、execa、Handlebars 這些庫(kù)都是久經(jīng)考驗(yàn)的完全不用重新造輪子。最終 t3code 的依賴清單如下commander命令行參數(shù)解析。inquirer交互式問(wèn)答。handlebars模板渲染。execa子進(jìn)程執(zhí)行安裝依賴、git 命令。fs-extra遞歸拷貝和文件操作。每個(gè)庫(kù)都放在自己最擅長(zhǎng)的位置上。commander 負(fù)責(zé)參數(shù)inquirer 負(fù)責(zé)問(wèn)答handlebars 負(fù)責(zé)渲染execa 負(fù)責(zé)外部命令fs-extra 負(fù)責(zé)文件系統(tǒng)操作。依賴雖然不少但沒(méi)有一個(gè)是可有可無(wú)的。2.3 模板目錄結(jié)構(gòu)約定優(yōu)于配置配置優(yōu)于代碼t3code 的模板不是簡(jiǎn)單的一堆文件它有明確的兩層結(jié)構(gòu)。第一層是項(xiàng)目級(jí)模板比如 next-trpc、next-plain、library每個(gè)模板對(duì)應(yīng)一類項(xiàng)目形態(tài)第二層是模板內(nèi)部的可選區(qū)塊比如某個(gè)模板里可以選擇是否生成 GitHub Actions 工作流、是否生成 Dockerfile。這么設(shè)計(jì)是為了讓按需生成成為可能同時(shí)不讓這種靈活性泛濫成災(zāi)。模板目錄的結(jié)構(gòu)大致是這樣的templates/ ├── next-trpc/ │ ├── base/ │ │ ├── .env.example │ │ ├── .eslintrc.cjs │ │ ├── package.json.j2 │ │ ├── tsconfig.json │ │ ├── next.config.mjs │ │ ├── src/ │ │ └── README.md.j2 │ ├── optional/ │ │ ├── ci-github/ │ │ ├── docker/ │ │ └── monorepo/ │ └── manifest.json ├── next-plain/ └── library/base 目錄下的文件是必選內(nèi)容optional 目錄下都是可選的增量文件。manifest.json 聲明了這個(gè)模板支持哪些可選區(qū)塊、哪些文件需要渲染、默認(rèn)推薦選項(xiàng)是什么。模板里以 .j2 結(jié)尾的文件表示需要經(jīng)過(guò) Handlebars 渲染其他文件一律原樣拷貝。這個(gè)約定的好處是模板作者一眼就能看出哪些文件會(huì)被動(dòng)態(tài)處理哪些不會(huì)。模板即代碼是我在這個(gè)項(xiàng)目里最堅(jiān)持的原則。業(yè)務(wù)方想加一段自定義配置不需要改 t3code 的源碼只需要在 templates 目錄下新增一個(gè) optional 區(qū)塊然后更新 manifest.json 的描述文案。后來(lái)我們團(tuán)隊(duì)干脆把模板倉(cāng)庫(kù)單獨(dú)拆了出去通過(guò) git submodule 的方式在發(fā)版本時(shí)同步進(jìn)主倉(cāng)庫(kù)模板的維護(hù)和 CLI 代碼的維護(hù)徹底解耦。這一步讓我體會(huì)到模板結(jié)構(gòu)設(shè)計(jì)得清晰很多后續(xù)的流程問(wèn)題都會(huì)自動(dòng)消失。3. 核心實(shí)現(xiàn)拆解從用戶輸入到項(xiàng)目落地的完整鏈路3.1 入口命令與參數(shù)解析t3code 的命令入口是 package.json 的 bin 字段指向的 JS 文件。我用 Commander 定義了三個(gè)子命令init 是交互式創(chuàng)建項(xiàng)目list 列出所有可用模板doctor 檢查當(dāng)前環(huán)境是否滿足生成條件。三個(gè)命令各有定位init 是日常主力list 讓用戶知道有哪些選擇doctor 則是排障專用的環(huán)境有問(wèn)題時(shí)先跑一下它。下面貼 init 命令的解析邏輯這是整個(gè)工具的主入口#!/usr/bin/env node const { Command } require(commander); const program new Command(); program .name(t3code) .description(T3 技術(shù)棧項(xiàng)目腳手架生成器) .version(1.4.2); program .command(init) .description(初始化一個(gè) T3 項(xiàng)目) .argument([projectName], 項(xiàng)目目錄名稱例如 my-app) .option(-t, --template name, 指定模板例如 next-trpc) .option(--no-git, 跳過(guò) git init) .option(--no-install, 跳過(guò)依賴安裝) .option(-r, --registry url, 指定 npm registry 地址) .action((projectName, options) { runInit(projectName, options).catch((err) { console.error([t3code] 初始化失敗:, err.message); process.exit(1); }); }); program.parse(process.argv);Commander 的 argument 和 option 分離得很清晰。項(xiàng)目名是位置參數(shù)可以寫在命令后面模板、registry 等是選項(xiàng)參數(shù)用短橫線語(yǔ)法傳。這里我考慮過(guò)要不要加一個(gè) --yes 參數(shù)跳過(guò)所有交互直接使用默認(rèn)值后來(lái)決定不支持。原因是我見(jiàn)過(guò)太多腳手架默認(rèn)值藏在文檔里用戶完全不知道自己在用什么。t3code 面向的是有一定經(jīng)驗(yàn)的開(kāi)發(fā)者把關(guān)鍵選項(xiàng)問(wèn)清楚比快速跳過(guò)重要得多。3.2 交互式問(wèn)答把決策放在用戶眼前把校驗(yàn)做在輸入之前如果用戶沒(méi)有在命令行里指定項(xiàng)目名或模板init 流程就會(huì)進(jìn)入 Inquirer 的問(wèn)答環(huán)節(jié)。我把問(wèn)答分成兩層第一層是項(xiàng)目基本信息第二層是根據(jù) manifest.json 動(dòng)態(tài)生成的可選區(qū)塊問(wèn)題。第一層的問(wèn)題非常直接但校驗(yàn)必須嚴(yán)格。比如項(xiàng)目名的校驗(yàn)const basicQuestions [ { type: input, name: projectName, message: 項(xiàng)目目錄名稱:, validate: (input) { if (!input.trim()) return 項(xiàng)目名不能為空; if (!/^[a-z0-9-]$/.test(input)) return 只能包含小寫字母、數(shù)字和中劃線; return true; }, }, { type: input, name: packageName, message: npm 包名默認(rèn)與項(xiàng)目名一致:, default: (answers) answers.projectName, validate: (input) { if (!/^[a-z0-9-]$/.test(input)) return 包名只能包含小寫字母、數(shù)字和中劃線; return true; }, }, ];這個(gè)校驗(yàn)規(guī)則是我踩坑踩出來(lái)的。第一版只做了非空校驗(yàn)結(jié)果有同事輸入了中文項(xiàng)目名后面生成的 next.config.mjs 直接被 Node.js 解析報(bào)錯(cuò)還得手動(dòng)改一堆文件名。從那之后所有用戶輸入都必須過(guò)規(guī)則校驗(yàn)。寧可在 prompt 階段多問(wèn)一遍也不要在生成之后返工。正則限定得嚴(yán)一點(diǎn)沒(méi)有壞處因?yàn)轫?xiàng)目名和包名都會(huì)進(jìn)入后續(xù)的模板變量一旦出現(xiàn)非法字符問(wèn)題往往不止一處。第二層問(wèn)題來(lái)自模板的 manifest.json。比如模板聲明了 ci-github 這個(gè)可選區(qū)塊init 流程就會(huì)自動(dòng)生成一個(gè)確認(rèn)類型的問(wèn)題是否生成 GitHub Actions 工作流。這層邏輯雖然只用了幾行代碼但它的意義在于模板能力擴(kuò)展不再需要修改代碼只要改 manifest.json交互層就是通用的。3.3 模板渲染為什么選 Handlebars而不是字符串拼接模板渲染是整個(gè)工具的技術(shù)核心。最初我想過(guò)最簡(jiǎn)單的方式在模板里寫PROJECT_NAME之類的占位符然后用字符串 replace 替換成實(shí)際值。這個(gè)方案實(shí)現(xiàn)最快但有一個(gè)致命問(wèn)題——如果配置內(nèi)容需要根據(jù)用戶選項(xiàng)條件性地出現(xiàn)字符串拼接就完全無(wú)力了。舉個(gè)例子package.json 里如果用戶選擇了 Docker 區(qū)塊scripts 里就要多一個(gè) docker:build 命令如果選擇了 CI 區(qū)塊devDependencies 里就要多幾個(gè)包。用字符串拼接去組織這些條件邏輯代碼會(huì)迅速腐爛。所以我改用 Handlebars。它有三個(gè)好處語(yǔ)法簡(jiǎn)單模板作者不需要學(xué)一門新語(yǔ)言原生支持 #if 條件判斷和 #each 循環(huán)覆蓋了我 99% 的需求有完整的轉(zhuǎn)義機(jī)制不會(huì)出現(xiàn)模板變量破壞 JSON 格式的問(wèn)題。下面是一個(gè)真實(shí)模板片段來(lái)自 next-trpc 模板的 package.json.j2{ name: {{packageName}}, version: 0.1.0, scripts: { dev: next dev, build: next build, start: next start, lint: next lint, {{#if withDocker}} docker:build: docker build -t {{projectName}}:latest ., {{/if}} typecheck: tsc --noEmit }, devDependencies: { typescript: ^5.4.0, tailwindcss: ^3.4.0, eslint: ^8.57.0, eslint-config-next: ^14.1.0, {{#if withCI}} changesets/cli: ^2.27.0, {{/if}} eslint-plugin-tailwindcss: ^0.5.0 } }渲染的時(shí)候把前面收集到的所有答案整理成一個(gè)大的 context 對(duì)象傳給 Handlebars 編譯之后的函數(shù)const Handlebars require(handlebars); const context { projectName: my-app, packageName: my-app, withDocker: true, withCI: false, author: your-name, registry: https://registry.npmjs.org, }; const source await fs.readFile(templateFile, utf-8); const render Handlebars.compile(source); const output render(context);這里有一個(gè)我從實(shí)際使用中總結(jié)出來(lái)的關(guān)鍵經(jīng)驗(yàn)?zāi)０逦募彩?.json 結(jié)尾的渲染完成之后必須通過(guò) JSON.parse 校驗(yàn)才能落盤。因?yàn)?Handlebars 的 #if 塊如果縮進(jìn)或者逗號(hào)位置處理不當(dāng)很容易在 JSON 文件里多出一個(gè)逗號(hào)或者少一個(gè)閉合括號(hào)。我在 renderFile 函數(shù)里加了一個(gè)鉤子如果源文件擴(kuò)展名是 .json渲染結(jié)果必須 JSON.parse 成功否則直接報(bào)錯(cuò)并且把渲染結(jié)果連同原始模板一起打印出來(lái)。這個(gè)鉤子幫我攔下了很多模板編寫不規(guī)范的問(wèn)題。3.4 文件落盤與目錄創(chuàng)建最容易翻車的環(huán)節(jié)渲染完成之后就該寫文件了。這個(gè)環(huán)節(jié)看起來(lái)最沒(méi)有技術(shù)含量實(shí)際上最容易翻車。我用 fs-extra 的 copy 方法先把模板目錄完整復(fù)制到目標(biāo)目錄然后逐文件處理渲染。注意順序很重要先復(fù)制再渲染可以保證非模板文件比如圖片、字體、二進(jìn)制文件也能被原樣帶上如果先渲染再?gòu)?fù)制二進(jìn)制文件可能會(huì)在讀寫過(guò)程中損壞。核心代碼如下const fse require(fs-extra); await fse.copy(templateBaseDir, targetDir, { filter: (src) !src.includes(node_modules), }); // 遍歷目標(biāo)目錄渲染所有 .j2 結(jié)尾的文件 const files await findAllJ2Files(targetDir); for (const file of files) { const rendered await renderTemplateFile(file, context); const outputPath file.replace(/\.j2$/, ); await fse.outputFile(outputPath, rendered); await fse.remove(file); }有幾個(gè)細(xì)節(jié)必須強(qiáng)調(diào)。第一遍歷文件時(shí)要用 fs.readdir 的 withFileTypes 參數(shù)判斷目錄類型不能用簡(jiǎn)單的字符串包含判斷否則遇到名字里帶點(diǎn)的目錄比如 .next、.github會(huì)誤判成文件。第二隱藏文件在 copy 階段是正常處理的但如果你選了某些第三方復(fù)制庫(kù)要確認(rèn)它的過(guò)濾邏輯不會(huì)把隱藏文件丟掉。第三目標(biāo)目錄如果已經(jīng)存在且非空init 命令應(yīng)該直接拒絕執(zhí)行必須加一個(gè) --force 選項(xiàng)才能覆蓋。這個(gè)保護(hù)非常重要我因?yàn)樵缙谕藢戇@個(gè)檢查曾經(jīng)把同事一個(gè)正在開(kāi)發(fā)的目錄直接覆蓋了。項(xiàng)目?jī)?nèi)容沒(méi)丟但那次經(jīng)歷絕對(duì)不想再來(lái)一次。3.5 依賴安裝與 Git 初始化外部命令的靜默陷阱文件生成完畢最后一步是安裝依賴和初始化 Git。這里我用了 execa 而不是 Node.js 自帶的 child_process.exec原因是 execa 對(duì) Windows 的支持更好還支持超時(shí)時(shí)間和 stdio 模式設(shè)置。以下是依賴安裝和 Git 初始化的代碼const execa require(execa); async function installDependencies(targetDir, { registry }) { const args [install]; if (registry) { args.push(--registry, registry); } const subprocess execa(npm, args, { cwd: targetDir, stdio: inherit, timeout: 120000, }); try { await subprocess; } catch (err) { throw new Error(依賴安裝失敗: ${err.message}); } } async function initGit(targetDir) { if (!(await fse.exists(path.join(targetDir, .git)))) { await execa(git, [init, -b, main], { cwd: targetDir }); await execa(git, [add, .], { cwd: targetDir }); await execa(git, [commit, -m, chore: init project via t3code], { cwd: targetDir, }).catch(() { // 如果用戶全局 git 配置不全缺 name/emailcommit 會(huì)失敗 // 這里不做強(qiáng)制只留下提示 console.warn([t3code] 自動(dòng) commit 失敗請(qǐng)檢查 git 用戶配置); }); } }git init 之后要不要自動(dòng) commit我猶豫過(guò)。自動(dòng) commit 的好處是用戶拿到的是一個(gè)干凈的工作區(qū)可以直接開(kāi)新分支寫代碼壞處是如果用戶的全局 git 配置不全commit 失敗會(huì)中斷整個(gè)流程。后來(lái)我做了容錯(cuò)處理commit 失敗只打印警告不阻塞流程。同時(shí)用戶也可以用 --no-git 完全跳過(guò) Git 相關(guān)操作。依賴安裝這里我特意保留了 stdio: inherit讓 npm 的安裝日志直接打到終端上。有些腳手架喜歡把安裝過(guò)程藏起來(lái)只顯示一個(gè) spinner但實(shí)際經(jīng)驗(yàn)是安裝卡住的時(shí)候用戶最需要原始進(jìn)度信息。寧可輸出丑一點(diǎn)也要讓用戶知道它到底卡在哪一步。npm install 超過(guò)兩分鐘超時(shí)之后錯(cuò)誤信息會(huì)包含具體命令的完整輸出這比安裝失敗四個(gè)字有用得多。4. 實(shí)測(cè)過(guò)程從一條命令到完整可用的 T3 項(xiàng)目4.1 完整跑一遍 t3code init我拿一臺(tái)配置干凈的新電腦做了一次完整實(shí)測(cè)確保從空目錄到項(xiàng)目跑起來(lái)沒(méi)有斷點(diǎn)。執(zhí)行命令npx t3code init my-app -t next-trpc由于指定了模板交互問(wèn)答會(huì)自動(dòng)跳過(guò)模板選擇剩下的問(wèn)題只有四個(gè)npm 包名、是否生成 Dockerfile、是否生成 CI 工作流、是否自動(dòng)執(zhí)行依賴安裝和 git init。這四個(gè)問(wèn)題的默認(rèn)值我都做了認(rèn)真設(shè)計(jì)包名默認(rèn)等于項(xiàng)目名Dockerfile 默認(rèn)不生成CI 默認(rèn)生成安裝和 git init 默認(rèn)執(zhí)行。默認(rèn)值的選取原則是多數(shù)場(chǎng)景下不需要改而不是保守選項(xiàng)避免出錯(cuò)。選擇完成之后大概過(guò)了一分多鐘大部分時(shí)間是 npm install 在跑。等命令結(jié)束我用 tree 命令看了一眼生成的項(xiàng)目結(jié)構(gòu)my-app/ ├── .env.example ├── .eslintrc.cjs ├── .github/workflows/ci.yml ├── .gitignore ├── README.md ├── next.config.mjs ├── package.json ├── pnpm-lock.yaml ├── postcss.config.cjs ├── tailwind.config.ts ├── tsconfig.json └── src/ ├── app/ │ ├── api/trpc/[trpc]/route.ts │ ├── layout.tsx │ ├── page.tsx │ └── globals.css ├── server/api/root.ts ├── server/api/routers/post.ts ├── trpc/react.tsx └── trpc/server.ts然后執(zhí)行 npm run dev本機(jī) 3000 端口直接起了一個(gè)帶有 tRPC 完整鏈路的 Next.js 項(xiàng)目。從 React 組件到后端路由全類型安全新項(xiàng)目的第一個(gè) commit 就已經(jīng)是一個(gè)可以開(kāi)發(fā)的起點(diǎn)。整個(gè)流程走完我的感受是工具的價(jià)值不在于它生成了多少文件而在于它把想清楚再動(dòng)手這件事變成了默認(rèn)行為。新項(xiàng)目一創(chuàng)建目錄規(guī)范、命名規(guī)范、環(huán)境變量管理、CI 檢查全部就位。4.2 驗(yàn)證生成內(nèi)容的核心鏈路類型和 CI 都要真的能跑光能跑起來(lái)還不算數(shù)我特意做了兩件驗(yàn)證工作。第一件是驗(yàn)證端到端類型安全是否真的成立。我在 src/trpc/react.tsx 里調(diào)用 useQuery 獲取數(shù)據(jù)然后故意把服務(wù)端 router 返回的字段類型改掉編輯器里立刻出現(xiàn)了類型錯(cuò)誤。這說(shuō)明 tRPC 的端到端類型推斷在生成的樣板工程里是通的。這個(gè)驗(yàn)證很重要因?yàn)?t3code 的核心賣點(diǎn)之一就是類型安全如果模板里某個(gè)配置文件版本不匹配導(dǎo)致類型推斷斷裂整個(gè)項(xiàng)目的開(kāi)發(fā)體驗(yàn)會(huì)大打折扣。第二件是驗(yàn)證 CI 腳本能真正跑通。我把生成出來(lái)的 .github/workflows/ci.yml 放進(jìn)一個(gè) GitHub 倉(cāng)庫(kù)里觸發(fā)了一次流水線確認(rèn) lint、typecheck、build 三個(gè)步驟都能通過(guò)并且用的是模板里鎖定的 Node 版本。這兩項(xiàng)驗(yàn)證幫我發(fā)現(xiàn)了一個(gè)暗處的問(wèn)題模板里 .env.example 的 DATABASE_URL 用的是本地 localhost 默認(rèn)值但 CI 環(huán)境里根本沒(méi)有這個(gè)數(shù)據(jù)庫(kù)所以 CI 腳本里所有依賴數(shù)據(jù)庫(kù)的步驟我都提前加上了注釋用戶需要按自己的實(shí)際情況調(diào)整。這個(gè)問(wèn)題不算是 bug但它體現(xiàn)了模板作者該有的自覺(jué)——模板里必須留下足夠的注釋明確告訴使用者哪些地方必須改。4.3 參數(shù)化細(xì)節(jié)版本號(hào)為什么要統(tǒng)一管理生成出來(lái)的 package.json 里依賴版本號(hào)是精確鎖定的。這個(gè)決策當(dāng)時(shí)有同事反對(duì)覺(jué)得應(yīng)該用 latest 或者 ^ 前綴讓 npm 自動(dòng)解析到最新版。我堅(jiān)持用精確版本號(hào)原因很簡(jiǎn)單腳手架生成的項(xiàng)目是團(tuán)隊(duì)的長(zhǎng)期基線如果每次生成都拉到最新版某天某個(gè)依賴升級(jí)引入了 breaking change所有新項(xiàng)目同時(shí)中招問(wèn)題定位成本會(huì)非常高。精確鎖定版本讓升級(jí)這件事發(fā)生在可控的時(shí)間點(diǎn)比自動(dòng)最新穩(wěn)定得多。為此我在模板引擎里做了一個(gè)擴(kuò)展context 里注入一個(gè) versions 對(duì)象所有依賴版本都從一份統(tǒng)一的 versions.json 讀取。每次升級(jí)基礎(chǔ)依賴只需要改 versions.json 然后發(fā)布一個(gè)新版 t3code不用在一堆模板文件里翻找版本號(hào)。這是單一數(shù)據(jù)源原則在腳手架里的實(shí)際落地它保證了團(tuán)隊(duì)所有新項(xiàng)目用的基礎(chǔ)依賴版本完全一致不會(huì)出現(xiàn)張三的新項(xiàng)目用 React 18李四的新項(xiàng)目還在用 React 17 這種混亂情況。{ next: 14.1.0, react: 18.2.0, react-dom: 18.2.0, trpc/server: 10.45.0, trpc/client: 10.45.0, trpc/react-query: 10.45.0, trpc/next: 10.45.0, typescript: 5.4.0, tailwindcss: 3.4.1 }模板里引用版本號(hào)時(shí)寫成這樣{ dependencies: { next: {{versions.next}}, react: {{versions.react}}, trpc/server: {{versions.trpc-server}} } }versions.json 里的 key 和模板里的引用并不是靠約定來(lái)保證一致的我加了一個(gè)配套的單元測(cè)試模板文件里出現(xiàn)的所有 versions.xxx 引用必須在 versions.json 里有對(duì)應(yīng)定義否則測(cè)試直接失敗。這個(gè)測(cè)試是我踩了一次大坑之后才補(bǔ)上的。有一次我刪掉了某個(gè)不再需要的依賴版本定義但忘了模板里還在引用發(fā)布出去的版本生成的項(xiàng)目依賴直接失效排查了很久才定位到是版本錯(cuò)配。從那以后凡是模板和數(shù)據(jù)源之間的引用關(guān)系一律用自動(dòng)化測(cè)試兜底不再靠人肉記憶。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 模板渲染后 JSON 格式被破壞這是 t3code 用戶反饋?zhàn)疃嗟囊活悊?wèn)題。Handlebars 的 #if 塊在 JSON 文件里非常脆弱只要縮進(jìn)或者逗號(hào)位置不對(duì)渲染結(jié)果就是非法 JSON。舉一個(gè)真實(shí)例子。某個(gè)用戶自定義模板里寫了這樣的片段{ scripts: { dev: next dev, {{#if withE2E}} e2e: playwright test, {{/if}} build: next build } }如果 withE2E 為 false渲染結(jié)果會(huì)保留一個(gè)多余的空行JSON.parse 不一定失敗但可讀性很差。真正致命的是另一種寫法——把逗號(hào)放在 #if 塊前面{ scripts: { dev: next dev, {{#if withE2E}} e2e: playwright test {{/if}} } }當(dāng) withE2E 為 false 時(shí)dev: next dev, 后面直接跟著一個(gè) }這就是非法 JSON。解決這個(gè)問(wèn)題最穩(wěn)妥的方式是要求模板作者遵守一條約定任何可能被 #if 移除的條目它的前導(dǎo)逗號(hào)必須寫在 #if 塊內(nèi)部而不是寫在塊外面。我把這條約定寫進(jìn)了文檔同時(shí)保留了 JSON.parse 校驗(yàn)鉤子。雙保險(xiǎn)下來(lái)這類問(wèn)題基本絕跡了。5.2 Windows 兼容性三個(gè)高頻雷區(qū)我平時(shí)的主力開(kāi)發(fā)機(jī)是 macOS但團(tuán)隊(duì)里 Windows 同事不少。t3code 早期版本在 Windows 上的問(wèn)題集中出現(xiàn)在三處。第一是路徑分隔符。生成出來(lái)的某些配置需要寫路徑比如 Dockerfile 里的 COPY 命令。早期代碼直接用了 path.join 拼接路徑在 Windows 上會(huì)生成反斜杠Dockerfile 解析直接失敗。后來(lái)所有寫進(jìn)模板的路徑統(tǒng)一使用正斜杠只有真正操作文件系統(tǒng)的路徑才用 path.sep。第二是換行符。模板文件在 Windows 上被 Git 檢出后變成 CRLF渲染出來(lái)的文件也是 CRLF。Linux 容器或者 shell 腳本對(duì) CRLF 非常敏感會(huì)報(bào)一些莫名其妙的錯(cuò)誤。我在工具里加了一個(gè) lineEnding 配置項(xiàng)默認(rèn)按模板文件本身的行尾處理但允許用戶統(tǒng)一轉(zhuǎn)為 lf。第三是外部命令的調(diào)用方式。在 Windows 上通過(guò) Node.js 調(diào)用 npm.cmd 這類文件時(shí)execa 是安全的但如果直接用 child_process.exec 并且開(kāi)啟了 shell 選項(xiàng)很容易被路徑里的空格或特殊字符坑到。統(tǒng)一走 execa 之后這類問(wèn)題基本不再出現(xiàn)。5.3 依賴安裝超時(shí)和內(nèi)網(wǎng)源問(wèn)題生成項(xiàng)目之后的第一道坎往往就是 npm install。網(wǎng)絡(luò)環(huán)境不穩(wěn)定的時(shí)候安裝一個(gè)中等規(guī)模的項(xiàng)目動(dòng)輒幾十秒超過(guò)默認(rèn)超時(shí)時(shí)間就會(huì)失敗。t3code 把超時(shí)做成了可配置項(xiàng)同時(shí)在 init 命令里提供了一個(gè) -r 參數(shù)直接指定 npm registry。這個(gè)參數(shù)很實(shí)用比如在受限網(wǎng)絡(luò)環(huán)境下用戶可以傳一個(gè)鏡像地址不用去改全局 .npmrc。還有一個(gè)容易被忽略的細(xì)節(jié)如果用戶已經(jīng)配置了 .npmrc 里的 registryexeca 啟動(dòng) npm 時(shí)會(huì)自動(dòng)讀到這個(gè)配置。這個(gè)行為有好有壞。好的方面是用戶不需要額外配置壞的方面是如果用戶配了一個(gè)錯(cuò)誤的鏡像地址安裝失敗后第一時(shí)間不會(huì)懷疑 .npmrc而會(huì)認(rèn)為是 t3code 的問(wèn)題。我在安裝失敗的錯(cuò)誤信息里加了一行提示提醒用戶檢查 .npmrc 中的 registry 配置。這條提示幫我擋掉了不少重復(fù)的 issue也讓用戶排查問(wèn)題的路徑短了很多。5.4 模板分發(fā)與版本錯(cuò)配的教訓(xùn)t3code 的模板存儲(chǔ)在 npm 包內(nèi)模板和 CLI 代碼共享版本號(hào)。對(duì)于小項(xiàng)目來(lái)說(shuō)這個(gè)方案夠用但模板數(shù)量上來(lái)之后就會(huì)出現(xiàn)代碼沒(méi)變、模板更新也要發(fā)版本的情況。目前我的處理是遵循語(yǔ)義化版本規(guī)范模板改動(dòng)如果只是內(nèi)容層面的變化發(fā) minor 版本模板數(shù)據(jù)結(jié)構(gòu)變化比如 manifest.json 格式調(diào)整發(fā) major 版本。同時(shí)我做了一個(gè)雖然簡(jiǎn)單但非常有用的機(jī)制doctor 命令會(huì)檢查當(dāng)前 CLI 版本與最新版本之間的差異如果差異過(guò)大就提示用戶升級(jí)。這個(gè)檢查不是為了騷擾用戶而是因?yàn)槟０搴?CLI 強(qiáng)耦合版本不對(duì)齊會(huì)生成錯(cuò)誤的內(nèi)容。這個(gè)設(shè)計(jì)是真實(shí)事故換來(lái)的。有一次用戶用舊版 CLI 搭配新模板生成出來(lái)的 package.json 里引用了一個(gè)不存在的腳本排查了很久才發(fā)現(xiàn)是版本錯(cuò)配。現(xiàn)在 doctor 命令會(huì)在用戶跑 init 之前先做版本檢查不一致時(shí)給出明確提示。6. 后續(xù)擴(kuò)展的方向工具的生命力在于被真實(shí)使用最后聊一聊我接下來(lái)想做的事。t3code 目前的形態(tài)已經(jīng)能解決團(tuán)隊(duì)的日常問(wèn)題但它距離我理想中的工程基線工具還有一段路。我自己打算按下面幾個(gè)方向慢慢推進(jìn)也寫出來(lái)給大家做個(gè)參考。6.1 插件機(jī)制當(dāng)前可選區(qū)塊是寫在 manifest.json 里的靜態(tài)聲明數(shù)據(jù)和邏輯都不夠靈活。如果支持插件讓第三方通過(guò)一個(gè)鉤子函數(shù)注入自定義渲染邏輯t3code 就能變成一個(gè)更通用的工程能力平臺(tái)。比如有人做了一套企業(yè)級(jí)日志方案寫一個(gè)插件任何人在生成項(xiàng)目時(shí)都能一鍵接入。這個(gè)方向投入不小目前優(yōu)先級(jí)不算最高但長(zhǎng)期來(lái)看是讓工具突破單團(tuán)隊(duì)自用邊界的關(guān)鍵。6.2 模板遠(yuǎn)程化現(xiàn)在模板打包在 CLI 包里每次想加模板都要發(fā)一個(gè)版本。如果模板能放在 Git 倉(cāng)庫(kù)里CLI 通過(guò) URL 直接拉取指定 tag 的模板那么團(tuán)隊(duì)里的非前端同學(xué)也能通過(guò)維護(hù)倉(cāng)庫(kù)來(lái)更新模板完全不碰 CLI 代碼。這一步能把模板即代碼的理念貫徹得更徹底也是我比較看好的方向。6.3 生成后自動(dòng)校驗(yàn)?zāi)壳?t3code 生成完項(xiàng)目后只做了依賴安裝沒(méi)有對(duì)生成產(chǎn)物做深度校驗(yàn)。我打算加一個(gè) post-init 鉤子在目標(biāo)目錄里自動(dòng)跑一遍 typecheck 和 lint如果失敗直接指出哪些模板文件有問(wèn)題。這個(gè)能力的價(jià)值在于模板作者改完模板后能立刻知道模板本身引入了編譯錯(cuò)誤而不是等用戶創(chuàng)建項(xiàng)目之后才發(fā)現(xiàn)。6.4 更多項(xiàng)目模板t3code 的核心價(jià)值是 T3 技術(shù)棧的工程化基線但同樣的機(jī)制完全可以用于生成 NestJS 后端項(xiàng)目、React Native 項(xiàng)目甚至純 npm 庫(kù)的基線。底層邏輯都是一樣的交互收集參數(shù)、模板渲染、收尾動(dòng)作變的只是模板內(nèi)容。這個(gè)方向不復(fù)雜主要看團(tuán)隊(duì)實(shí)際需求什么時(shí)候出現(xiàn)。根據(jù)我個(gè)人的體會(huì)腳手架工具最怕的不是功能少而是功能沒(méi)人用。t3code 從立項(xiàng)到現(xiàn)在最大的收獲不是代碼量而是逼著我把團(tuán)隊(duì)里很多默認(rèn)大家都知道的工程約定寫成了文檔化的、可驗(yàn)證的模板。這個(gè)過(guò)程中很多原本模糊的規(guī)范變得清晰了很多原本靠口頭傳授的經(jīng)驗(yàn)變成了代碼。如果你也在維護(hù)團(tuán)隊(duì)的工程基建我真心建議試一次把自己的腳手架工具寫出來(lái)哪怕只服務(wù)三個(gè)人它帶來(lái)的規(guī)范沉淀也比任何現(xiàn)成工具都值。