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-appcreate-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-applatestCLI 会在本地交互式地询问你的技术选型然后生成一个为你量身定制、各部分已经互相集成好的项目例如 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解决实际问题Solve Problems项目只添加能解决核心技术栈内具体问题的东西。它不会添加 zustand、redux 这类状态库但会帮你把 NextAuth.js、Prisma、tRPC 集成好。负责任地拥抱前沿Bleed Responsibly喜欢前沿技术但只在低风险部位使用。例如不会押注激进的新型数据库技术SQL 足够好但愿意押注 tRPC——因为它本质只是函数随时可以迁移走。类型安全不可妥协Typesafety Isnt Optional项目的目标是最快地启动一个全栈、类型安全的应用任何损害类型安全特性的决策都不应出现在这个项目里。这三点解释了为什么create-t3-app的默认技术栈以 TypeScript 为根基为什么 ORM 限定在 Prisma 与 Drizzle也解释了为什么它坚持克制而非堆砌。快速开始四种包管理器一条命令启动在任意空目录下运行以下任意一条命令并按提示回答即可命令对应源码文档 cli/README.md# npm npm create t3-applatest # yarn yarn create t3-app # pnpm pnpm create t3-applatest # bun bun create t3-applatestCLI 会自动检测你当前使用的包管理器通过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。下面是按顺序出现的全部问题及默认值提问可选值默认值项目名称What will your project be called?任意合法应用名my-t3-app见 cli/src/consts.ts使用 TypeScript 还是 JavaScriptTypeScript / JavaScriptTypeScript选 JavaScript 会提示 Wrong answer, using TypeScript instead是否使用 Tailwind CSS 做样式是 / 否—是否使用 tRPC是 / 否—选择认证方案None / NextAuth.js / BetterAuthNone选择数据库 ORMNone / Prisma / DrizzleNone是否使用 Next.js App Router是 / 否是选择数据库提供者选了 ORM 才会问SQLite (LibSQL) / MySQL / PostgreSQL / PlanetScaleSQLite选择 lint/format 工具ESLint/Prettier / BiomeESLint/Prettier是否初始化 Git 仓库并暂存更改是 / 否是是否替你运行包管理器 install是 / 否是使用什么 import alias合法别名~/所有问题回答完成后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 与 BetterAuthCLI 会判定为不兼容组合并直接退出cli/src/cli/index.ts。命令行参数完整参考除了交互式引导CLI 还支持通过参数直接指定选项适合脚本化和非交互环境参数定义见 cli/src/cli/index.ts参数说明[dir]应用名称同时也是要创建的目录名支持 scoped 写法如dir/mono/app会被解析为包名mono/app与目录dir/app--noGit不初始化 Git 仓库--noInstall不自动执行包管理器的 install 命令-y, --default跳过所有交互使用全部默认选项默认组合为 nextAuth prisma tailwind trpc eslintSQLiteApp Router-v, --version显示版本号-i, --import-alias [alias]自定义 import alias默认~/--dbProvider [provider]指定数据库提供者可选mysql、postgres、sqlite、planetscale--appRouter [boolean]是否使用 Next.js App Router以下参数标注为experimental官方用途是 CI E2E 测试必须配合--CI使用以跳过提问参数说明--CI声明当前运行在 CI 环境配合下列 flag 跳过交互提示--tailwind [boolean]是否安装 Tailwind CSS--nextAuth [boolean]是否安装 NextAuth.js--betterAuth [boolean]是否安装 BetterAuth--prisma [boolean]是否安装 Prisma--drizzle [boolean]是否安装 Drizzle--trpc [boolean]是否安装 tRPC--eslint [boolean]是否安装 ESLint 与 Prettier--biome [boolean]是否安装 Biome例如在 CI 中要生成一个使用 App Router、SQLite、tRPC Tailwind 的默认项目可以运行npm create t3-applatest -- --CI --trpc --tailwind --appRouter --dbProvider sqlite此外有两个值得一提的行为Yarn 3 不兼容警告当检测到npm_config_user_agent以yarn/3开头时CLI 会打印警告提示 Yarn 3 当前不受支持、可能导致崩溃建议改用 pnpm、npm 或 Yarn Classiccli/src/cli/index.ts。非交互终端兜底如果在 MinTTY如 Git Bash等非交互环境运行交互提示会抛出IsTTYErrorCLI 会捕获异常并询问是否继续生成默认 T3 应用确认后自动用默认选项完成脚手架cli/src/cli/index.ts。命令执行背后从参数到项目的完整调用链create-t3-app的主流程定义在入口文件 cli/src/index.ts大致分为以下几个阶段启动准备渲染 ASCII 标题renderTitle检查 npm 版本并渲染版本警告如果当前环境 npm 过旧。收集选项调用runCli()得到应用名、包列表、flagsnoGit/noInstall/importAlias/appRouter与数据库提供者。解析项目名parseNameAndPath将dir/mono/app拆分为 scoped 包名与目标目录。创建项目createProject依次执行——scaffoldProject把 cli/template/base 目录整体复制到目标目录并把_gitignore重命名为.gitignore若目标目录已存在且非空会询问中止 / 清空目录 / 覆盖冲突文件cli/src/helpers/scaffoldProject.tsinstallPackages遍历用户选择的包逐个执行对应 installer如 prisma、trpc、tailwind 安装器写入依赖与样板代码cli/src/helpers/installPackages.tsselectBoilerplate根据 App Router / Pages Router 及已选包从 cli/template/extras/src 中挑选对应的layout/pageApp Router或_app/indexPages Router样板文件覆盖到项目cli/src/helpers/selectBoilerplate.ts若未选择 Tailwind则额外复制index.module.css作为替代样式方案。写回 package.json把解析出的包名写入项目package.json的name字段记录ct3aMetadata.initVersion并写入packageManager字段bun 除外因为 bun 暂不支持该字段。处理自定义 import alias若用户指定的 alias 不是默认的~/则遍历生成文件并批量替换setImportAlias。安装依赖installDependencies按包管理器分流——npm 直接继承 stderr 显示进度条pnpm/yarn 通过 ora spinner 展示进度bun 隐藏 stdoutcli/src/helpers/installDependencies.ts。若选了 Prisma还会额外执行npx prisma generate生成客户端随后运行 Prettier 格式化整个项目。初始化 Git若未传--noGit调用initializeGit——检测 git 是否安装、目标目录是否已在 git 仓库内并尊重init.defaultBranch配置默认main初始化仓库并git add .对 git 版本低于 2.28 的会降级使用git initsymbolic-refcli/src/helpers/git.ts。打印后续步骤根据项目情况输出cd、install、db:pushPrisma/Drizzle 项目、填写.envNextAuth 项目、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.3t3-oss/env-nextjs^0.12.0与zod^3.24.2用于类型安全的环境变量校验开发依赖typescript^5.8.2、types/node、types/react等脚本内置了devnext 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 commitnpm/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 12:44:23 · 阅读 1.2k create-t3-app 完全指南：用一条命令搭建全栈类型安全的 Next.js 应用
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-appcreate-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-applatestCLI 会在本地交互式地询问你的技术选型然后生成一个为你量身定制、各部分已经互相集成好的项目例如 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解决实际问题Solve Problems项目只添加能解决核心技术栈内具体问题的东西。它不会添加 zustand、redux 这类状态库但会帮你把 NextAuth.js、Prisma、tRPC 集成好。负责任地拥抱前沿Bleed Responsibly喜欢前沿技术但只在低风险部位使用。例如不会押注激进的新型数据库技术SQL 足够好但愿意押注 tRPC——因为它本质只是函数随时可以迁移走。类型安全不可妥协Typesafety Isnt Optional项目的目标是最快地启动一个全栈、类型安全的应用任何损害类型安全特性的决策都不应出现在这个项目里。这三点解释了为什么create-t3-app的默认技术栈以 TypeScript 为根基为什么 ORM 限定在 Prisma 与 Drizzle也解释了为什么它坚持克制而非堆砌。快速开始四种包管理器一条命令启动在任意空目录下运行以下任意一条命令并按提示回答即可命令对应源码文档 cli/README.md# npm npm create t3-applatest # yarn yarn create t3-app # pnpm pnpm create t3-applatest # bun bun create t3-applatestCLI 会自动检测你当前使用的包管理器通过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。下面是按顺序出现的全部问题及默认值提问可选值默认值项目名称What will your project be called?任意合法应用名my-t3-app见 cli/src/consts.ts使用 TypeScript 还是 JavaScriptTypeScript / JavaScriptTypeScript选 JavaScript 会提示 Wrong answer, using TypeScript instead是否使用 Tailwind CSS 做样式是 / 否—是否使用 tRPC是 / 否—选择认证方案None / NextAuth.js / BetterAuthNone选择数据库 ORMNone / Prisma / DrizzleNone是否使用 Next.js App Router是 / 否是选择数据库提供者选了 ORM 才会问SQLite (LibSQL) / MySQL / PostgreSQL / PlanetScaleSQLite选择 lint/format 工具ESLint/Prettier / BiomeESLint/Prettier是否初始化 Git 仓库并暂存更改是 / 否是是否替你运行包管理器 install是 / 否是使用什么 import alias合法别名~/所有问题回答完成后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 与 BetterAuthCLI 会判定为不兼容组合并直接退出cli/src/cli/index.ts。命令行参数完整参考除了交互式引导CLI 还支持通过参数直接指定选项适合脚本化和非交互环境参数定义见 cli/src/cli/index.ts参数说明[dir]应用名称同时也是要创建的目录名支持 scoped 写法如dir/mono/app会被解析为包名mono/app与目录dir/app--noGit不初始化 Git 仓库--noInstall不自动执行包管理器的 install 命令-y, --default跳过所有交互使用全部默认选项默认组合为 nextAuth prisma tailwind trpc eslintSQLiteApp Router-v, --version显示版本号-i, --import-alias [alias]自定义 import alias默认~/--dbProvider [provider]指定数据库提供者可选mysql、postgres、sqlite、planetscale--appRouter [boolean]是否使用 Next.js App Router以下参数标注为experimental官方用途是 CI E2E 测试必须配合--CI使用以跳过提问参数说明--CI声明当前运行在 CI 环境配合下列 flag 跳过交互提示--tailwind [boolean]是否安装 Tailwind CSS--nextAuth [boolean]是否安装 NextAuth.js--betterAuth [boolean]是否安装 BetterAuth--prisma [boolean]是否安装 Prisma--drizzle [boolean]是否安装 Drizzle--trpc [boolean]是否安装 tRPC--eslint [boolean]是否安装 ESLint 与 Prettier--biome [boolean]是否安装 Biome例如在 CI 中要生成一个使用 App Router、SQLite、tRPC Tailwind 的默认项目可以运行npm create t3-applatest -- --CI --trpc --tailwind --appRouter --dbProvider sqlite此外有两个值得一提的行为Yarn 3 不兼容警告当检测到npm_config_user_agent以yarn/3开头时CLI 会打印警告提示 Yarn 3 当前不受支持、可能导致崩溃建议改用 pnpm、npm 或 Yarn Classiccli/src/cli/index.ts。非交互终端兜底如果在 MinTTY如 Git Bash等非交互环境运行交互提示会抛出IsTTYErrorCLI 会捕获异常并询问是否继续生成默认 T3 应用确认后自动用默认选项完成脚手架cli/src/cli/index.ts。命令执行背后从参数到项目的完整调用链create-t3-app的主流程定义在入口文件 cli/src/index.ts大致分为以下几个阶段启动准备渲染 ASCII 标题renderTitle检查 npm 版本并渲染版本警告如果当前环境 npm 过旧。收集选项调用runCli()得到应用名、包列表、flagsnoGit/noInstall/importAlias/appRouter与数据库提供者。解析项目名parseNameAndPath将dir/mono/app拆分为 scoped 包名与目标目录。创建项目createProject依次执行——scaffoldProject把 cli/template/base 目录整体复制到目标目录并把_gitignore重命名为.gitignore若目标目录已存在且非空会询问中止 / 清空目录 / 覆盖冲突文件cli/src/helpers/scaffoldProject.tsinstallPackages遍历用户选择的包逐个执行对应 installer如 prisma、trpc、tailwind 安装器写入依赖与样板代码cli/src/helpers/installPackages.tsselectBoilerplate根据 App Router / Pages Router 及已选包从 cli/template/extras/src 中挑选对应的layout/pageApp Router或_app/indexPages Router样板文件覆盖到项目cli/src/helpers/selectBoilerplate.ts若未选择 Tailwind则额外复制index.module.css作为替代样式方案。写回 package.json把解析出的包名写入项目package.json的name字段记录ct3aMetadata.initVersion并写入packageManager字段bun 除外因为 bun 暂不支持该字段。处理自定义 import alias若用户指定的 alias 不是默认的~/则遍历生成文件并批量替换setImportAlias。安装依赖installDependencies按包管理器分流——npm 直接继承 stderr 显示进度条pnpm/yarn 通过 ora spinner 展示进度bun 隐藏 stdoutcli/src/helpers/installDependencies.ts。若选了 Prisma还会额外执行npx prisma generate生成客户端随后运行 Prettier 格式化整个项目。初始化 Git若未传--noGit调用initializeGit——检测 git 是否安装、目标目录是否已在 git 仓库内并尊重init.defaultBranch配置默认main初始化仓库并git add .对 git 版本低于 2.28 的会降级使用git initsymbolic-refcli/src/helpers/git.ts。打印后续步骤根据项目情况输出cd、install、db:pushPrisma/Drizzle 项目、填写.envNextAuth 项目、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.3t3-oss/env-nextjs^0.12.0与zod^3.24.2用于类型安全的环境变量校验开发依赖typescript^5.8.2、types/node、types/react等脚本内置了devnext 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 commitnpm/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考