企业官网建设流程全解析

create-t3-app 入门导读：T3 Stack 的组成、设计哲学与三大公理

【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app

T3 Stack 是一套以极简、模块化、全栈类型安全为核心哲学的 Web 开发技术栈，而create-t3-app则是其官方 CLI 脚手架工具。本篇指南将带你理解 T3 Stack 由哪些技术组成、create-t3-app与普通模板的本质区别，以及驱动该项目的三条核心公理（T3 Axioms），并结合当前仓库源码，深入剖析这些设计理念是如何在 CLI 的交互流程与项目生成逻辑中被逐条落地的。读完本文，你将能判断 T3 Stack 是否适合你的下一个项目，并理解该工具每个选项背后的设计意图。

T3 Stack 是什么

"T3 Stack" 是一个聚焦于简单性、模块化（modularity）与全栈类型安全的 Web 开发技术栈。它不是一个锁定死板的框架组合，而是一套可以自由取舍、按需拼装的组件集合。

其核心组件包括：

• Next.js—— 全栈 React 框架，负责页面渲染、路由与 API 层；
• TypeScript—— 为整个应用提供静态类型系统，是全栈类型安全的基石。

此外，Tailwind CSS几乎总是被包含在内，用于样式方案。如果你的项目涉及任何后端逻辑（"anything resembling backend"），文档还推荐追加以下三件套：

• tRPC—— 端到端类型安全的远程过程调用层；
• Prisma—— 类型安全的 ORM 数据库层；
• NextAuth.js—— 认证方案。

你可能会注意到组件"有点多"——这正是刻意设计的结果。T3 Stack 在核心上是模块化的，你可以根据需求自由地"换入换出"组件：需要什么就加什么，不需要什么就删掉什么。基础栈始终服从于你的具体需求。

create-t3-app 是什么？是模板（template）吗？

"算是吧。"create-t3-app是一个由经验丰富的 T3 Stack 开发者构建的CLI（命令行工具），目标是把模块化 T3 应用的搭建流程简化到极致。它的关键特性是：每一个组件都是可选的，"模板"完全根据你的具体选择动态生成。

在历经无数项目实践、多年深耕这套技术之后，维护者们积累了大量的经验与观点，并尽可能地把这些洞察"编码"进了 CLI 中——从默认选项、目录结构到脚手架生成逻辑，处处体现着这些沉淀。

需要特别强调：它不是一个包罗万象的全包含模板。项目方期望你自带那些解决你自己应用特定需求的库。他们不打算为状态管理、部署这类更具体的问题预设方案，但确实给出了一些推荐清单，参见 other-recs。

T3 Axioms：驱动项目的三条核心公理

官方明确表示，这是一个opinionated（有鲜明主张的）项目。团队共享若干关于"如何构建"的核心信念，并将它们作为一切决策的基础。这些信念被总结为三条公理（T3 Axioms）：

1. Solve Problems（解决真实问题）

开发者很容易落入"什么都加进去"的陷阱——但项目方明确表示不想要这样。凡是被加入create-t3-app的东西，都必须解决核心技术栈内真实存在的某个具体问题。

这一原则的直接影响是：项目不会加入像zustand、redux这类状态管理库（因为 React/Next.js 已足以覆盖常见状态管理场景），但会加入 NextAuth.js，并替你完成 Prisma、tRPC 的集成——因为认证与后端类型安全是真实存在、需要专门方案的问题。

2. 冒险，但请负责（Bleed Responsibly）

团队热爱前沿技术——新技术带来的速度与乐趣是实实在在的。但他们认为关键在于有责任地采用前沿技术：把风险较高的技术用在风险较低的环节。

例如，他们⛔️ 不会把赌注押在有风险的"新型数据库"上（"SQL 就很棒！"），但✅ 乐于押注 tRPC——因为它本质只是一些普通函数（functions），日后迁移成本极低、可以轻松脱离。这条公理给出了一个实用的取舍框架：评估新技术时，先问"如果它不行，我跑路的成本有多高？"

3. Typesafety 不是可选项

create-t3-app的既定目标，是提供最快的方式来启动一个全栈、类型安全的 Web 应用。团队对类型安全极为认真，因为它在生产环境中能显著提升开发效率、帮助我们减少 Bug。

由此引出一条严格的底线：任何会损害create-t3-app类型安全本质的决策，都应该放到另一个项目中去决定——也就是说，类型安全在这个项目里是不可谈判的。

从公理到实现：CLI 如何把理念落成代码

三条公理并非只是口号，它们直接塑造了 CLI 的实现。在 cli/src/cli/index.ts 中可以看到，交互式问答把"模块化、按需选择"落到了实处；而"Solve Problems"与"模块化"体现在每个组件都可选、互不强制的安装器架构上。

交互式选择：一次一问，按需拼装

create-t3-app启动后，会通过 @clack/prompts 依次向你提问（cli/src/cli/index.ts 中p.group部分）：

1. 项目名称—— 通过validateAppName校验（见 validateAppName.ts，仅允许小写字母、数字、-、_及作用域包名格式）；
2. TypeScript 还是 JavaScript？—— 选择 JavaScript 时 CLI 会开玩笑地回一句"Wrong answer, using TypeScript instead"（默认仍用 TypeScript），呼应"Typesafety 不是可选项"的公理；
3. 是否使用 Tailwind CSS？；
4. 是否使用 tRPC？；
5. 认证方案—— None / NextAuth.js / BetterAuth；
6. ORM—— None / Prisma / Drizzle；
7. 是否使用 Next.js App Router？（默认是）；
8. 数据库提供方—— SQLite (LibSQL) / MySQL / PostgreSQL / PlanetScale（默认 SQLite）；
9. Linter—— ESLint/Prettier 或 Biome；
10. 是否初始化 Git 仓库并暂存变更？；
11. 是否运行包管理器安装依赖？；
12. 自定义 import alias—— 默认~/。

这些回答最终被收集进packages: AvailablePackages[]数组，作为后续安装器的输入。值得一提的是，若在非交互式终端（如 Git Bash 的 MinTTY）运行，CLI 会捕获IsTTYError，提示需要交互式终端，并征询是否改用默认配置继续脚手架。

安装器架构：每个组件独立且可选

组件可选性在 cli/src/installers/index.ts 中体现为availablePackages常量与PkgInstallerMap映射。当前可安装组件包括：

nextAuth、betterAuth、prisma、drizzle、tailwind、trpc、envVariables、eslint、biome、dbContainer。

其中envVariables恒为启用（inUse: true），dbContainer仅在选择 MySQL 或 PostgreSQL 时自动启用——其余全部由用户的选择决定，完美呼应"每个组件可选、基础栈服从需求"的理念。每个安装器（如 nextAuth.ts、prisma.ts、trpc.ts）负责独立的配置注入，互不干扰。

生成流程：按选择拼装模板

生成过程的整体编排在 createProject.ts 中：

1. scaffoldProject（scaffoldProject.ts）从template/base复制基础 Next.js 骨架（含_gitignore重命名为.gitignore等处理）；若目标目录已存在且非空，会提示中止 / 清空 / 覆盖三种处理方式；
2. installPackages按所选组件执行各安装器，写入依赖与配置；
3. selectBoilerplate（selectBoilerplate.ts）根据tailwind、trpc、认证等组合，从template/extras/src/app|pages下数十个预置变体中挑选对应的layout/page或_app/index文件。

例如selectIndexFile会依据 tRPC、Tailwind、NextAuth、BetterAuth 的启用组合，从base.tsx、with-trpc.tsx、with-auth-trpc-tw.tsx等候选文件中精确匹配——这正是"生成你的专属模板"的实现机制。

版本固定：性能与稳定性的权衡

依赖版本并非运行时从 npm 注册表拉取，而是硬编码在 dependencyVersionMap.ts 中（如next-auth: 5.0.0-beta.25、prisma: ^6.6.0、@trpc/*: ^11.0.0、tailwindcss: ^4.0.15）。源码注释明确说明：这能显著提升性能，避免每次脚手架都向 npm 发起请求。这也呼应了公理中对稳定与高效的追求。

如何开始使用

在你的终端中运行以下任一命令（具体以你使用的包管理器为准），然后回答交互式提问即可：

# npm npm create t3-app@latest # yarn yarn create t3-app # pnpm pnpm create t3-app@latest # bun bun create t3-app@latest

脚手架完成后，即可进入新应用开始开发。CLI 还提供若干高级与实验性参数，例如：

• [dir]—— 直接指定项目目录名；
• --noGit—— 跳过 Git 仓库初始化；
• --noInstall—— 只生成项目、不安装依赖；
• -y, --default—— 跳过所有提问，直接使用全部默认选项（默认组合为 NextAuth、Prisma、Tailwind、tRPC、ESLint，见 cli/index.ts 中defaultOptions）；
• --CI及配套的--trpc、--prisma、--drizzle、--nextAuth、--tailwind、--dbProvider、--appRouter等实验性 flags —— 用于 CI 场景下免交互生成应用（不提供--CI时其余 flags 不生效）。

例如以下命令会生成一个包含 tRPC 与 Tailwind CSS 的应用：

pnpm dlx create-t3-app@latest --CI --trpc --tailwind

小结

T3 Stack 与create-t3-app的核心价值不在于"又多了一个脚手架"，而在于一套可复制的构建信念：只解决真实问题、有责任地拥抱新技术、类型安全绝不妥协。这三条公理贯穿了从交互式问答、模块化安装器到按需拼装模板的每一行实现代码。如果你认同这套取舍哲学，create-t3-app将是启动一个全栈类型安全 Next.js 应用的最快路径——而如果你不认同，至少它的模块化设计也能让你清楚地知道自己在"换掉"什么。

【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app