企业官网建设流程全解析

做全栈开发这几年，我越来越偏爱那些“约定优于配置”的样板工程。t3code是我目前在个人项目和团队内部用得最顺手的全栈模板，它把TypeScript、Next.js、Tailwind CSS、tRPC、Prisma和NextAuth打包成一套开箱即用的代码骨架，核心思路只有一个：让类型安全从数据库一直贯穿到浏览器端的按钮。你写的每个接口、查的每张表、渲染的每个字段，统统在一个类型系统里闭环运行，前端再也不会因为“后端返回少了一个字段”而临时补判断，后端也不会因为“前端传了奇怪格式”而在运行时才炸出来。

这个项目适合谁？独立开发者想快速验证产品原型、全栈新手想省去繁琐的工程配置、以及被前后端联调文档折磨过的小团队，都可以拿它当起点。它不是框架，也不是库，而是一整套可以照着跑、拆开改的工程化方案。这篇文章我会从选型逻辑、目录结构、核心模块、实操落地到问题排查完整拆一遍，并且会把我踩过的坑和优化过的细节一并写出来。

1. 核心设计思路：为什么这套组合能自洽

1.1 语言层的统一：TypeScript是地基不是装饰

很多人把TypeScript当成给变量加类型注解的小工具，但在t3code这套体系里，TypeScript是整个项目存在的前提。它要管的不只是某个函数入参出参的类型，而是数据库表结构、API请求参数、组件Props、状态管理数据这几层之间的“一致性契约”。

为什么强调这一点？因为在传统的前后端分离开发里，前端拿到的是后端接口返回的JSON，这个JSON长什么样，你只能通过文档或者抓包去看。一旦后端改了字段名，前端要么编译期毫无察觉、运行时报undefined，要么就得靠人肉搜索一个个找出来改。而t3code的做法是：用一套共享的类型定义把数据库和前端组件直接“焊死”，数据库表结构变了，前端编译立刻报错，改错成本被压到了最低。

从工程实践来看，这种“类型优先”的地基选型还有一个隐性收益：新成员接手项目时不需要读几十页接口文档。他们只要看看.ts文件里的类型定义就知道数据结构是什么，产生歧义的概率低得多。我给团队引入t3code之后，前后端扯皮的会议次数肉眼可见地变少了，这不是玄学，是类型系统确实把一部分模糊地带拿到了编译期解决。

1.2 数据同步不再靠猜：tRPC如何替代REST与GraphQL

在t3code之前，我试过REST，也试过GraphQL。REST的问题是接口多了以后，前端要自己拼URL、自己记参数和响应结构，每加一个接口就要同步一次文档。GraphQL虽然解决了按需取数的问题，但引入的Schema配置、Resolver分层和缓存策略，对中小型项目来说反而有些偏重。

tRPC走的是另一条路：你直接在服务端定义函数（procedure），前端像调用本地函数一样调用它，不需要生成URL、不需要手动声明请求类型，tRPC会利用TypeScript的推断能力把入参和出参类型自动传递给前端。换句话说，你写了一个getUserById的函数，前端代码里敲trpc.user.getUserById.useQuery({ id: 1 })，返回值的类型就已经是后端定义的类型了。

这个“像调用本地函数”的体验一开始会让人觉得不真实。我第一次把tRPC接入项目时，甚至怀疑编辑器是不是用了什么魔法。后来翻了源码才明白，它本质上是创建一个类型安全的RPC协议，服务端的router定义会作为类型参数传给前端的client，所有类型都由TypeScript自动推导，不需要额外生成代码。这种模式特别适合单体全栈应用，因为它省掉了接口文档、字段映射、数据校验这一整套繁文缛节。

当然，它不是银弹。如果你的架构是多服务独立部署，或者有大量第三方需要走标准HTTP接口，tRPC的优势会打折扣。但在t3code定位的“一个应用搞定前后端”的框架里，它是最好的选择。

1.3 样式与渲染：Tailwind和Next.js的取舍

Tailwind CSS在t3code里负责一切视觉表达。早期我也有过“Tailwind会让HTML变得又长又乱”的顾虑，实际用下来发现这种原子化CSS的收益大于成本。它的好处不在于少写几行CSS，而是提供了严格的视觉约束：间距、颜色、字体大小都有既定刻度，团队协作时不会出现一个人用16px、另一个人用15px的混乱局面。如果你熟悉设计系统，Tailwind本质上就是一套被搬进代码里的设计系统。

Next.js则是整个应用的“骨架”。它承担路由、渲染策略以及API路由宿主。t3code默认使用Next.js的App Router或Pages Router（取决于初始化选项），提供了SSR、SSG、CSR按需选择的自由。这一层非常重要——同样是数据加载，首页可能需要SSG提前渲染、后台管理页可能直接用CSR、需要实时数据的页面又该走SSR。Next.js让这些策略混用而不必重写架构。

2. 项目结构全拆解：每个目录都有它存在的理由

2.1 从初始化开始：t3code长什么样

用t3code启动项目的命令很简单，初始化时会让你交互式选择需要的模块。这里我强烈建议第一次用的时候保留所有选项，最大程度理解它各模块之间的协作方式。初始化完成后的目录结构大致如下：

my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ │ ├── api/ │ │ │ └── trpc/ │ │ │ └── [trpc].ts │ │ ├── _app.tsx │ │ └── index.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ │ ├── post.ts │ │ │ │ └── user.ts │ │ │ └── root.ts │ │ ├── auth.ts │ │ └── db.ts │ ├── styles/ │ │ └── globals.css │ └── utils/ │ └── api.ts ├── .env ├── next.config.js ├── package.json └── tsconfig.json

这里最核心的目录是src/server。db.ts负责初始化Prisma Client，auth.ts负责NextAuth配置，api/routers下面才是真正的业务逻辑代码。src/utils/api.ts暴露了前端的tRPC客户端实例，并注入类型。这就是类型共享的关键管道：后端router的类型参数被抽出来传给了前端client。

我没见过多少模板会把“后端”和“前端”放在同一路径层级下还能保持清晰边界的。t3code的做法是物理分层：src/server只管数据库、鉴权和业务逻辑，src/pages只管路由和UI。这样当你需要搞清楚一个功能从请求到响应的完整链路时，路径非常明确，不用在几十个文件夹之间来回跳。

2.2 类型共享机制：单仓库内如何做到不复制类型

大多数项目的类型共享靠的是建立一个types.ts到处import，但这种静态共享有几个问题：第一，类型分散在各处后容易失去约束力；第二，后端改了表结构，前端类型并不会自动跟着变。t3code用tRPC的类型推断天然解决了这个问题。

后端在router里定义的每个查询和变更操作，会自动被收集进一个AppRouter类型。前端引入这个类型后，客户端对象的所有方法、入参、响应值都自动获得类型。也就是说，你根本不需要手动写任何API类型。

这背后其实是TypeScript的infer能力。tRPC导出一个inferRouterOutputs等工具类型，你可以直接用来提取任何procedure的输出类型。举个例子，如果要获取文章列表的返回类型，可以这样写：

import type { inferRouterOutputs } from "@trpc/server"; import type { AppRouter } from "~/server/api/root"; type RouterOutput = inferRouterOutputs<AppRouter>; type PostList = RouterOutput["post"]["getAll"];

这里的PostList类型是自动生成的，数据库里Article表加了字段，它就会跟着变。我在很多文章里看到过“不要手动维护类型”的呼吁，但真正能做到这一点的框架并不多，t3code和tRPC的组合是我见过最省心的。

2.3 配置文件的细节：tsconfig、prettier、eslint的工程意义

很多模板的配置文件看似是“压舱石”，其实是“面子工程”。t3code的配置文件则不同，几乎每一条都有实际意义。

tsconfig.json默认开启了严格模式、路径别名@/或~映射，还做了noUncheckedIndexedAccess这类严格检查。这个选项建议保持开启——它能把你从“数组越界才会暴露”的隐患中救回来。用过一段时间后你会发现，TypeScript的严格模式越严格，被动调试的时间越少。

eslint和prettier配置则是团队协同的基石。t3code默认继承next/core-web-vitals和prettier规则，还加了@tanstack/query的推荐规则。我自己在实际开发中，会在保存时自动执行lint和format，这样不管是谁提交代码，风格都是同一个模子出来的，code review只聊逻辑不聊格式。

3. 核心模块实现解析：认证、数据、渲染三板斧

3.1 认证体系：NextAuth集成与Session类型

认证是全栈应用最先要碰的墙。t3code默认集成了NextAuth（也就是Auth.js），但值得注意的是，它的Session类型也被“类型化”了。默认的getServerSession返回的session.user中只有name、email、image这些基础字段，但实际开发中我们常常需要存角色、用户ID甚至自定义的用户状态。

在t3code里，扩展Session类型的方式是在src/types/next-auth.d.ts里声明模块增强：

import { DefaultSession } from "next-auth"; declare module "next-auth" { interface Session { user: { id: string; role: "USER" | "ADMIN"; } & DefaultSession["user"]; } }

之后在NextAuth的callbacks里把数据库查出的用户信息挂到session.user上，那么整个应用的所有地方都能直接拿到带角色的session对象，并且类型完全自动。这里有个细节容易踩坑：别忘了同时扩展JWT接口，否则role字段在JWT回调里会丢失。我见过不少项目因为只扩展了Session类型、没扩展JWT类型，导致刷新Token后自定义字段消失，排查了半天才发现是这个原因。

认证路由的保护则配合中间件或getServerSideProps来做。比如后台管理页，在getServerSideProps里先取session，没登录就直接redirect到登录页。这样服务端渲染和权限校验一气呵成，前端不需要额外做路由守卫，也不会出现页面闪现后再跳走的尴尬。

3.2 数据模型与数据库访问：Prisma如何与tRPC协作

Prisma在t3code里充当数据访问层。它的核心是prisma/schema.prisma文件，定义了数据模型和数据库连接。自动生成的Prisma Client提供了强类型查询API，把数据库表的字段映射成了TypeScript类型。

一个典型的Prisma模型长这样：

model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

改完schema后记得跑npx prisma db push或npx prisma migrate dev同步数据库。在t3code里，tRPC的router和Prisma的协作方式是：在procedure内部直接调用db实例。比如文章列表：

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import { db } from "~/server/db"; export const postRouter = createTRPCRouter({ getAll: publicProcedure.query(async () => { const posts = await db.post.findMany({ orderBy: { createdAt: "desc" }, include: { author: { select: { name: true } } }, }); return posts; }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string() })) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { ...input, authorId: ctx.session?.user.id ?? "" }, }); }), });

这里createTRPCRouter定义了一个子路由，publicProcedure换成protectedProcedure就可以要求鉴权。input参数用Zod声明校验，前端调用时的入参类型和这里完全一致，两端不用写任何重复校验逻辑。

我理解很多人看到Prisma和tRPC时会觉得“两个新东西叠加学习成本高”，但实际跑一次之后会发现，它们解决的是同一件事的两面：Prisma解决了数据层的类型安全和查询简洁性，tRPC解决了传输层的类型安全和调用简洁性，两者合起来，从数据库字段到页面组件的链路就彻底打通了。这个流畅度是传统REST + ORM架构很难达到的。

3.3 页面渲染策略：SSR、SSG、CSR的适用场景

Next.js提供了多种渲染方式，t3code中根据场景选择不同策略。我的建议是：

• 纯展示内容、更新频率低，用SSG（静态生成）。Next.js会在构建时生成静态HTML，访问速度最快。
• 依赖Session、需要实时数据，用SSR。比如用户个人中心，每次请求都拿最新的session和数据。
• 交互密集、登录后的工作台，用CSR。让数据在客户端通过tRPC和React Query拉取，体验更接近SPA。

在t3code里，一个典型的SSR页面会用trpc.post.getAll.useQuery()配合React Query实现。React Query在t3code中默认附带，它为数据请求提供了缓存、重试、失效重取等能力。举例来说，创建一篇新文章后，想刷新文章列表，只需要执行：

const utils = trpc.useUtils(); await utils.post.getAll.invalidate();

这一行代码就会让所有引用post.getAll的组件重新拉取数据，不需要手动管理全局状态。React Query的缓存策略还能减少不必要的重复请求，比如多个组件同时调用post.getAll，实际只会有一次网络请求，这在工作台类页面里优化效果非常明显。

4. 实操：从零跑通一个t3code全栈应用

4.1 环境准备与初始化参数选择

开发t3code项目的前置环境非常简单：Node.js 18以上、包管理器npm/pnpm/yarn任选、以及一个可用的数据库（SQLite起步最方便，生产推荐PostgreSQL或MySQL）。

初始化命令：

npm create t3-app@latest my-project

交互界面会让你选择模块。我的建议是如果项目刚起步，全部选中：Next.js、Tailwind CSS、tRPC、Prisma、NextAuth，多余的不用。选择完成后，进入项目：

cd my-project npm install

这里要注意两件事。第一，项目路径不要带空格和中文，避免后续工具链解析问题。第二，初始化过程会生成.env文件，里面是空的环境变量模板，需要手动补充才能启动。

4.2 配置数据库与鉴权环境变量

在.env文件中你至少需要配置三个关键变量。以使用默认的SQLite为例：

DATABASE_URL="file:./db.sqlite" NEXTAUTH_SECRET="your-secret-key"

生成NEXTAUTH_SECRET可以直接用命令openssl rand -base64 32。这是一个必备的签名密钥，用于加密Session Token，泄露或随意配置会导致认证失效。

然后运行：

npx prisma db push

这个命令会把schema.prisma中的模型同步到数据库。如果是SQLite，会在prisma目录下生成一个db.sqlite文件。如果使用PostgreSQL，需要注意把DATABASE_URL改成完整连接串，例如：

DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

数据库地址配好后，启动开发服务器：

npm run dev

打开http://localhost:3000就能看到默认页面。这时候你其实已经拥有了一个带类型安全的全栈环境，只是还没写业务代码而已。

4.3 加入第一个业务模块：以“文章发布”为例

假设我们要做一个简单的博客发布功能。先改Prisma schema，加文章模型，然后执行npx prisma db push。

接着在src/server/api/routers下新建post.ts，写我们前面的postRouter。然后在src/server/api/root.ts里把postRouter挂载到主路由上：

import { postRouter } from "./routers/post"; export const appRouter = createTRPCRouter({ post: postRouter, });

前端页面就可以直接使用了。在src/pages/index.tsx里：

import { api } from "~/utils/api"; import type { NextPage } from "next"; const Home: NextPage = () => { const { data: posts, isLoading } = api.post.getAll.useQuery(); if (isLoading) return <div>Loading...</div>; return ( <div> {posts?.map((post) => ( <div key={post.id}> <h2>{post.title}</h2> <p>{post.content}</p> </div> ))} </div> ); }; export default Home;

从这个例子能看到，我没有写任何fetch、axios或URL拼接代码，也没有定义任何前端接口类型，所有东西都是自动的。而且由于类型已同步，post字段无法拼错，编辑器会直接提示。

4.4 生产环境构建与部署注意事项

npm run build是生产构建的第一步。在构建期，Next.js会预渲染所有SSG页面，这时代码里如果有数据库查询或环境变量读取，必须保证这些资源在构建机器上可访问。比如若使用PostgreSQL，构建机需要能连上数据库，否则取数阶段的SSG页面会报错。

环境变量在部署时和本地不同。很多托管平台支持直接在后台面板设置环境变量，也可以用.env.production文件。记得把NEXTAUTH_URL配置成线上的完整地址，否则OAuth回调地址不匹配会导致无法登录。

部署平台方面，我试过Vercel和自建VPS。t3code对Vercel支持很友好，因为Next.js本身就是Vercel家的产品，构建和部署基本无感。自建则需要保证Node服务常驻，配合Nginx反向代理，这里就不展开了。

5. 常见问题排查与优化建议

5.1 类型不同步：tRPC后端改了，前端没变

这是新手最容易困惑的地方。后端router返回类型改了，前端项目编译不报错，看起来类型没有更新。原因往往是开发服务器没有热重载类型信息，或者IDE的类型缓存没有刷新。解决方式：重启开发服务器、Ctrl+Shift+P找到“TypeScript: Restart TS Server”执行一次，通常就能恢复。

更隐蔽的情况是：在root.ts里漏了挂载新router。写过一次后我就养成了习惯，新建router文件后第一件事就是去root.ts挂载，否则前端怎么调用都是undefined。

5.2 部署时的常见构建错误与处理

部署阶段遇到过两个高频问题。第一个是“Prisma Client没有生成”，报错类似@prisma/client did not initialize yet。解决方式是在构建前执行npx prisma generate。很多部署平台可以配置构建命令，把这一步加进去一劳永逸：

npx prisma generate && npm run build

第二个是“数据库表不存在”，通常出现在新环境第一次部署时。因为prisma db push不会自动在部署平台运行。建议在数据库初始化阶段手动执行一次迁移命令，或者在构建脚本里加入prisma migrate deploy。

5.3 常见问题速查表

5.4 性能与体验优化记录

t3code默认已经做了很多优化，但我实测后还是有几个值得动手的地方。第一，tRPC请求的合并。React Query支持httpBatchLink，t3code默认用的是这个配置。这意味着在同一个事件循环内发的多个tRPC请求会被合并成一个HTTP请求发出，对列表页和仪表盘页的加载性能提升非常明显。

第二，SSG页面的数据更新策略。纯静态页面部署后，如果数据库内容变了，页面不会自动更新。这时候可以引入revalidate参数，开启Next.js的ISR（增量静态再生）。例如在页面组件中导出：

export const revalidate = 60;

这个60秒的意思是页面最多缓存60秒，之后有请求就会触发后台重新生成。既保留了SSG的快速响应，又避免了内容永远不更新的尴尬。

第三，大列表的分页。Prisma默认findMany会返回所有匹配记录，数据量大时页面会非常臃肿。配合tRPC查询参数，给getAll加上take和skip两个参数，再结合前端React Query的keepPreviousData和滚动加载机制，就可以轻松实现无限滚动，而不影响类型安全。

6. 我从t3code里收获的工程经验

用了t3code这段时间，最大的感受并不是某个框架“很酷”，而是一套完整类型安全的开发模式确实能改变团队的协作方式。过去写API文档、定义TypeScript interface、前后端联调所花的时间，在这里几乎被压缩到了零。更重要的是，它让新成员在前三天就能上手写功能，而不是先读一周文档。

我建议你在使用它的时候，不要把自己当成“模板的消费者”，而应该当成一个“改造者”。当你遇到不适合你的场景，比如需要加Redis缓存、需要额外的事件队列，可以逐步把它扩展成适合你业务形态的架构。毕竟t3code的价值在于起点足够规范，而不是终点只有一条路。

如果让我给一个最简单的行动建议，那就是别看了，直接跑一个项目试试。用十分钟写出一个带数据库和鉴权的功能，然后回头再想想，你之前的全栈开发流程是不是还有不少时间被浪费在了那些“类型本可以帮你自动搞定”的事情上。