create-t3-app 常见问题全解析从脚手架使用到 App Router、类型安全与 .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 官方 FAQ阿拉伯语版www/src/pages/ar/faq.md为骨架逐一拆解开发者最常提出的五个问题创建项目后如何继续开发、如何选择学习资源、项目中为何存在.js文件、为何默认不内置 i18n以及应该选用 App Router 还是 Pages Router。在回答这些问题时我们将深入对应源码与模板配置如 cli/src/cli/index.ts、cli/template/base/tsconfig.json、cli/src/helpers/selectBoilerplate.ts让读者既得到可直接落地的操作指引也理解每个设计决策背后的工程原理。创建应用之后下一步该做什么这是 FAQ 中被问得最多的问题答案的核心是create-t3-app 是一个脚手架工具而不是一个框架。它在创建完项目后并不会常驻后台、替你管理升级因此项目一经生成就完全属于你英文版 FAQ 对此有专门说明见 www/src/pages/en/faq.mdx。项目团队刻意将脚手架保持尽可能简单CLI 只为你铺好地基scaffolding后续需要什么再按需添加。这一理念与 T3 Stack 的模块化定位一脉相承——从 cli/src/cli/index.ts 中的defaultOptions可以看到默认组合是nextAuth prisma tailwind trpc eslint每个成员都可以在交互式提示中单独取消或替换。如果你对某个技术栈成员还不熟悉官方建议先查阅对应组件的文档再去社区求助。FAQ 中列出的核心组件包括Next.js全栈 React 框架构成应用的主干NextAuth.js / BetterAuth认证方案仓库同时维护了两种认证的安装器见 cli/src/installers/nextAuth.ts 与 cli/src/installers/betterAuth.tsPrisma / DrizzleORM 二选一二者被设计为互斥组合CLI 在 CI 模式下会显式校验并拒绝Prisma Drizzle同时存在见 cli/src/cli/index.tsTailwind CSS样式方案tRPC端到端类型安全的 API 层。一个值得注意的细节是这个仓库本身也是模块化理念的活教材——cli/template/extras 目录下存放了大量按功能拆分的模板片段CLI 会根据用户勾选的组合动态拼装最终项目。有哪些现成的学习资源FAQ 给出的建议非常直白与其先系统学习整套技术栈不如直接动手用 Stack 构建一个真实项目在实战中学习。社区以及 T3 Stack 作者 Theo都认可构建驱动学习是最快的路径——如果你已经在用 T3 Stack 的某些成员那么最适合的方式就是先用起来边做边补。当然FAQ 也承认这条路径并不适合所有人。如果你尝试后仍需要系统性的教程官方 FAQ 整理了多篇社区文章与视频教程覆盖使用 Create T3 App 构建全栈应用迁移到 TurborepoT3 Stack 概览等主题详见 www/src/pages/ar/faq.md 原文。这些资源的共同背景是 T3 Stack 以Next.js TypeScript为核心Tailwind CSS几乎总是被包含在内而一旦涉及后端能力tRPC、Prisma、NextAuth.js就是锦上添花的补充——这套组合的描述可以在官方介绍文档 www/src/pages/en/introduction.mdx 中找到。需要提醒的是社区教程的时效性参差不齐英文版 FAQ 也标注了部分可能过时使用时请对照当前仓库的模板版本当前模板使用 Next.js 15、React 19见 cli/template/base/package.json酌情采纳。为什么项目里会有.js文件这是最容易被新手误解的问题。表面上一个类型安全优先的项目里出现 JavaScript 文件显得自相矛盾但 FAQ 给出了明确的解释依据 T3 公理第三条类型安全不是可选项Typesafety Isnt Optional见 www/src/pages/en/introduction.mdx类型安全是 T3 项目的一等公民。然而并非所有框架和插件都原生支持 TypeScript因此部分配置文件不得不写成.js。换句话说.js文件的存在是外部生态限制的妥协而不是项目自身的退让。为了把这种被迫使用 JavaScript的语义表达清楚项目采取了两条配套措施显式声明模块类型按所依赖库的支持情况明确使用.cjsCommonJS或.mjs/.jsESM扩展名。例如 cli/template/base/next.config.js 使用 ESM 语法 typeJSDoc 注释标注配置类型Prettier 配置同样通过 JSDoc 声明类型见 cli/template/extras/config/_prettier.config.js。强制类型检查兜底虽然这些文件是 JavaScript但它们在编译阶段仍然会被 TypeScript 检查。关键在于 cli/template/base/tsconfig.json 同时开启了allowJs: true与checkJs: true且include数组覆盖了**/*.cjs、**/*.js——这意味着 JS 配置文件的类型错误同样会在pnpm typecheck即tsc --noEmit见 cli/template/base/package.json时被拦截。所以项目中.js配置文件的真实工作方式是语法上是 JavaScript类型上仍受 TypeScript 编译器保护配合typeJSDoc 注释开发体验与纯 TS 文件几乎一致。想加 i18n有没有现成参考FAQ 明确表示create-t3-app 默认不内置 i18n原因是国际化是一个高度观点化的主题实现方式五花八门强行捆绑只会破坏脚手架的中立性。这与 T3 公理第一条解决问题Solve Problems完全一致——只添加那些能解决核心技术栈内特定问题的东西而 i18n 显然更适合留给用户按需选择参见 www/src/pages/en/introduction.mdx 对不添加一切原则的阐述。不过FAQ 为确有需求的用户保留了一条退路官方维护了一个参考仓库演示如何用next-i18next为 T3 应用接入国际化。仓库本身也是一个绝佳的观察样本——本项目文档目录 www/src/pages 下维护了ar、en、es、fr、ja、no、pl、pt、ru、uk、zh-hans等多达十一种语言的版本并且通过 frontmatter 中的lang与dir: rtl阿拉伯语从右向左排版字段处理本地化元信息见 www/src/pages/ar/faq.md。你可以把这种多语言文档目录 语言元数据的组织方式当作 i18n 落地的现实参照。到底该用/appApp Router还是/pagesPages Router曾经的纠结与现在的答案阿拉伯语版 FAQ 成文时Next.js 13 的 App Router 还处于尝鲜阶段它被形容为未来的惊鸿一瞥API 仍在 beta 且预期会有破坏性变更因此官方当时推荐成熟的 Pages Router。这背后是 T3 公理第二条负责任地尝鲜Bleed Responsibly——热爱前沿技术但只在风险可控的地方使用见 www/src/pages/en/introduction.mdx。时过境迁英文版 FAQwww/src/pages/en/faq.mdx已经更新了这一结论App Router 现在被 T3 社区认为成熟到可以用于生产环境。结合当前仓库的 CLI 源码可以验证这一态度转变在交互式提示中CLI 询问 Would you like to use Next.js App Router? 时initialValue默认为true见 cli/src/cli/index.ts即默认推荐 App Router模板目录同时完整保留了两种路由范式的文件集[cli/template/extras/src/app](https://link.gitcode.com/i/2fdb05cd6955826a8b1e4812aeb76234)App Router 的layout/page与[cli/template/extras/src/pages](https://link.gitcode.com/i/e1c3fcc844121a445ea3c1266ac1df58)Pages Router 的_app/index。两种路由是如何被组装出来的即便你选择了 Pages Router也完全不必担心迁移压力。脚手架的分发逻辑位于 cli/src/helpers/selectBoilerplate.ts核心做法是按已选包的组合从模板库中挑选对应文件再复制到项目。以 App Router 的布局文件为例selectLayoutFile会依据tailwind与trpc是否启用从with-trpc-tw.tsx、with-trpc.tsx、with-tw.tsx、base.tsx中选出最匹配的layout.tsx模板见 selectBoilerplate.ts_app.tsx、首页、page.tsx同理分别对应selectAppFile、selectIndexFile、selectPageFile。这解释了为什么模板目录里会出现大量with-*-tw.tsx之类的排列组合文件——它们是模块化思想的直接产物。如何确认自己的选择在脚手架阶段两种路由互斥存在CLI 的交互确认框会决定最终项目采用哪套目录结构在 CI 场景下则通过--appRouter [boolean]参数显式指定见 cli/src/cli/index.ts。生产环境使用哪个范式本质上取决于你的团队对稳定性的诉求——FAQ 的最终建议是除非有强理由迁移否则不必背负不必要的重构压力选择哪个就在哪个范式下深耕。小结把 FAQ 当成使用哲学说明书纵览整份 FAQ你会发现它回答的不仅是怎么做更是为什么这么做常见问题结论要点仓库证据创建后如何继续脚手架非框架模块化按需添加cli/src/cli/index.ts 默认选项组合怎么学习先构建、后补课教程为辅FAQ 资源清单 introduction.mdx为何有.js文件生态限制使然checkJs兜底类型安全tsconfig.jsoni18n 有参考吗默认不内置按需自行接入仓库 11 语言文档目录App 还是 Pages Router已默认推荐 App RouterPages 仍可用cli/src/cli/index.ts selectBoilerplate.tsFAQ 中反复出现的简单simplicity模块化modularity全栈类型安全full-stack typesafety三个关键词正是 T3 Stack 的立身之本。读懂 FAQ本质上就是读懂这套脚手架的设计取舍——而这往往比记住某条具体命令更能帮你用好它。【免费下载链接】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），仅供参考 create-t3-app 常见问题全解析：从脚手架使用到 App Router、类型安全与 .js 配置文件实践
create-t3-app 常见问题全解析从脚手架使用到 App Router、类型安全与 .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 官方 FAQ阿拉伯语版www/src/pages/ar/faq.md为骨架逐一拆解开发者最常提出的五个问题创建项目后如何继续开发、如何选择学习资源、项目中为何存在.js文件、为何默认不内置 i18n以及应该选用 App Router 还是 Pages Router。在回答这些问题时我们将深入对应源码与模板配置如 cli/src/cli/index.ts、cli/template/base/tsconfig.json、cli/src/helpers/selectBoilerplate.ts让读者既得到可直接落地的操作指引也理解每个设计决策背后的工程原理。创建应用之后下一步该做什么这是 FAQ 中被问得最多的问题答案的核心是create-t3-app 是一个脚手架工具而不是一个框架。它在创建完项目后并不会常驻后台、替你管理升级因此项目一经生成就完全属于你英文版 FAQ 对此有专门说明见 www/src/pages/en/faq.mdx。项目团队刻意将脚手架保持尽可能简单CLI 只为你铺好地基scaffolding后续需要什么再按需添加。这一理念与 T3 Stack 的模块化定位一脉相承——从 cli/src/cli/index.ts 中的defaultOptions可以看到默认组合是nextAuth prisma tailwind trpc eslint每个成员都可以在交互式提示中单独取消或替换。如果你对某个技术栈成员还不熟悉官方建议先查阅对应组件的文档再去社区求助。FAQ 中列出的核心组件包括Next.js全栈 React 框架构成应用的主干NextAuth.js / BetterAuth认证方案仓库同时维护了两种认证的安装器见 cli/src/installers/nextAuth.ts 与 cli/src/installers/betterAuth.tsPrisma / DrizzleORM 二选一二者被设计为互斥组合CLI 在 CI 模式下会显式校验并拒绝Prisma Drizzle同时存在见 cli/src/cli/index.tsTailwind CSS样式方案tRPC端到端类型安全的 API 层。一个值得注意的细节是这个仓库本身也是模块化理念的活教材——cli/template/extras 目录下存放了大量按功能拆分的模板片段CLI 会根据用户勾选的组合动态拼装最终项目。有哪些现成的学习资源FAQ 给出的建议非常直白与其先系统学习整套技术栈不如直接动手用 Stack 构建一个真实项目在实战中学习。社区以及 T3 Stack 作者 Theo都认可构建驱动学习是最快的路径——如果你已经在用 T3 Stack 的某些成员那么最适合的方式就是先用起来边做边补。当然FAQ 也承认这条路径并不适合所有人。如果你尝试后仍需要系统性的教程官方 FAQ 整理了多篇社区文章与视频教程覆盖使用 Create T3 App 构建全栈应用迁移到 TurborepoT3 Stack 概览等主题详见 www/src/pages/ar/faq.md 原文。这些资源的共同背景是 T3 Stack 以Next.js TypeScript为核心Tailwind CSS几乎总是被包含在内而一旦涉及后端能力tRPC、Prisma、NextAuth.js就是锦上添花的补充——这套组合的描述可以在官方介绍文档 www/src/pages/en/introduction.mdx 中找到。需要提醒的是社区教程的时效性参差不齐英文版 FAQ 也标注了部分可能过时使用时请对照当前仓库的模板版本当前模板使用 Next.js 15、React 19见 cli/template/base/package.json酌情采纳。为什么项目里会有.js文件这是最容易被新手误解的问题。表面上一个类型安全优先的项目里出现 JavaScript 文件显得自相矛盾但 FAQ 给出了明确的解释依据 T3 公理第三条类型安全不是可选项Typesafety Isnt Optional见 www/src/pages/en/introduction.mdx类型安全是 T3 项目的一等公民。然而并非所有框架和插件都原生支持 TypeScript因此部分配置文件不得不写成.js。换句话说.js文件的存在是外部生态限制的妥协而不是项目自身的退让。为了把这种被迫使用 JavaScript的语义表达清楚项目采取了两条配套措施显式声明模块类型按所依赖库的支持情况明确使用.cjsCommonJS或.mjs/.jsESM扩展名。例如 cli/template/base/next.config.js 使用 ESM 语法 typeJSDoc 注释标注配置类型Prettier 配置同样通过 JSDoc 声明类型见 cli/template/extras/config/_prettier.config.js。强制类型检查兜底虽然这些文件是 JavaScript但它们在编译阶段仍然会被 TypeScript 检查。关键在于 cli/template/base/tsconfig.json 同时开启了allowJs: true与checkJs: true且include数组覆盖了**/*.cjs、**/*.js——这意味着 JS 配置文件的类型错误同样会在pnpm typecheck即tsc --noEmit见 cli/template/base/package.json时被拦截。所以项目中.js配置文件的真实工作方式是语法上是 JavaScript类型上仍受 TypeScript 编译器保护配合typeJSDoc 注释开发体验与纯 TS 文件几乎一致。想加 i18n有没有现成参考FAQ 明确表示create-t3-app 默认不内置 i18n原因是国际化是一个高度观点化的主题实现方式五花八门强行捆绑只会破坏脚手架的中立性。这与 T3 公理第一条解决问题Solve Problems完全一致——只添加那些能解决核心技术栈内特定问题的东西而 i18n 显然更适合留给用户按需选择参见 www/src/pages/en/introduction.mdx 对不添加一切原则的阐述。不过FAQ 为确有需求的用户保留了一条退路官方维护了一个参考仓库演示如何用next-i18next为 T3 应用接入国际化。仓库本身也是一个绝佳的观察样本——本项目文档目录 www/src/pages 下维护了ar、en、es、fr、ja、no、pl、pt、ru、uk、zh-hans等多达十一种语言的版本并且通过 frontmatter 中的lang与dir: rtl阿拉伯语从右向左排版字段处理本地化元信息见 www/src/pages/ar/faq.md。你可以把这种多语言文档目录 语言元数据的组织方式当作 i18n 落地的现实参照。到底该用/appApp Router还是/pagesPages Router曾经的纠结与现在的答案阿拉伯语版 FAQ 成文时Next.js 13 的 App Router 还处于尝鲜阶段它被形容为未来的惊鸿一瞥API 仍在 beta 且预期会有破坏性变更因此官方当时推荐成熟的 Pages Router。这背后是 T3 公理第二条负责任地尝鲜Bleed Responsibly——热爱前沿技术但只在风险可控的地方使用见 www/src/pages/en/introduction.mdx。时过境迁英文版 FAQwww/src/pages/en/faq.mdx已经更新了这一结论App Router 现在被 T3 社区认为成熟到可以用于生产环境。结合当前仓库的 CLI 源码可以验证这一态度转变在交互式提示中CLI 询问 Would you like to use Next.js App Router? 时initialValue默认为true见 cli/src/cli/index.ts即默认推荐 App Router模板目录同时完整保留了两种路由范式的文件集[cli/template/extras/src/app](https://link.gitcode.com/i/2fdb05cd6955826a8b1e4812aeb76234)App Router 的layout/page与[cli/template/extras/src/pages](https://link.gitcode.com/i/e1c3fcc844121a445ea3c1266ac1df58)Pages Router 的_app/index。两种路由是如何被组装出来的即便你选择了 Pages Router也完全不必担心迁移压力。脚手架的分发逻辑位于 cli/src/helpers/selectBoilerplate.ts核心做法是按已选包的组合从模板库中挑选对应文件再复制到项目。以 App Router 的布局文件为例selectLayoutFile会依据tailwind与trpc是否启用从with-trpc-tw.tsx、with-trpc.tsx、with-tw.tsx、base.tsx中选出最匹配的layout.tsx模板见 selectBoilerplate.ts_app.tsx、首页、page.tsx同理分别对应selectAppFile、selectIndexFile、selectPageFile。这解释了为什么模板目录里会出现大量with-*-tw.tsx之类的排列组合文件——它们是模块化思想的直接产物。如何确认自己的选择在脚手架阶段两种路由互斥存在CLI 的交互确认框会决定最终项目采用哪套目录结构在 CI 场景下则通过--appRouter [boolean]参数显式指定见 cli/src/cli/index.ts。生产环境使用哪个范式本质上取决于你的团队对稳定性的诉求——FAQ 的最终建议是除非有强理由迁移否则不必背负不必要的重构压力选择哪个就在哪个范式下深耕。小结把 FAQ 当成使用哲学说明书纵览整份 FAQ你会发现它回答的不仅是怎么做更是为什么这么做常见问题结论要点仓库证据创建后如何继续脚手架非框架模块化按需添加cli/src/cli/index.ts 默认选项组合怎么学习先构建、后补课教程为辅FAQ 资源清单 introduction.mdx为何有.js文件生态限制使然checkJs兜底类型安全tsconfig.jsoni18n 有参考吗默认不内置按需自行接入仓库 11 语言文档目录App 还是 Pages Router已默认推荐 App RouterPages 仍可用cli/src/cli/index.ts selectBoilerplate.tsFAQ 中反复出现的简单simplicity模块化modularity全栈类型安全full-stack typesafety三个关键词正是 T3 Stack 的立身之本。读懂 FAQ本质上就是读懂这套脚手架的设计取舍——而这往往比记住某条具体命令更能帮你用好它。【免费下载链接】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），仅供参考