企业官网建设流程全解析

这段时间不少做全栈的朋友都在讨论 t3code 这个东西，尤其是那些受够了在 TypeScript 项目里来回折腾脚手架、手写胶水代码、维护一堆类型声明的团队。简单说，t3code 是一套面向 TypeScript 全栈开发的代码生成与工程初始化工具，它把"类型安全"从编译期的约束延伸到了代码生成阶段——你定义好数据模型，它帮你把后端路由、数据库访问层、前端 API 调用、表单类型这一整条链路的代码一次性生成出来。对于从零启动一个中大型 TS 项目、或者想把现有项目里重复劳动砍掉一半的人来说，这篇文章值得你花十分钟看完。

我大概用了三周时间把 t3code 跑进了实际业务项目，期间踩了不少坑，也摸清了它的设计逻辑。下面不写官腔，就从"它到底解决了什么问题""内部是怎么工作的""怎么从零跑通""有哪些坑和扩展思路"这四个角度，把我的实操经验完整拆给你。

1. t3code 解决的不是"脚手架问题"，而是"类型链路断裂"问题

1.1 为什么你的 TS 项目总在"类型不安全"的边缘试探

很多团队从 JavaScript 迁移到 TypeScript 之后，会遇到一个很微妙的处境：单看每个文件，类型都写得挺规范，但是整个项目连起来跑的时候，类型约束在边界处就断了。

举个例子，后端用 Prisma 定义了一个 User 模型，前端有一个注册表单，中间还有一个 API 层。数据库层的类型、接口层的 DTO、前端的表单数据类型，这三层大多数情况下是各写各的。后端改了字段，前端编译不报错，等运行到接口返回 undefined 才炸。你在小项目里可能觉得手动同步一下就行，但项目一大了，这种跨层类型不同步的问题会成为 bug 重灾区。

t3code 的切入点就在这里：它不只是一个生成 CRUD 代码的工具，而是把"类型"作为生成逻辑的唯一输入源。你在一个统一的模型定义文件里写清楚实体、字段、关系、校验规则，它负责把这个模型翻译成不同层次都能识别的 TypeScript 类型与运行时代码。这样一来，类型不再散落四处，而是从一个中心点自动长出来，链路两端永远对得上。

1.2 t3 的三层含义：Types、Templates、Tooling

很多第一次听说 t3code 的人都会问，为什么叫 t3？官方的说法是三个以 T 开头的关键词：Types、Templates、Tooling，即类型、模板、工具链三者的结合。也有社区朋友调侃说 t3 指的是 TypeScript 生态从手动维护到自动生成的"第三阶段"，这个说法虽然不一定严谨，但确实点中了它的定位。

我做了一个小的功能对比，能更清楚地看出 t3code 和其他常用方案的差别：

现在很多团队其实处在前三行的状态，能用，但每一层之间的连接依然靠人肉保证。t3code 把这层连接自动化了，这是它和其他工具最本质的区别。

2. 核心机制拆解：模型即契约，生成即连接

2.1 "单一事实来源"是怎么落地的

我见过很多项目号称有"单一数据源"，结果还是数据库模型一套、接口文档一套、前端类型一套，开会的时候大家对着三份材料各说各的。t3code 的做法很直接：你要在项目里建立一个 model 目录，里面用 TS 接口或者专门的 schema 语法定义所有业务实体，这就是全项目唯一的契约源头。

比如你要做一个电商系统里的订单模块，模型定义大致长这样：

// models/order.model.ts import { z } from 'zod'; export const OrderSchema = z.object({ id: z.string().uuid(), userId: z.string().uuid(), productId: z.string().uuid(), quantity: z.number().int().positive(), totalAmount: z.number().positive(), status: z.enum(['pending', 'paid', 'shipped', 'cancelled']), createdAt: z.date(), updatedAt: z.date(), }); export type Order = z.infer<typeof OrderSchema>; export const OrderCreateInputSchema = OrderSchema.omit({ id: true, createdAt: true, updatedAt: true, }); export type OrderCreateInput = z.infer<typeof OrderCreateInputSchema>;

你可能注意到了，这里用了 zod 来做 schema 定义。这是 t3code 的默认推荐方式，理由很简单：zod 同时承担了运行时校验和静态类型推导两个职责，一份 schema 既能用来生成类型，又能直接作为接口入参的校验器。生成出来的代码里，API 层会自动引用这份 schema 的解析逻辑，所以前端传进来的数据在入口处就会被严格校验，而不是等到数据库层面才报错。

2.2 生成管线：从模型到三层代码

模型定义好之后，t3code 的 CLI 会执行一条生成管线。我把它拆成四步来看，逻辑会清楚很多：

1. 解析：CLI 读取 model 目录下所有 schema 文件，用 TypeScript 编译器 API 或者 zod 的内部结构提取字段、类型、默认值、校验规则。
2. 规划：根据你选择的生成目标（后端框架、前端框架、ORM 类型），计算需要生成哪些文件、文件之间如何互相引用。
3. 渲染：内置的模板引擎把模型信息填充到预定义模板里，输出 TS 文件。
4. 后处理：执行 import 整理、路径别名替换，必要时跑一遍 prettier，让生成代码符合项目原有风格。

以实际生成结果为例，一个 Order 模型在后端大概会生成这些文件：

server/ routes/ order.routes.ts # 路由注册 controllers/ order.controller.ts # 请求入参校验 + 调用 service services/ order.service.ts # 业务逻辑 repositories/ order.repository.ts # 数据库访问 dtos/ order.dto.ts # 出入参类型，自动复用模型类型 client/ api/ orderApi.ts # 前端 API 调用封装 types/ order.types.ts # 前端类型定义 hooks/ useOrder.ts # React hooks 封装

这套结构我是跑通了之后才理解它的妙处：生成出来的代码不是让你一行不改，而是给你一套"骨架已经完全正确"的起点。你改业务逻辑，但不需要再操心类型边界、路由声明、API 调用这些纯体力活。

2.3 自定义模板：遇到特殊业务怎么办

默认模板覆盖了常见的 CRUD 场景，但真实业务里总有"订单创建后要扣库存""用户注册后要发欢迎邮件"这类特殊逻辑。t3code 留了两个口子：

• 模板覆盖：在项目根目录建一个 .t3/templates 目录，把你需要改的模板文件放进去，CLI 会优先使用本地模板而不是内置模板。你可以直接改生成出来的文件，然后把它复制进自定义模板目录，下次生成时就会以你的版本为准。
• 生命周期钩子：在 .t3/hooks.js 里可以注册 beforeGenerate、afterGenerate 这类钩子函数，在生成前后执行自定义逻辑。比如我就在 afterGenerate 里加了自动运行 eslint --fix 和 tsc --noEmit 的操作，确保每次生成出来的代码直接就是通过检查和编译的。

这里有个实操建议：模板文件里尽量避免写死具体业务字段，而是多使用模板变量。你改完一份实际生成文件想拿它当模板时，记得把里面的字段名替换成变量占位符，否则下次生成到别的模型上，内容就完全错乱了。

3. 从零实战：跑通一个前后端全栈的最小闭环

3.1 环境准备与初始化

t3code 的安装本身不复杂，但有几个前置条件容易踩坑。首先 Node.js 版本建议 18 以上，否则 CLI 的依赖解析会有兼容问题；其次项目最好已经初始化了 git 仓库，因为生成器会自动生成 .gitignore 更新，没有 git 环境会少掉一部分体验。

先创建一个空项目，然后安装 t3code：

mkdir my-t3-project cd my-t3-project npm init -y npx t3code init --template fullstack

这个 fullstack 模板会同时生成 server 和 client 两个目录，并装好前后端的基础依赖。初始化完成后的目录结构大概是这样的：

my-t3-project/ .t3/ # 配置文件、自定义模板目录 models/ # 模型定义目录，这是核心 server/ # 后端代码 client/ # 前端代码 tsconfig.base.json # 共享 TS 配置

如果网络环境不太稳定，init 阶段有概率因为依赖安装超时而中断。遇到这种情况不用慌，项目骨架已经生成了，只需进到对应目录手动执行 npm install 即可。

3.2 定义一个带业务关系的模型并生成代码

我拿一个最简单的"用户 + 订单"场景来演示。在 models 目录下建两个文件：

// models/user.model.ts import { z } from 'zod'; export const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email(), nickname: z.string().min(2).max(20), createdAt: z.date(), }); export type User = z.infer<typeof UserSchema>;

// models/order.model.ts import { z } from 'zod'; import { UserSchema } from './user.model'; export const OrderSchema = z.object({ id: z.string().uuid(), userId: UserSchema.shape.id, productName: z.string().min(1), quantity: z.number().int().positive(), totalAmount: z.number().positive(), status: z.enum(['pending', 'paid', 'shipped', 'cancelled']), createdAt: z.date(), }); export type Order = z.infer<typeof OrderSchema>;

然后执行生成命令：

npx t3code generate

如果你在 init 时选用的是 Prisma 作为数据库层，t3code 还会自动同步更新 schema.prisma 文件。注意这一步需要数据库环境变量能正常读取，如果 DATABASE_URL 没配好，生成会在后处理阶段报错提示你检查环境变量。

3.3 看一眼前后端生成出来的代码

后端 controller 层的生成代码大致长这样：

// server/controllers/order.controller.ts import { Request, Response } from 'express'; import { OrderCreateInputSchema, OrderUpdateInputSchema } from '../dtos/order.dto'; import * as orderService from '../services/order.service'; export async function createOrder(req: Request, res: Response) { const parsed = OrderCreateInputSchema.safeParse(req.body); if (!parsed.success) { return res.status(400).json({ error: parsed.error.flatten() }); } const order = await orderService.createOrder(parsed.data); return res.status(201).json(order); }

可以看到，入参校验直接从模型 schema 派生，不需要再单独维护一层校验规则。前端 API 层也很整洁：

// client/api/orderApi.ts import { apiClient } from './apiClient'; import type { Order, OrderCreateInput } from '../types/order.types'; export const orderApi = { list: async () => { const { data } = await apiClient.get<Order[]>('/orders'); return data; }, create: async (input: OrderCreateInput) => { const { data } = await apiClient.post<Order>('/orders', input); return data; }, };

前端拿到的类型 OrderCreateInput 和后端校验用的 OrderCreateInputSchema 是完全同一套类型推导出来的，不存在"前端以为能传、后端以为不会传"的错位。

3.4 把全链路类型检查跑起来

生成完代码后，最重要的一步是验证端到端的类型安全。我在 package.json 里加了一个脚本：

{ "scripts": { "typecheck": "tsc --noEmit -p server/tsconfig.json && tsc --noEmit -p client/tsconfig.json" } }

然后执行：

npm run typecheck

如果后端 model 里把 totalAmount 改成 string，前端调 orderApi.create 传 number 的地方立刻会报类型错误，不需要等联调时才发现。这就是 t3code 对比传统脚手架最直观的收益：生成代码不是一次性工作，而是让你后续每一次修改模型，都像按了一下"全链路同步"的开关。

4. 落地过程中的踩坑清单与二次扩展思路

4.1 生成代码和手写代码的边界，怎么定才不会打架

我见过不少团队用了类似工具之后产生一个新问题：生成出来的代码和自己手写的代码混在一起，改来改去都不记得哪些是"可以重新生成"的，哪些是"手工改过不能覆盖"的。

我目前的经验是用三个原则来区分：

• 模型文件只负责结构和校验规则，业务逻辑一律不写在里面；
• 生成出来的 routes、dtos、api 层文件是"受控文件"，默认不手工修改；需要改时，优先找到对应的自定义模板去改；
• services、hooks、组件这类承载业务逻辑的文件属于"半受控"，生成后自己会继续往里面加功能，但新增字段时重新生成的代码会自动尝试 merge，而不是直接覆盖。

t3code 的 merge 策略默认保留你的修改块，只要你在手写代码的外面加上特定注释标记，比如：

// @t3code:preserve-start // 这里写你自己的业务逻辑，重新生成时不会被删 // @t3code:preserve-end

这个标记养成习惯后，团队协作会省掉很多"谁把谁改的东西覆盖了"的扯皮。

4.2 路径别名和 Monorepo 场景的两个坑

第一个坑在路径别名。很多项目喜欢用 @/ 代表 src 目录，t3code 初始化时会自动读取根目录的 tsconfig.json，生成代码里会使用你配置的别名。但如果你在 init 之前没有配置好 paths，生成出来的代码会带着相对路径，后面手动改成别名时，重新生成又会退回去。强烈建议：先配置 tsconfig 里的 paths，再跑 init。

第二个坑是 Monorepo。t3code 默认假设 server 和 client 在同一个 package 下，如果你用的是 pnpm workspace 或 turborepo，需要额外配置一下 .t3/config.json，把 serverRoot 和 clientRoot 指到对应子包目录。否则生成器会自动把依赖安装到根目录，导致子包间的 import 关系混乱。我在一个 monorepo 项目里第一次跑生成时，整个 node_modules 结构被打乱了，后来检查配置才发现没显式声明子包路径。

4.3 扩展自己的模板与生成器插件

如果你不满足于默认模板，想给团队定制一套"专属风格"的生成代码，可以使用 .t3/templates 目录做整文件覆盖，也可以写轻量级插件扩展生成类型。插件本质上就是一个函数，挂在 generate 过程的中间阶段：

// .t3/plugins/auditLog.js module.exports = { name: 'audit-log-plugin', afterEntityGenerated({ entity, files }) { // 比如在每个实体的 service 里自动注入操作日志 }, };

这个机制让我可以额外生成一套审计日志模块，业务代码里每次 create、update，都会自动带上操作人、时间戳、变更前快照。如果没有这个钩子，我需要把所有的 service 文件全部手工改一遍，而且每次重新生成后还得再改一次，非常痛苦。

4.4 什么时候不建议使用 t3code

说说完美场景之外的部分。t3code 是"模型驱动"的设计，这决定了它最适合数据结构清晰、CRUD 占比较大的业务系统，比如后台管理系统、中台项目、内部工具平台。如果你的项目是那种高度定制、强交互的前端体验型产品，或者后端逻辑大量依赖外部系统对接，生成代码能覆盖的比例会大幅下降，这时候引入它可能反而增加一层心智负担。

还有一个现实问题：如果你的团队对 TypeScript 本身掌握得不够扎实，不建议初期就引入这么强约束的工具。因为 t3code 的模型文件用了不少高级类型技巧，看不懂模型就相当于改不了源头，后面所有环节都会被卡住。先把 TS 类型基础补起来，再用这种工具，效益才会最大化。

最后的经验之谈

花几周时间把 t3code 用进实际项目之后，我最大的体感是：团队里"类型边界"层面的低级 bug 明显减少了，新人上手项目时不再需要从前端翻到后端、从路由翻到数据库去理清楚一条数据到底是怎么流动的。模型文件本身就像一张地图，看一眼就知道系统里有哪些实体、字段长什么样、校验规则是什么。如果你正在被跨层类型不同步、重复的 CRUD 代码、联调时才暴露的字段错误这些问题困扰，并且团队对 TypeScript 有一定熟悉度，那 t3code 值得你花一个下午跑一遍 demo，亲自感受一下"改一个模型，全链路类型同步更新"到底是什么体验。真正适合自己的工具，永远是在实际项目里试出来的。