企业官网建设流程全解析

t3code 这个名字，乍看只是个随手起的项目代号，但如果你团队里经常为了“前后端类型对不上”“新模块起步半天”“环境配置一人一个样”这类事吵架，那这套东西就是冲着这些痛点来的。它本质上是一套以 TypeScript 为核心的工程化模板与编码约定，把数据模型、接口契约、前端调用、环境配置全部串在一条类型安全的链路上，让整个团队在一个项目里共享同一份“世界真相”。这篇文章我会从设计思路拆起，把你可能关心的选型理由、目录结构、落地步骤、踩坑记录都过一遍，看完就能照着搭出一套顺手的版本。

最开始接触到 t3code 这个代号，是听一个做全栈的朋友提起来的。他说团队里来了三个新同学，每人第一周写的代码风格都不一样，有人用 any 到处飞，有人把接口地址硬编码在页面里，还有人为了取一个字段自己又包了一层对象。问题不在人，在于项目没有一个统一的“骨架”。t3code 就是他们内部为了解决这件事沉淀出来的一套模板：一套规范了数据流、接口层、环境变量、生成脚本的 TypeScript 工程骨架，推倒重来的成本几乎为零。

这篇文章不只是介绍目录长什么样，我更想把每个设计决策背后的为什么讲清楚，比如为什么要用 zod 校验环境变量，为什么模块生成器要连着路由和类型一起生成，为什么接口层不直接放 axios 实例。这些都是我在实际落地中反复权衡过的点，希望你看完能直接拿去用，少交学费。

1. t3code 是什么：一套 TypeScript 全栈工程方案的设计思路

1.1 项目的来源与核心需求

t3code 并不是一个框架，也不是一个库，它更像是一套“把约定固化下来”的工程模板。它的目标场景非常明确：中小型全栈项目，团队规模三五人到十几人，前端用 React 或 Vue，后端用 Node.js（NestJS 或 Express），数据库以 PostgreSQL 为主，整个团队希望用 TypeScript 覆盖从前端到后端的全部代码。

这套模板要解决的核心问题有三个。第一个是类型割裂：前后端各写各的类型，接口一变更，前端往往要翻后端代码才能找到新字段名，改完还容易漏。第二个是起步成本高：每开一个新模块，都要手动建路由、建控制器、建页面文件、配路径别名，少则半小时，多则一下午。第三个是环境配置混乱：有人用 .env.development，有人用 .env.local，有人把密钥放到代码里提交，项目在不同电脑上跑起来结果都不一样。

t3code 的核心主张就是一句话：凡是能被代码自动生成的，就不要手工编写；凡是能被类型系统约束的，就不要靠口头约定。基于这个主张，它把所有规则都固化在模板和脚本里。你拿到项目之后不需要读十页 README，跑一条命令，一个新模块的路由、控制器、前端页面、类型定义就全部生成好了，而且类型是通的。

1.2 这套方案解决了哪几类实际问题

我根据自己用下来的经验，把 t3code 解决的问题归纳为四类，每一类都是实际开发中真实存在的麻烦。

第一类：接口联调的成本失控。传统前后端联调，后端把接口写好了，前端拿着文档开始对接，接口文档一旦不更新，前端就只能去问后端。t3code 的做法是让后端接口的入参和出参模型成为唯一的类型来源，前端通过自动生成的类型文件引用它。后端改了字段名，前端 TypeScript 编译直接报错，问题在写代码阶段就暴露，而不是上线前联调才发现。

第二类：新业务模块的重复建设。我见过不少团队，新开一个“用户反馈”模块，要复制一遍“商品列表”模块的目录结构，再改掉里面的名称。复制粘贴这件事本身不算大问题，问题在于经常会漏掉配置文件、忘记注册路由、路径名改一半。t3code 的模块生成器会把整个生命周期打通，从后端路由到前端页面一把梭，生成完直接能跑起来改业务。

第三类：环境和依赖的不一致。这种问题排查起来最磨人。我遇到过一次，本地跑得好好的，同事拉代码却启动报错，查了半天是环境变量里少了数据库连接字段，而代码里压根没有对这个字段的校验，漏了也不报错，直到运行时才挂。t3code 会用校验库在进程启动时强校验所有环境变量，缺一项、错一项，直接明确报错告诉你哪里有问题。

第四类：代码风格与架构漂移。项目一开始架构清晰，随着人员流动和业务堆叠，Controller 里开始写业务逻辑，页面里开始拼 SQL，架构慢慢就“烂”了。t3code 通过分层约定和依赖方向限制，把合理的架构固定在模板里，新来的同事照着写，写不出结构太离谱的代码。

2. 核心设计思路与技术选型解析

2.1 技术栈选型与取舍逻辑

t3code 的技术栈选型不是追新，而是选“大家都能上手、生态稳定、类型支持好”的组合。它的基础底座是 TypeScript 4.x+，后端框架推荐 NestJS 或 Express + tsrpc 二选一，前端推荐 React + TanStack Query 或 Vue + Pinia，数据库访问层使用 Prisma，环境变量校验使用 zod，API 层封装使用 axios 或 fetch。整套栈的核心是 TypeScript，所有选型都围绕“类型安全”这一个指标展开。

为什么后端我倾向于 NestJS？不是因为 Spring 那种重度依赖注入风格适合所有项目，而是 NestJS 的模块化结构与 t3code 的模块生成器天然契合。NestJS 本身用装饰器和类来组织路由与依赖，元数据很规整，自动生成代码的模板好写。Express 本身够简单灵活，但它的灵活性对工程模板来说反而是缺点，因为规范要管住灵活性，成本就高了。

Prisma 是我在实践里觉得最顺手的一个选择。它通过 schema 文件定义数据模型，然后自动生成完全的 TypeScript 类型，这一点正好配合 t3code 的“单一事实来源”原则。你只需要维护一份 schema，数据库表结构、后端类型、前端类型全部从它推导出来，省掉了手工维护多份文件的噩梦。也有人用 TypeORM 或 MikroORM，它们也不差，但从开箱体验和类型生成质量来说，Prisma 更适合模板化。

2.2 目录结构与模块分层约定

目录结构决定了团队协同的边界规则。t3code 的分层是严格的单向依赖，大致结构如下：

t3code-app/ ├── packages/ │ ├── shared/ # 共享类型、工具函数、常量 │ │ ├── types/ │ │ ├── utils/ │ │ └── constants/ │ ├── server/ # 后端服务 │ │ ├── src/ │ │ │ ├── modules/ # 业务模块（按模块划分） │ │ │ ├── common/ # 公共中间件、守卫、拦截器 │ │ │ ├── config/ # 环境变量校验与配置解析 │ │ │ └── main.ts │ └── web/ # 前端应用 │ ├── src/ │ │ ├── pages/ │ │ ├── api/ # 接口调用层 │ │ ├── stores/ # 状态管理 │ │ └── components/

这种结构的重点不是目录名称，而是依赖方向。shared 包不依赖 server 和 web，server 依赖 shared，web 依赖 shared。server 和 web 永远不直接互相引用，哪怕它们是同一个仓库里的两个包。

我用一个生活化的例子来类比：shared 像是两家人共同遵守的“物品交接清单”，server 是厨房负责做菜，web 是餐厅负责上菜。厨房和餐厅不直接对话，所有菜式、份量、价格都按照同一份清单来，谁要改，先把清单改了，然后两边一起受影响。这样就不会出现厨房偷偷换菜、餐厅还在按旧清单宣传的情况。

2.3 类型安全的契约设计：从数据库到前端一杆到底

t3code 最亮眼的地方在于契约设计。它定义了一条完整的类型链路：Prisma Schema -> 数据库类型 -> 后端接口 DTO -> 共享 API 响应类型 -> 前端页面状态。

具体怎么串起来？第一环，Prisma Schema 定义数据库模型，比如用户表：

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

第二环，Prisma 在每次 migrate 或者 generate 之后，自动生成User类型，后端可以直接引用。第三环，后端的接口出参类型不是自己手写的，而是从 Prisma 类型里派生出来的，比如用Pick或者 Omit 挑选必要字段，而不是定义一个新的“UserResponseDTO”类。第四环，这个接口出参类型通过 shared 包发布给前端。前端调接口时拿到的数据，就是这个类型的实例，天然是完整的类型信息。

这里有个关键细节：后端不能直接把 Prisma 生成的完整 User 类型暴露给前端。因为数据库模型可能在业务边界外泄露敏感字段，比如密码哈希、内部标记。t3code 的做法是强制每个接口声明自己的“公开视图类型”，用映射类型来清洗字段：

// 后端接口处 export type UserPublic = Pick<User, 'id' | 'email' | 'name' | 'createdAt'>;

这个UserPublic类型会进入 shared 包里，前端只能看到这个类型，不知道 User 表还有其他字段。这样既保证类型自动推导，又守住接口的字段边界，两边都安全。

3. t3code 的实操落地：从初始化到模块生成全流程

3.1 初始化项目与基础配置

初始化 t3code 项目并不复杂，前提是你已经装好了 Node.js 18 以上版本、pnpm 或者 yarn、Docker（用来跑数据库）。建议用 pnpm 管理 monorepo，因为 workspace 支持成熟，安装速度快，依赖隔离也干净。

第一步，用模板仓库初始化项目结构。如果是内部 git 仓库，直接克隆模板；如果自己从零搭，需要手动建立 packages/shared、packages/server、packages/web 三个包。第二步，在根目录配置 TypeScript 的 project references，让 shared 包的编译结果可以被 server 和 web 直接引用，同时保持各自独立的构建配置。

根目录的 tsconfig.json 大致长这样：

{ "compilerOptions": { "target": "ES2022", "module": "commonjs", "moduleResolution": "node", "strict": true, "declaration": true, "composite": true }, "references": [ { "path": "./packages/shared" }, { "path": "./packages/server" }, { "path": "./packages/web" } ] }

这里的composite: true很关键，它允许 TypeScript 的 Project References 机制在多个包之间做增量编译，shared 类型一变，引用了它的包会自动感知。

3.2 环境变量与配置管理怎么做

环境变量这个环节我吃过不少亏，所以单独拎出来讲。t3code 的做法是用 zod 写一个 config schema，在服务启动的最开始校验并解析全部环境变量，失败就立即退出并打印错误。

比如服务端要用的配置：

import { z } from 'zod'; const envSchema = z.object({ NODE_ENV: z.enum(['development', 'test', 'production']).default('development'), PORT: z.coerce.number().default(3000), DATABASE_URL: z.string().min(1), JWT_SECRET: z.string().min(32), REDIS_URL: z.string().url().optional(), }); export type EnvConfig = z.infer<typeof envSchema>; export const config: EnvConfig = envSchema.parse(process.env);

为什么做校验而不是直接读process.env？因为字符串类型的环境变量很容易出现低级错误：端口写成字符串、变量名拼错、漏配某个必填项。用 zod 定义 schema 之后，所有字段都会在启动时被检查，错误信息会明确指出“DATABASE_URL 缺失”或“JWT_SECRET 长度不足”，而不是等你跑到一半才崩溃。

这里有一条实践建议：JWT_SECRET 这类敏感值不要放进 .env 文件提交到 git 仓库，用 .env.example 提交占位符，真实值通过部署平台的 secrets 注入。本地开发可以用 .env.local，并保证 .gitignore 把它忽略掉。

3.3 数据模型定义与迁移流程

数据模型是 t3code 的源点，一切类型从这里开始。用 Prisma 做迁移时我建议遵循一套固定流程：改 schema -> 跑npx prisma format-> 跑npx prisma migrate dev-> 跑npx prisma generate。

第四步经常被忽略，但它恰恰是最重要的。Prisma generate 会把最新的模型类型重新生成到 node_modules 里，如果你不跑，那 server 代码里引用的 User 类型还是旧版本。建议把 generate 命令写进 package.json 的 postinstall 脚本里，这样不管谁安装依赖，类型都会自动同步最新。

定义数据模型时要注意两个实践点。一个是尽量使用语义化字段名，数据库里叫createdAt，PostgreSQL 里默认生成是带时区的 timestamp，但 Prisma 的 GraphQL 风格类型会自动映射，前端拿到的类型就是字符串或 Date，不用自己转换。另一个是关系字段要有意识地设计，Prisma 的关系会自动生成外键查询能力，但如果你不需要关系，宁可不建，减少隐式查询带来的性能隐患。

3.4 模块生成器：把重复劳动交给脚本

t3code 最有实用价值的就是它的模块生成器。实际开发中每新增一个业务模块，你就跑一条命令：

pnpm generate:module --name user-feedback

这条命令会自动做以下事情：在后端 modules 目录下创建 user-feedback 文件夹，生成 controller 与 service 的骨架；在 Prisma schema 里追加一个UserFeedback模型占位定义；在前端 pages 目录下创建 user-feedback 页面骨架；在 api 目录下创建对应的接口调用文件；在 shared/types 里导出这个模块的前后端共享类型。

生成完之后，项目可以直接跑起来，新模块的代码就已经能被路由访问到了。开发者只需要往骨架里填自己的业务逻辑，不再需要手工做那些接线工作。

模块生成器的实现并不复杂，它的核心是几个模板文件和一段 node 脚本。脚本里用简单的字符串替换、文件复制和路径拼接就能完成。注意命名统一使用 kebab-case，内部在代码里转成 PascalCase 和 camelCase。

这里我特别强调一个我在实现中踩过的坑：脚本一定要同时处理文件名、类名、路由前缀和数据库表名四处，四者如果有一处不一致，后面排查会让你怀疑人生。我自己写过一个早期版本，只改了类名没改路由前缀，导致接口路径还是旧的，前端一直请求 404，排查了半小时才发现是生成脚本的 bug。

3.5 前端接入 API 的具体模式

前端接 API 我推荐的方式是：每个模块一个 API 文件，API 文件里每个函数对应一个接口，函数返回值带完整的类型标注。配合 TanStack Query 或 SWR 使用，还能自动管理缓存、重试和请求取消。

以 React + TanStack Query 为例：

// packages/web/src/api/user.ts import { request } from '../utils/request'; import type { UserPublic } from '@t3code/shared'; export function fetchUserProfile(userId: string) { return request.get<UserPublic>(`/api/users/${userId}`); } // 在页面组件里 const { data: user, isLoading } = useQuery({ queryKey: ['user', userId], queryFn: () => fetchUserProfile(userId), });

这里我把request封装成了一个统一实例，它在内部做了三件事：自动附加认证 token；统一处理 HTTP 错误码，401 时跳转登录；把响应数据解包。封装的好处是业务代码不会到处出现 axios 细节，后续如果要换请求库，只改一个文件就够了。

4. 常见问题与排查技巧实录

4.1 前后端类型不同步引发的编译错误

使用 t3code 过程中最常遇到的问题，就是前端编译报错，说某个类型在 shared 里不存在。绝大多数情况下，原因是 shared 包没有重新构建，或者 monorepo 里没有正确链接到最新产物。

排查路径我建议按三步走。第一步，在 shared 包目录下跑一次pnpm build，确认类型文件是否已经生成；第二步，检查 server 和 web 的 tsconfig 里引用的路径是否指向 shared 的源码而非旧产物目录；第三步，检查 pnpm workspace 的软链接是否正常，必要时删掉 node_modules 重装。

有一个细节值得留意：如果你用的是 TypeScript Project References，要确保 shared 包里的declaration和composite都被打开，否则类型文件不会自动生成。

4.2 循环依赖与运行时崩溃

循环依赖在工程模板里很容易被触发，尤其是 shared 包里的工具函数互相引用、service 之间互相调用时。Node.js 在处理循环依赖时不会报语法错误，但经常出现“某个类未定义”或“undefined is not a constructor”的诡异运行时问题。

我的排查经验是：看到一个类似Cannot read properties of undefined (reading 'xxx')的错误，先往循环依赖方向想。用madge工具扫描一下依赖图：

npx madge --circular packages/server/src

如果检测出循环，高概率是某两个 service 互相引用了。解决办法通常是抽取一个公共的 service 层，或者用事件机制解耦，而不是简单地调换 import 顺序。import 顺序可能暂时掩盖问题，但下一次代码重组又会爆发。

4.3 环境变量校验失败但报错不明确

有时候配置明明没有明显问题，启动却失败，报错信息很笼统。这种情况大多是因为 zod 校验的默认错误信息不够友好。我建议在项目里自定义一个 env 校验的包装函数，捕获 zodError，逐条解析 issue 路径和 message，输出成表格形式：

❌ 环境变量校验失败： DATABASE_URL: Invalid url JWT_SECRET: String must contain at least 32 character(s)

这样看一眼就知道哪里漏了，不用去翻冗长的 error stack。这个技巧虽然简单，但能节省大量排查时间。

4.4 构建体积与首屏性能优化

t3code 模板默认是方便为主，没有在性能上做极致优化，但等到项目变大，构建体积一定会成为问题。我习惯在三个层面做优化。

第一层是代码分割。前端路由配置里使用 React.lazy 懒加载非首屏页面，让首屏只加载必要代码。第二层是依赖优化。用 bundle analyzer 找出体积过大的第三方库，比如 moment 换成 dayjs，lodash 按需引入。第三层是缓存优化。后端接口合理设置 Cache-Control 头，配合 Redis 缓存热数据，减少数据库压力。

一个有意思的细节：Prisma 生成的 client 体积并不小，但它的 tree-shaking 效果近年来已经改善很多，只要确保按需引用，不必过度担心。真正需要注意的往往是隐藏在 shared 包里的公共模块被全部打进每个 bundle 的情况，此时需要检查 sideEffects 字段配置。

5. 使用 t3code 的注意事项与优化建议

5.1 不是所有项目都适合 t3code

虽然我花了不少笔墨推荐这套东西，但必须诚实地说一句：不是所有项目都适合直接用 t3code。如果你的项目是一个几十个服务的大型微服务系统，每个服务独立部署、独立团队维护，monorepo 加共享类型的做法反而会拖累你，因为耦合度会始终存在。微服务之间用独立的 API 文档和 proto / OpenAPI 文件更合适，而不是一口吃成一个共享类型大包。

另外，如果你的团队对 TypeScript 本身还不熟悉，直接上这套模板可能适得其反。先让团队掌握类型推导、泛型、装饰器这些基础概念，再引入工程模板，效果会好得多。否则类型错误会成为新人每天遇到的第一个障碍，学习曲线过于陡峭。

5.2 三个值得坚持的团队约定

第一约定：接口返回类型必须从 shared 包导入，禁止在页面里手写 any 类型。这一条是所有类型安全的底线，一旦有人开了 any 的口子，类型保护就会逐渐失效。

第二约定：数据库模型变更必须走 Prisma Migration，禁止手工改表结构。手工 ALTER TABLE 确实快，但很快迁移历史和实际库结构就会脱节，导致同事本地环境起不来。

第三约定：新模块必须通过生成器创建，禁止手动复制其他模块再改名。这条规则看起来死板，但它保住了模块结构的长期整洁。手动复制极容易漏掉路由注册或类型导出，生成器才是可复现的工程资产。

这些约定看起来不起眼，但它们决定了一个中型项目能否在半年后依然保持初期架构的干净程度。我在实际维护过程中最大的感受是：架构的腐化不是哪一天突然发生的，而是每天“破一次例”累积出来的。t3code 的价值正在于把最常见、最合理的规则提前固化成代码和脚本，让团队的每一次提交都在标准的轨道上运行。你用它的时间越长，省下来的力气就越可观。