t3code：从重复搭架子到开箱即用，全栈项目脚手架的实战解析

t3code 是我自己维护了大半年的一套全栈项目脚手架，名字里的三个 t 我借用了 TypeScript、Tailwind、tRPC 的常见组合叫法，但实际内容比“某个技术栈模板”要宽不少。简单说，它解决的是我一直很烦的问题：每开一个新项目，路由要重新配、请求层要重新写、lint 规则要重新聊、提交规范要重新说服队友，一两天就这么耗在“搭架子”上。现在这些事基本都固化进 t3code，一句命令就能拉出带完整规范的项目骨架。

这篇文章直接把思路和盘托出：为什么当初要造这个轮子，模板内部是怎么设计的，实际用起来到底顺不顺手，以及这半年里我踩过的几个典型坑。如果你也是那种手里同时维护好几个项目、还得反复初始化仓库的前端或者全栈开发者，又或者你小团队里总有人为“代码风格不统一”吵架，那这篇应该能给你不少可落地的参考。

1. 为什么会有 t3code：从“重复搭架子”到“开箱即用”

1.1 我最初的问题：每个项目都要重新走一遍流程

两年前我接手一个小团队的技术规划，当时组里三个人，手里同时滚着四五个项目。表面上看大家都在正常推进业务，但有个问题一直让我很不舒服：每个项目的初始化方式都“稍微有点不一样”。

有人直接用 Vite 默认模板，有人从旧项目里 copy 了一份带路由的目录，还有人喜欢自己搭一套带services、stores、views的目录结构。依赖管理也是，有人用 npm，有人用 pnpm，lockfile 一换就是一次大改动。更别提 lint 规则了——A 项目里能过的代码，到了 B 项目直接红一片。

这种差异一开始看着只是“不统一”，但半年后问题就来了。团队里任何一个人一旦需要去改另一个人的项目，光看目录结构就要花半天。代码评审的时候，讨论的重点经常不在业务逻辑上，而是“你这里为什么用双引号”“这个类型为什么没有显式声明”。后来我实在受不了，决定把“搭架子”这件事做成一个标准流程。

1.2 t3code 的三个设计原则

这个脚手架做到现在，核心设计原则就三条，所有后续功能都是围绕这三条展开的。

第一条是“约定优于配置，但约定必须可覆盖”。t3code 默认给出整套规范：目录怎么分、请求层怎么封装、路由怎么注册、提交信息什么格式。你直接用就能跑，但如果你想改，也不用去源码里翻配置，所有默认值都集中在一个配置文件里，改一处全局生效。

第二条是“模板要有业务感，不能只是个 Hello World”。一般脚手架生成的模板，顶多帮你搭好一个能跑起来的页面。但实际中后台项目的大部分工作量来自登录鉴权、路由守卫、请求错误处理、权限指令、分页表格这些“业务基建”。t3code 生成的代码会直接带上这些内容，让你初始化完之后不至于面对一片空白。

第三条是“模板本身要被持续维护”。我一开始也犯过“模板写一次就放着不管”的毛病，后来发现技术栈一升级、业务模式一变，旧模板反而成了负担。所以 t3code 里引入了“片段”概念：模板被拆成一个个可插拔的模块，核心部分升级时不会影响你已经生成的项目，已经创建的项目也能通过新片段增量同步最新实践。后面我会专门讲这一块。

选 CLI 而不是让用户直接git clone一个模板仓库，也是基于这三点考虑。直接 copy 仓库最大的问题是：仓库里的包名、项目名、作者信息全是写死的，拿回来还得全局搜索替换，一不留神就漏改。而且 git 历史、旧依赖、旧的提交钩子配置全都被带过来了，反而成了脏数据。CLI 加模板渲染的方式则可以做到参数化生成：回答几个问题，渲染器把变量写进对应文件，产出的项目干净且完整。

2. 核心设计与技术选型：t3code 到底长什么样

2.1 目录结构设计与划分逻辑

整个 t3code 的仓库结构是典型的 pnpm monorepo。核心目录大概长这样：

t3code/ ├── apps/ │ ├── web/ # 前端应用（React + Vite） │ └── server/ # 后端 API（Express + Prisma） ├── packages/ │ ├── shared/ # 前后端共享的类型与工具函数 │ └── config/ # 统一的 eslint / tsconfig / prettier 配置 ├── scripts/ │ ├── cli/ # 初始化命令行的实现 │ ├── generators/ # 页面、API、模型的代码生成器 │ └── loaders/ # 模板片段的加载与注册逻辑 ├── templates/ │ ├── base/ # 最基础的项目骨架 │ └── fragments/ # 可插拔的片段：login、user-list、audit-log 等 └── package.json

这个结构乍看比单个应用项目复杂，但对“脚手架”这个角色来说很合适。apps里是真正的生成目标，packages里放的是跨项目复用的配置和代码。比如@t3code/config这个包集中管理 TypeScript 的strict选项、ESLint 的规则集，以及 Prettier 的格式配置。所有从 t3code 生成出来的项目，统一从packages/config继承规范，而不是在各自项目里各写一份.eslintrc。

为什么坚持用 monorepo？因为在真实项目里，一个中后台系统往往同时包含前端、API 服务、定时任务、文档站点。如果每个代码仓库都独立维护 tsconfig 和 eslint，很容易出现两个服务的类型定义悄然漂移。我之前见过一个项目，前端User接口里age是number，后端User模型里age是string，编译各自都通过，联调的时候才发现问题。把共享类型抽到packages/shared之后，前后端引的是同一份定义，这类问题直接被消灭在编译期。

2.2 技术选型背后的取舍

t3code 目前默认的技术栈是 TypeScript + React + Vite + Tailwind CSS + Express + Prisma + Vitest，配套 ESLint、Prettier、Husky、lint-staged、commitlint。表格里列一下我当初选型时的理由：

这个选型可能不是每个场景的最优解，但它是“大概率不会错”的组合。比如我不选 Next.js，是因为 t3code 的目标场景是传统前后端分离的中后台：前端要的是快速迭代和清晰的页面路由，后端要的是能直接接数据库的 CRUD 接口。如果换成重 SSR 的框架，部署复杂度会明显上升，对一个小团队来说性价比不高。当然，t3code 并没有把路堵死，技术选型都集中在模板层，你完全可以基于模板换成别的框架。

2.3 模板与代码生成器的关系

t3code 本质上不是“一份静态模板”，而是“模板 + 生成器”的组合。静态模板能解决初始化问题，但解决不了重复造页面、重复写 CRUD 的问题。我在模板里内置了几条常用命令，比如生成一个新的列表页面、生成一个带 Prisma model 的接口、生成一个表单组件。

打个比方，静态模板相当于毛坯房加一张户型图；生成器则是按图施工的施工队。你告诉它“我需要一个用户列表页”，它会自动把路由配置、导航菜单、API 调用函数、页面组件、类型定义全部生成出来，并且把该注册的地方都注册好。这一步大大减少了“业务基建”层面的重复劳动。

不过有一点我必须强调：生成器不是魔术，它的价值建立在团队约定一致的基础上。如果你们团队本来就没有统一的目录规则，那任何生成器产出的代码都可能跟你的现状冲突。所以 t3code 默认先把目录结构和注册机制定死，遇到不合规的情况宁可报错，也不要生成一个“四不像”的文件。

3. 实际使用教程：用 t3code 快速创建一个可用项目

3.1 安装与初始化

假设你现在要用 t3code 创建一个项目，整个过程大概是这样的。先执行：

pnpm create t3code my-app

如果你用的是 npm，可以执行npm create t3code@latest my-app。初始化之后，CLI 会问你几个问题，主要是三种：项目名、包管理器偏好、需要哪些功能片段。功能片段目前有登录鉴权、用户列表、操作日志、文件上传这几个。这些片段不是必选，但绝大多数人至少会选登录，所以我默认把auth放在第一个。

回答完之后，CLI 会开始渲染模板。这里有两个细节我觉得比生成结果本身更重要，一并说一下。

一是它会做“文件冲突检测”：如果你执行命令的项目目录里已经有文件，CLI 不会直接覆盖，而是逐文件询问是跳过、替换还是保留两者。我见过很多脚手架直接把目录清空，这个行为我始终认为太危险了。

二是它会做“全量依赖安装”。生成完之后自动执行pnpm install，并且跑一次pnpm lint和pnpm typecheck，确保你拿到手的就是一个能通过全部检查的项目。如果初始化过程中有任何一步失败，它会明确提示是在哪个环节断的，不会留下一堆未知状态。

3.2 生成后的项目结构与关键配置

初始化完成后，你会得到一个这样的目录结构：

my-app/ ├── apps/ │ ├── web/ │ │ ├── src/ │ │ │ ├── pages/ │ │ │ ├── components/ │ │ │ ├── layouts/ │ │ │ ├── router/ │ │ │ ├── services/ │ │ │ └── main.tsx │ └── server/ │ ├── src/ │ │ ├── routes/ │ │ ├── middlewares/ │ │ ├── prisma/ │ │ └── index.ts ├── packages/ │ ├── shared/ │ │ └── src/ │ │ ├── types/ │ │ └── utils/ │ └── config/ ├── .env.example ├── .eslintrc.cjs ├── .prettierrc ├── .gitignore ├── commitlint.config.cjs └── package.json

几个关键配置文件的价值，我拆开说。

packages/config里的tsconfig.base.json保存了严格模式下的所有编译选项。核心是"strict": true、"noUncheckedIndexedAccess": true、"exactOptionalPropertyTypes": true、"moduleResolution": "bundler"。这几个选项看着不起眼，实际能帮你拦下一大批运行时错误。特别是noUncheckedIndexedAccess，它会让你在访问数组元素时意识到结果可能有undefined，逼着你处理边界。

.env.example里预置了数据库连接串、JWT 密钥、前端 API 地址这些常见的环境变量占位。在模板里，环境变量不是到处process.env.SOMETHING随手取，而是要求先在一个env.ts文件里定义 schema，统一导出。这个习惯花不了多少时间，但能让“缺个环境变量导致线上崩”的概率大幅下降。

husky 和 lint-staged 是开箱即用的。提交之前自动跑一次 prettier 和 eslint，只针对暂存区文件。commitlint 则限定了提交信息的格式。这些机制刚上时会有队友觉得烦，但用一个月之后，基本没人愿意再回到“commit message 随便写”的状态。

3.3 一个完整的落地示例：新增页面和接口

我用一个“用户列表页面”来演示 t3code 的日常开发流程。

第一步，在apps/server里定义数据模型。假设用 Prisma，直接在schema.prisma增加一个模型：

model User { id String @id @default(cuid()) email String @unique name String? role String @default("member") createdAt DateTime @default(now()) }

第二步，运行pnpm prisma migrate dev生成迁移文件。之后用 t3code 的生成器创建 API：

pnpm gen api user

这个命令会读取 Prisma 模型，自动生成对应的路由文件、controller 和对应的方法，并且在routes/index.ts里完成注册。路由层拿到的请求会直接映射到 Prisma 的 CRUD 方法，所以很短：

import { Router } from 'express'; import { prisma } from '../prisma'; import type { User } from '@t3code/shared'; export const userRouter = Router(); userRouter.get('/users', async (_req, res) => { const users = await prisma.user.findMany(); res.json(users satisfies User[]); });

第三步，在前端项目里生成页面：

pnpm gen page user-list

生成器会自动创建apps/web/src/pages/user-list/index.tsx，把路由配置加进router/routes.tsx，把导航菜单项加进layouts/MainLayout.tsx的菜单配置里，再生成一个调用接口的service文件。页面组件用 React Query 管理请求状态，大致长这样：

import { useQuery } from '@tanstack/react-query'; import { fetchUsers } from '../../../services/user'; import type { User } from '@t3code/shared'; export function UserListPage() { const { data, isLoading } = useQuery({ queryKey: ['users'], queryFn: fetchUsers }); if (isLoading) { return <div>加载中...</div>; } return ( <div className="p-6"> <h1 className="text-lg font-semibold">用户列表</h1> <div className="mt-4 grid gap-2"> {data?.map((user: User) => ( <div key={user.id} className="rounded border p-3"> <span>{user.name}</span> <span className="text-sm text-gray-500">{user.email}</span> </div> ))} </div> </div> ); }

整个过程大概五分钟。以前这五分钟要花在复制旧代码、改路径、查路由表、补类型上，现在只需要给出“我要用户列表”这个意图，剩下都是生成器的事。我刻意没有在示例里写更复杂的表格组件，因为生成器只是起点，真正的业务逻辑终究要自己写；它的价值在于把你“必经的路”自动铺好。

4. 深度自定义：把 t3code 改造成你自己的脚手架

4.1 配置文件与动态变量体系

t3code 的模板渲染建立在一套“变量注入 + 条件文件”的机制上。所有变量都来自templates/base/template.config.ts这个文件。看一下简化版本：

export default { prompts: [ { name: 'projectName', message: '项目名称', default: 'my-app' }, { name: 'needAuth', message: '是否需要登录鉴权', type: 'confirm', default: true }, ], variables: { projectName: (answers) => kebabCase(answers.projectName), packageName: (answers) => answers.projectName.replace(/-/g, ''), }, conditionalFiles: [ { condition: (answers) => answers.needAuth, source: 'fragments/auth', }, ], };

模板文件里用<%= projectName %>这类占位符来注入变量。举一个实际例子，package.json模板会写：

{ "name": "<%= packageName %>", "scripts": { "dev": "pnpm run -r dev", "lint": "pnpm run -r lint" } }

这套体系成本很低，但收益很实在。你可以非常方便地加入自己的变量，比如公司前缀、包名缩写、内部 registry 等，然后统一作用于全部模板文件。CLI 交互里收集到的答案会直接进入同一个 answers 对象，后续所有渲染都基于这份 answer 展开。

4.2 新增一个业务模板片段的完整步骤

t3code 的“片段”机制是最值得自定义的部分。默认模板只覆盖通用场景，但不同团队总有自己的一套固定玩法，比如移动端项目要套壳 H5，后台项目要有审批流。这时候你可以自己写片段。

写一个片段分四步。

第一步，在templates/fragments/下创建一个目录，比如叫audit-log，里面放你要生成的文件，用占位符标注变量。

第二步，在片段配置文件里声明这个片段能干什么。一个最简单的片段配置长这样：

export default { name: 'audit-log', description: '操作日志模块', prompts: [ { name: 'logTableName', message: '日志表名', default: 'audit_log' }, ], files: [ { source: 'server/route.ts.tpl', target: 'apps/server/src/routes/audit-log.ts' }, { source: 'web/page.tsx.tpl', target: 'apps/web/src/pages/audit-log/index.tsx' }, ], };

第三步，在scripts/loaders/fragment.ts里注册这个片段。注册动作只做一件事：把新的片段配置合并进已有的片段列表。这里有个细节要注意，文件名要尽量避免和已有片段冲突，否则加载的时候会直接报错。冲突比覆盖更安全，因为覆盖会静默地丢掉旧代码。

第四步，运行pnpm gen fragment audit-log验证一遍。如果你没安装依赖，可以先pnpm install；正常的话生成器会提示新增了几个文件、注册了几条路由。

这套机制的思路来自我一直在用的一个原则：任何你做过三次以上的重复工作，都应该变成可复用的模板代码。哪怕是团队内部特有的“分页表格带筛选条件”这类组件，也值得沉淀成片段，然后在下一个项目里直接复用。

4.3 升级模板时如何兼顾已有的项目

这是所有脚手架类项目最尴尬的问题：模板升级了，那已经用老模板生成的项目怎么办？强行重新生成整个模板肯定不现实，因为业务代码早就写进去了。t3code 的解决方案有三个层级，按推荐程度从高到低排。

第一层级，把核心能力放进packages/并通过 workspace 依赖升级。比如请求封装、鉴权逻辑、Env 解析这一类基础代码，它们以包的形式被项目引用。包升级时，只需在项目里把版本号抬一下，然后看 changelog 决定要不要改调用方。这种方式的侵入性最低，也是我最推荐的同步方式。

第二层级，用 codemod 脚本做定向替换。比如模板早期把所有路由都放在一个routes.ts里，后来你想改成按目录自动加载，就不适合手动改每个项目。我写过几个 codemod 脚本，遍历项目文件做 AST 级转换，跑完自动提交。AST 转换比字符串替换可靠得多，建议所有人都学一点 jscodeshift 的基础用法。

第三层级，直接放弃同步。如果某个项目已经进入稳定维护期，业务逻辑基本不再变动，那就没必要强行追新模板。模板升级应该服务于“还在活跃开发的项目”，而不是让每个老项目都跟着折腾。

5. 常见问题与踩坑记录：这些坑我替你先踩过了

5.1 问题速查表

5.2 三个最棘手的坑

第一个坑是模板变量与业务代码语法冲突。我最初用 ejs 作为模板引擎，占位符是<%= %>，但 React 和 Vue 模板里大量使用{{ }}。这个问题一开始没暴露，直到我在一个模板文件里写了const style = { color: '{{ color }}' }才发现渲染结果完全不对。排查了很久，最终结论是：ejs 默认把<%开头的内容当作代码，Vue 的插值写法“看起来”没问题，但某些组件库的文档模板里真会出现<%字符。解决方法是统一转义：所有模板文件里需要保留的<%一律写成<%%，渲染后再还原。这在生成器里是一条硬编码规则。

第二个坑是路径分隔符的系统差异。生成器在扫描片段文件时，我第一次写的是本地遍历，用的path.join，在 Windows 上会得出apps\\web\\src这样的路径。然后渲染器把这些路径写进配置，前端打包在 macOS 上就崩了。后来所有文件路径统一改用posix.join，并且扫描目录交给fast-glob处理，它会自动 normalize 路径分隔符。这件事让我记住一个规则：凡是会写进代码生成结果的路径，一律用 POSIX 风格，别跟操作系统较劲。

第三个坑是 pnpm 的幽灵依赖。t3code 用了 monorepo 结构，pnpm 默认的符号链接布局对依赖隔离做得很好，但如果你在项目里没有声明某个依赖，却在代码里直接 import，TypeScript 有时依然能解析到根目录node_modules里的同名包，因为编辑器用的是node_modules/.pnpm或根目录桌面解析。这个问题的诡异之处在于，构建能过、类型能过，但换到 CI 环境可能就挂了。最终的方案是两手抓：一是给 ESLint 配一条规则，禁止 import 未在package.json里声明的包；二是 CI 流水线里先跑一次pnpm install --frozen-lockfile，再跑pnpm typecheck，让“幽灵依赖”在第一步就直接报错。

6. 后续扩展与个人心得

6.1 我计划做的几个方向

接下来我对 t3code 的规划大致有三条线。

第一是把 CLI 部分从 monorepo 里拆成独立包，做成真正可发布的命令行工具。现在的 CLI 还依赖仓库内的脚本上下文，拆出去之后别人用起来会更干净。

第二是增加更多“业务片段”的预设。目前有登录、用户列表、日志、上传，接下来想做权限管理、工作流审批、数据字典这类在中后台里出现频率极高的功能。当然这些片段会比“列表页”复杂得多，目前还在靠真实项目反向打磨。

第三是给生成器加一个“反向扫描”能力：从一个已有项目里识别哪些目录和文件符合约定，生成报告。这个功能一旦做出来，老项目就能更平滑地纳入 t3code 的管理体系。

6.2 我个人使用 t3code 的一点体会

说句实话，做这套东西最大的收益不是省下一两天的初始化时间。省时间是显性的收益，但更大的隐性收益在于：工程规范被当作代码来管理了。以前讨论“路由应该怎么组织”“请求层要不要统一封装”是开会聊，现在直接看模板和生成规则就够了；有不满意的地方就改模板提 MR，人人都能参与演进。规范从“口头共识”变成了“可评审的代码”，这是我认为最值得推广的工作方式。

还有一个对我个人影响很深的小习惯：现在我每遇到第三次重复劳动，就会停下来琢磨能不能把它固化进模板。这个原则听起来很简单，真正坚持下来之后，你会发现自己的项目工具箱里积累的都是“被验证过”的资产，而不是一次次临时复制粘贴出来的碎片代码。如果你也对这种工作方式感兴趣，我的建议很直接：不要等模板做到完美才开始用，先从一个最小可用的版本跑起来，然后让它随你的项目一起慢慢长大。