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-appT3 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 Axioms1. 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部分项目名称—— 通过validateAppName校验见 validateAppName.ts仅允许小写字母、数字、-、_及作用域包名格式TypeScript 还是 JavaScript—— 选择 JavaScript 时 CLI 会开玩笑地回一句Wrong answer, using TypeScript instead默认仍用 TypeScript呼应Typesafety 不是可选项的公理是否使用 Tailwind CSS是否使用 tRPC认证方案—— None / NextAuth.js / BetterAuthORM—— None / Prisma / Drizzle是否使用 Next.js App Router默认是数据库提供方—— SQLite (LibSQL) / MySQL / PostgreSQL / PlanetScale默认 SQLiteLinter—— ESLint/Prettier 或 Biome是否初始化 Git 仓库并暂存变更是否运行包管理器安装依赖自定义 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: truedbContainer仅在选择 MySQL 或 PostgreSQL 时自动启用——其余全部由用户的选择决定完美呼应每个组件可选、基础栈服从需求的理念。每个安装器如 nextAuth.ts、prisma.ts、trpc.ts负责独立的配置注入互不干扰。生成流程按选择拼装模板生成过程的整体编排在 createProject.ts 中scaffoldProjectscaffoldProject.ts从template/base复制基础 Next.js 骨架含_gitignore重命名为.gitignore等处理若目标目录已存在且非空会提示中止 / 清空 / 覆盖三种处理方式installPackages按所选组件执行各安装器写入依赖与配置selectBoilerplateselectBoilerplate.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-applatest # yarn yarn create t3-app # pnpm pnpm create t3-applatest # bun bun create t3-applatest脚手架完成后即可进入新应用开始开发。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-applatest --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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考