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.ts）；
• Prisma / Drizzle：ORM 二选一，二者被设计为互斥组合（CLI 在 CI 模式下会显式校验并拒绝Prisma + Drizzle同时存在，见 cli/src/cli/index.ts）；
• Tailwind CSS：样式方案；
• tRPC：端到端类型安全的 API 层。

一个值得注意的细节是：这个仓库本身也是"模块化"理念的活教材——cli/template/extras 目录下存放了大量按功能拆分的模板片段，CLI 会根据用户勾选的组合动态拼装最终项目。

有哪些现成的学习资源？

FAQ 给出的建议非常直白：与其先系统学习整套技术栈，不如直接动手用 Stack 构建一个真实项目，在实战中学习。社区（以及 T3 Stack 作者 Theo）都认可"构建驱动学习"是最快的路径——如果你已经在用 T3 Stack 的某些成员，那么最适合的方式就是"先用起来，边做边补"。

当然，FAQ 也承认这条路径并不适合所有人。如果你尝试后仍需要系统性的教程，官方 FAQ 整理了多篇社区文章与视频教程（覆盖"使用 Create T3 App 构建全栈应用""迁移到 Turborepo""T3 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 Isn't Optional）"（见 www/src/pages/en/introduction.mdx），类型安全是 T3 项目的"一等公民"。然而并非所有框架和插件都原生支持 TypeScript，因此部分配置文件不得不写成.js。

换句话说，.js文件的存在是外部生态限制的妥协，而不是项目自身的退让。为了把这种"被迫使用 JavaScript"的语义表达清楚，项目采取了两条配套措施：

1. 显式声明模块类型：按所依赖库的支持情况，明确使用.cjs（CommonJS）或.mjs/.js（ESM）扩展名。例如 cli/template/base/next.config.js 使用 ESM 语法 +@typeJSDoc 注释标注配置类型；Prettier 配置同样通过 JSDoc 声明类型（见 cli/template/extras/config/_prettier.config.js）。

2. 强制类型检查兜底：虽然这些文件是 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 落地的现实参照。

到底该用/app（App Router）还是/pages（Pages Router）？

曾经的纠结与现在的答案

阿拉伯语版 FAQ 成文时，Next.js 13 的 App Router 还处于"尝鲜"阶段：它被形容为"未来的惊鸿一瞥"，API 仍在 beta 且预期会有破坏性变更，因此官方当时推荐成熟的 Pages Router。这背后是 T3 公理第二条"负责任地尝鲜（Bleed Responsibly）"——热爱前沿技术，但只在风险可控的地方使用（见 www/src/pages/en/introduction.mdx）。

时过境迁，英文版 FAQ（www/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，你会发现它回答的不仅是"怎么做"，更是"为什么这么做"：

FAQ 中反复出现的"简单（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