企业官网建设流程全解析

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

create-t3-app是 T3 Stack 官方提供的交互式 CLI 工具，用于快速搭建全栈、类型安全的 Next.js 应用骨架。本指南将围绕 CLI 的使用方式展开：从四种包管理器的启动命令、交互式引导的每一步提问，到全部命令行参数与底层源码执行流程，帮助你不仅会用，还能理解每一步背后发生了什么。读完本文，你可以熟练地用一条命令组合出 Tailwind CSS、tRPC、Prisma/Drizzle、NextAuth.js/BetterAuth 等模块，并掌握--noGit、--CI、--dbProvider等高级参数的适用场景。

create-t3-app 是什么？一个模板，还是一个生成器？

create-t3-app是一个由资深 T3 Stack 开发者构建的CLI 脚手架工具，而不是一个"开箱即用"的全包含模板。它的核心理念是模块化：每个组件（Tailwind、tRPC、Prisma、Drizzle、NextAuth.js、BetterAuth、ESLint/Biome 等）都是可选项，最终生成的"模板"完全根据你的具体需求动态组合而成。

npm create t3-app@latest

CLI 会在本地交互式地询问你的技术选型，然后生成一个为你量身定制、各部分已经互相集成好的项目（例如 Prisma 与 tRPC 之间的调用关系已预先接好），而不是给你一个塞满无用依赖的臃肿模板。这也意味着它不试图解决所有问题——像状态管理（zustand、redux）、部署方案这类更具体的问题，它期望你根据自己的应用场景自行引入。

从源码看，这一"按需组装"的实现落在 cli/src/installers/index.ts 的availablePackages常量中，它枚举了nextAuth、betterAuth、prisma、drizzle、tailwind、trpc、envVariables、eslint、biome、dbContainer共 10 个可安装单元，并通过 buildPkgInstallerMap 将用户选择映射为"是否启用 + 对应安装器"的注册表，后续脚手架阶段据此逐个执行安装。

T3 Axioms：驱动这个项目决策的三大原则

create-t3-app是一个有明确技术观点的项目，其决策依据是三条核心原则（见 cli/README.md）：

1. 解决实际问题（Solve Problems）：项目只添加能解决核心技术栈内"具体问题"的东西。它不会添加 zustand、redux 这类状态库，但会帮你把 NextAuth.js、Prisma、tRPC 集成好。
2. 负责任地拥抱前沿（Bleed Responsibly）：喜欢前沿技术，但只在低风险部位使用。例如不会押注激进的新型数据库技术（SQL 足够好），但愿意押注 tRPC——因为它本质只是函数，随时可以迁移走。
3. 类型安全不可妥协（Typesafety Isn't Optional）：项目的目标是"最快地启动一个全栈、类型安全的应用"，任何损害类型安全特性的决策都不应出现在这个项目里。

这三点解释了为什么create-t3-app的默认技术栈以 TypeScript 为根基，为什么 ORM 限定在 Prisma 与 Drizzle，也解释了为什么它坚持"克制"而非"堆砌"。

快速开始：四种包管理器一条命令启动

在任意空目录下，运行以下任意一条命令并按提示回答即可（命令对应源码文档 cli/README.md）：

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

CLI 会自动检测你当前使用的包管理器（通过npm_config_user_agent环境变量判断，见 cli/src/utils/getUserPkgManager.ts），后续的依赖安装、脚本提示都会沿用同一包管理器。包版本要求 Node.js>= 18.17.0（见 cli/package.json）。

交互式引导：CLI 会依次问你什么

不传任何参数直接运行时，CLI 会通过@clack/prompts弹出一系列交互问题（完整提问逻辑见 cli/src/cli/index.ts）。下面是按顺序出现的全部问题及默认值：

所有问题回答完成后，CLI 会把选项汇总为packages数组（cli/src/cli/index.ts），例如选择 tRPC + NextAuth.js + Prisma + Tailwind + ESLint 会得到["tailwind", "trpc", "nextAuth", "prisma", "eslint"]。

注意：认证与 ORM 的选择会在底层做兼容性约束。例如在 CI 模式下，若同时选择 Prisma 与 Drizzle、Biome 与 ESLint、NextAuth 与 BetterAuth，CLI 会判定为不兼容组合并直接退出（cli/src/cli/index.ts）。

命令行参数完整参考

除了交互式引导，CLI 还支持通过参数直接指定选项，适合脚本化和非交互环境（参数定义见 cli/src/cli/index.ts）：

以下参数标注为experimental，官方用途是 CI E2E 测试，必须配合--CI使用以跳过提问：

例如，在 CI 中要生成一个使用 App Router、SQLite、tRPC + Tailwind 的默认项目，可以运行：

npm create t3-app@latest -- --CI --trpc --tailwind --appRouter --dbProvider sqlite

此外有两个值得一提的行为：

• Yarn 3 不兼容警告：当检测到npm_config_user_agent以yarn/3开头时，CLI 会打印警告，提示 Yarn 3 当前不受支持、可能导致崩溃，建议改用 pnpm、npm 或 Yarn Classic（cli/src/cli/index.ts）。
• 非交互终端兜底：如果在 MinTTY（如 Git Bash）等非交互环境运行，交互提示会抛出IsTTYError，CLI 会捕获异常并询问"是否继续生成默认 T3 应用"，确认后自动用默认选项完成脚手架（cli/src/cli/index.ts）。

命令执行背后：从参数到项目的完整调用链

create-t3-app的主流程定义在入口文件 cli/src/index.ts，大致分为以下几个阶段：

1. 启动准备：渲染 ASCII 标题（renderTitle），检查 npm 版本并渲染版本警告（如果当前环境 npm 过旧）。
2. 收集选项：调用runCli()得到应用名、包列表、flags（noGit/noInstall/importAlias/appRouter）与数据库提供者。
3. 解析项目名：parseNameAndPath将dir/@mono/app拆分为 scoped 包名与目标目录。
4. 创建项目：createProject依次执行——
   • scaffoldProject：把 cli/template/base 目录整体复制到目标目录，并把_gitignore重命名为.gitignore；若目标目录已存在且非空，会询问"中止 / 清空目录 / 覆盖冲突文件"（cli/src/helpers/scaffoldProject.ts）；
   • installPackages：遍历用户选择的包，逐个执行对应 installer（如 prisma、trpc、tailwind 安装器），写入依赖与样板代码（cli/src/helpers/installPackages.ts）；
   • selectBoilerplate：根据 App Router / Pages Router 及已选包，从 cli/template/extras/src 中挑选对应的layout/page（App Router）或_app/index（Pages Router）样板文件覆盖到项目（cli/src/helpers/selectBoilerplate.ts）；
   • 若未选择 Tailwind，则额外复制index.module.css作为替代样式方案。
5. 写回 package.json：把解析出的包名写入项目package.json的name字段，记录ct3aMetadata.initVersion，并写入packageManager字段（bun 除外，因为 bun 暂不支持该字段）。
6. 处理自定义 import alias：若用户指定的 alias 不是默认的~/，则遍历生成文件并批量替换（setImportAlias）。
7. 安装依赖：installDependencies按包管理器分流——npm 直接继承 stderr 显示进度条；pnpm/yarn 通过 ora spinner 展示进度；bun 隐藏 stdout（cli/src/helpers/installDependencies.ts）。若选了 Prisma，还会额外执行npx prisma generate生成客户端；随后运行 Prettier 格式化整个项目。
8. 初始化 Git：若未传--noGit，调用initializeGit——检测 git 是否安装、目标目录是否已在 git 仓库内，并尊重init.defaultBranch配置（默认main）初始化仓库并git add .；对 git 版本低于 2.28 的会降级使用git init+symbolic-ref（cli/src/helpers/git.ts）。
9. 打印后续步骤：根据项目情况输出cd、install、db:push（Prisma/Drizzle 项目）、填写.env（NextAuth 项目）、dev、git commit等提示（cli/src/helpers/logNextSteps.ts）。

生成的模板长什么样

即使不选任何附加包，基础模板也自带一套完整的 Next.js + TypeScript 环境。以 cli/template/base/package.json 为例，默认依赖包括：

• next（^15.5.9）、react/react-dom（^19.2.3）
• @t3-oss/env-nextjs（^0.12.0）与zod（^3.24.2），用于类型安全的环境变量校验
• 开发依赖typescript（^5.8.2）、@types/node、@types/react等

脚本内置了dev（next dev --turbo）、build、start、preview、typecheck。

选择不同模块后，脚手架会组合出对应功能。例如选择 tRPC 后，项目会包含src/trpc/下的 query-client、react provider 与 server 封装，以及src/server/api/下的 router 结构；选择认证时，会在src/server/auth/（NextAuth）或src/server/better-auth/（BetterAuth）生成配置，并与 ORM 集成（参见 cli/template/extras/src/server 下的多版本组合文件）。数据库提供者选择 MySQL/PostgreSQL 时，dbContainer安装器还会附带start-database.sh脚本（模板见 cli/template/extras/start-database），方便本地起容器。

生成后的第一步

脚手架完成后，CLI 会打印 "Next steps" 提示，典型流程是：

cd your-app npm run db:push # 若选了 Prisma / Drizzle，先推送数据库 schema # 若选了 NextAuth.js，先根据提示填写 .env 中的密钥 npm run dev git add . git commit -m "initial commit"

（npm/bun 使用run前缀，pnpm/yarn 直接pnpm db:push、pnpm dev；项目名传.时不会生成子目录，直接在当前目录脚手架。）

更深入的使用文档（如环境变量、首次运行、各模块详解）可在仓库的 www/src/pages/en/installation.mdx 及 www/src/pages/en/usage 目录下找到；想要参与贡献的开发者，请先阅读仓库根目录的 CONTRIBUTING.md，其中说明了分支策略与本地开发环境。

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