create-t3-app 中的 Next.js理解React 后端框架定位与全栈数据获取实践【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app本篇技术指南围绕 www/src/pages/no/usage/next-js.md挪威语版 Next.js 使用指南展开系统讲解 Next.js 在 create-t3-app 技术栈中的React 后端框架定位、数据获取getServerSideProps、静态生成与 ISR的取舍并结合本仓库模板源码如 cli/template/base/next.config.js、cli/template/extras/src/trpc/server.ts给出可直接运行的配置与实现证据。读完后你将掌握 create-t3-app 生成的 Next.js 项目结构、服务端数据获取的正确姿势以及类型安全运行时环境校验的落地方法。Next.js 在 T3 技术栈中的定位React 应用的后端框架原文档开篇即给出一个常被忽略的定位Next.js 是为你的 React 应用提供后端能力的框架Next.js er et backend-rammeverk for dine React-applikasjoner。也就是说当你选择 React 时Next.js 并不是又一个 UI 库而是把服务端渲染、路由、API、构建优化等后端能力以框架的形式打包进来让纯前端 React 组件获得完整的全栈执行环境。这一判断在本仓库模板中得到充分印证。create-t3-app 生成的脚手架基于 Next.js 15 与 React 19 构建见 cli/template/base/package.json 的dependenciesnext: ^15.5.9、react: ^19.2.3、react-dom: ^19.2.3并且模板根目录同时包含next.config.js、tsconfig.json与next-env.d.ts等 Next.js 专属文件说明 Next.js 是整套脚手架的运行时底座而非可选插件。为什么要用 Next.js轻度主张、重度优化的框架哲学原文档用一句非常精准的话概括了 Next.js 的设计哲学lightly opinionated, heavily optimized轻度主张、重度优化。背后的动机是团队热爱 React它让 UI 开发变得前所未有的简单但同时 React 本身只解决视图问题路由、数据获取、图片优化、代码分割等都需要开发者自行决策容易把开发者引向困难的道路原文档原文It also can lead developers down some rough paths。Next.js 对如何构建 React 应用给出了一套有主见的默认方案从路由routing、API 定义到图片渲染image rendering都内置了经过优化的实现引导开发者走向良好决策。从模板源码看重度优化并非空话开发体验优化模板的package.json脚本使用next dev --turbo启动开发服务器即 Turbo 打包模式同时提供build、start、preview构建后启动、typechecktsc --noEmit等完整脚本见 cli/template/base/package.json 的scripts。严格模式与国际化默认配置开启reactStrictMode: true并在注释中提示如果使用 App Router 的appDir必须注释掉下方i18n配置见 cli/template/base/next.config.js这是 Next.js 新旧路由模式下容易踩坑的兼容性要点。开箱即用的类型安全模板 cli/template/base/tsconfig.json 开启了strict、noUncheckedIndexedAccess、verbatimModuleSyntax等严格编译选项并预置了~/*→./src/*的路径别名paths配置后续所有源码引用如~/server/api/root、~/trpc/react都依赖这一别名。此外原文档特别提到 Next.js 与 Vercel 的组合能让开发与部署变得前所未有的简单免费的额度与直观的界面让站点可以几次点击即可发布。这一点在仓库文档 www/src/pages/no/deployment/vercel.md以及多语言版本中有详细的分步部署说明属于可选的部署增强方案。App Router 与 Pages Router模板的两种应用形态create-t3-app 同时提供 App Router 与 Pages Router 两套模板二者在cli/template/extras/src/下分别以app/与pages/目录组织App Router布局组件位于 cli/template/extras/src/app/layout/base.tsx、with-trpc.tsx、with-tw.tsx、with-trpc-tw.tsx页面组件位于 cli/template/extras/src/app/page/。以 cli/template/extras/src/app/layout/with-trpc.tsx 为例根布局通过next/font/google的Geist字体、metadata导出与TRPCReactProvider包裹实现全局样式与 tRPC 状态注入。Pages Router_app与页面组件分别位于 cli/template/extras/src/pages/_app/ 与 cli/template/extras/src/pages/index/。两种形态的选择直接决定了数据获取 API 的使用方式详见下一节这也是原文档后续讨论Get Static/Server Props的背景。仓库文档 www/src/pages/no/folder-structure-pages.mdx 对 Pages Router 目录结构有专门讲解App Router 版本对应 www/src/pages/en/folder-structure-app.mdx。数据获取Get Static / Server Props 与增量静态再生ISR数据获取是 Next.js 的核心特性也是原文档重点提醒开发者仔细研读的部分。核心结论如下getServerSideProps阻塞调用谨慎使用getServerSideProps服务端渲染时的数据获取在每次请求时于服务端执行它是一个阻塞调用blocking call会让页面变慢因此原文档强烈建议除非有充分的理由否则一般不要使用它getServerSidePropsis generally discouraged unless there is a good reason for it。ISR动态数据的更优替代当数据是动态的、但可以增量获取时增量静态再生Incremental Static RegenerationISR 是getServerSideProps的出色替代方案——它既保留了静态生成的性能优势又能按需通过revalidate时间或按需触发重新生成页面兼顾动态性与吞吐量。原文档明确建议阅读官方数据获取文档以理解各方法间的差异。面向新架构App Router 下的服务端数据获取需要说明的是原文档写作时主要面向 Pages Router 的getServerSideProps/getStaticProps范式。而在 create-t3-app 当前的 App Router 模板中数据获取的核心场景已由React Server ComponentsRSC与 tRPC 的 hydration 机制承载。模板在 cli/template/extras/src/trpc/server.ts 中实现了这一能力import server-only; import { createHydrationHelpers } from trpc/react-query/rsc; import { headers } from next/headers; import { cache } from react; import { createCaller, type AppRouter } from ~/server/api/root; import { createTRPCContext } from ~/server/api/trpc; import { createQueryClient } from ./query-client; // 在 RSC 中包装 createTRPCContext为服务端 tRPC 调用提供请求上下文 const createContext cache(async () { const heads new Headers(await headers()); heads.set(x-trpc-source, rsc); return createTRPCContext({ headers: heads }); }); const getQueryClient cache(createQueryClient); const caller createCaller(createContext); export const { trpc: api, HydrateClient } createHydrationHelpersAppRouter( caller, getQueryClient );这段代码展示了与静态生成/服务端渲染一脉相承的新思路在服务端RSC直接调用 tRPC 路由获取数据再通过HydrateClient把数据水合到客户端避免客户端二次请求瀑布waterfall。配合 cli/template/extras/src/server/api/trpc-app/base.ts 中initTRPC.context...().create({ transformer: superjson })建立的上下文与 superjson 序列化整个链路保持端到端类型安全。运行时环境校验t3-oss/env-nextjs 与 SKIP_ENV_VALIDATIONcreate-t3-app 的 Next.js 模板把类型安全延伸到环境变量层。模板根目录 cli/template/base/src/env.js 使用t3-oss/env-nextjs与 zod 定义 schemaserver.NODE_ENV限定为development | test | production枚举确保应用不会被无效环境变量构建客户端变量必须以NEXT_PUBLIC_前缀暴露client块中预置了NEXT_PUBLIC_CLIENTVAR的注释示例由于 Next.js 的 Edge runtime 与客户端不能直接解构process.env需要通过runtimeEnv手动映射skipValidation: !!process.env.SKIP_ENV_VALIDATION允许在build/dev时跳过校验——这一点对Docker 构建尤为实用cli/template/base/next.config.js 顶部注释也重复强调Run build or dev with SKIP_ENV_VALIDATION to skip env validationemptyStringAsUndefined: true让空字符串按undefined处理避免z.string()校验被空串绕过。tRPC 与 Next.js 的桥接Route Handler 与 API 入口当在客户端组件中发起请求时请求会进入 Next.js 的Route Handler。模板在 cli/template/extras/src/app/api/trpc/[trpc]/route.ts 中通过trpc/server/adapters/fetch的fetchRequestHandler暴露GET/POST两个处理器const handler (req: NextRequest) fetchRequestHandler({ endpoint: /api/trpc, req, router: appRouter, createContext: () createContext(req), onError: env.NODE_ENV development ? ({ path, error }) { console.error( ❌ tRPC failed on ${path ?? no-path}: ${error.message} ); } : undefined, }); export { handler as GET, handler as POST };可见环境变量校验env.NODE_ENV与 tRPC 错误日志策略在真实请求链路中联动而 Pages Router 版本则对应 cli/template/extras/src/pages/api/trpc/[trpc].ts。两套入口共用 cli/template/extras/src/server/api/root.ts 定义的appRouter从源码结构可以推断模板刻意把路由定义与HTTP 适配层解耦便于在不同路由模式下复用。常用资源官方渠道一览原文档末尾提供了一份 Next.js 官方资源清单。由于本仓库为镜像仓库以下仅列出资源名称与用途读者可自行在官方渠道搜索资源说明Next.js Dokumentasjon官方文档数据获取、路由、图片优化等全部 API 的权威参考Next.js GitHub源码与 issue 跟踪可查看版本发布与 RFCNext.js Blogg官方博客新版本特性、最佳实践与生态动态Next.js Discord社区实时交流与官方支持Next.js Twitter版本发布与官方公告的快速渠道Vercel/Next.js YouTube-kanalYouTube 频道官方教程与会议演讲如 Theo 在 Next.js Conf 上关于Next.js 是后端框架的演讲此外本仓库内还有与上述主题强相关的本地文档可作补充阅读www/src/pages/no/usage/trpc.mdtRPC 在 Next.js 中的集成、www/src/pages/no/usage/typescript.md类型安全实践以及 www/src/pages/no/usage/next-auth.md鉴权与 API 路由的结合。小结回归原文档的立意Next.js 之于 create-t3-app是那个把 React 引向好决策的框架层——它提供轻度主张、重度优化的路由、API 与渲染能力配合 Vercel 实现一键部署在数据获取上getServerSideProps因阻塞特性应被谨慎使用动态数据优先考虑 ISR而在模板当前实现中App Router 下的 RSC tRPC hydration 已成为服务端数据获取的主流路径并与t3-oss/env-nextjs的类型安全环境校验、Route Handler 的 tRPC 桥接共同构成一套可复制的全栈实践。理解这一层定位是高效使用 create-t3-app 一切能力的前提。【免费下载链接】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 中的 Next.js：理解“React 后端框架“定位与全栈数据获取实践
create-t3-app 中的 Next.js理解React 后端框架定位与全栈数据获取实践【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app本篇技术指南围绕 www/src/pages/no/usage/next-js.md挪威语版 Next.js 使用指南展开系统讲解 Next.js 在 create-t3-app 技术栈中的React 后端框架定位、数据获取getServerSideProps、静态生成与 ISR的取舍并结合本仓库模板源码如 cli/template/base/next.config.js、cli/template/extras/src/trpc/server.ts给出可直接运行的配置与实现证据。读完后你将掌握 create-t3-app 生成的 Next.js 项目结构、服务端数据获取的正确姿势以及类型安全运行时环境校验的落地方法。Next.js 在 T3 技术栈中的定位React 应用的后端框架原文档开篇即给出一个常被忽略的定位Next.js 是为你的 React 应用提供后端能力的框架Next.js er et backend-rammeverk for dine React-applikasjoner。也就是说当你选择 React 时Next.js 并不是又一个 UI 库而是把服务端渲染、路由、API、构建优化等后端能力以框架的形式打包进来让纯前端 React 组件获得完整的全栈执行环境。这一判断在本仓库模板中得到充分印证。create-t3-app 生成的脚手架基于 Next.js 15 与 React 19 构建见 cli/template/base/package.json 的dependenciesnext: ^15.5.9、react: ^19.2.3、react-dom: ^19.2.3并且模板根目录同时包含next.config.js、tsconfig.json与next-env.d.ts等 Next.js 专属文件说明 Next.js 是整套脚手架的运行时底座而非可选插件。为什么要用 Next.js轻度主张、重度优化的框架哲学原文档用一句非常精准的话概括了 Next.js 的设计哲学lightly opinionated, heavily optimized轻度主张、重度优化。背后的动机是团队热爱 React它让 UI 开发变得前所未有的简单但同时 React 本身只解决视图问题路由、数据获取、图片优化、代码分割等都需要开发者自行决策容易把开发者引向困难的道路原文档原文It also can lead developers down some rough paths。Next.js 对如何构建 React 应用给出了一套有主见的默认方案从路由routing、API 定义到图片渲染image rendering都内置了经过优化的实现引导开发者走向良好决策。从模板源码看重度优化并非空话开发体验优化模板的package.json脚本使用next dev --turbo启动开发服务器即 Turbo 打包模式同时提供build、start、preview构建后启动、typechecktsc --noEmit等完整脚本见 cli/template/base/package.json 的scripts。严格模式与国际化默认配置开启reactStrictMode: true并在注释中提示如果使用 App Router 的appDir必须注释掉下方i18n配置见 cli/template/base/next.config.js这是 Next.js 新旧路由模式下容易踩坑的兼容性要点。开箱即用的类型安全模板 cli/template/base/tsconfig.json 开启了strict、noUncheckedIndexedAccess、verbatimModuleSyntax等严格编译选项并预置了~/*→./src/*的路径别名paths配置后续所有源码引用如~/server/api/root、~/trpc/react都依赖这一别名。此外原文档特别提到 Next.js 与 Vercel 的组合能让开发与部署变得前所未有的简单免费的额度与直观的界面让站点可以几次点击即可发布。这一点在仓库文档 www/src/pages/no/deployment/vercel.md以及多语言版本中有详细的分步部署说明属于可选的部署增强方案。App Router 与 Pages Router模板的两种应用形态create-t3-app 同时提供 App Router 与 Pages Router 两套模板二者在cli/template/extras/src/下分别以app/与pages/目录组织App Router布局组件位于 cli/template/extras/src/app/layout/base.tsx、with-trpc.tsx、with-tw.tsx、with-trpc-tw.tsx页面组件位于 cli/template/extras/src/app/page/。以 cli/template/extras/src/app/layout/with-trpc.tsx 为例根布局通过next/font/google的Geist字体、metadata导出与TRPCReactProvider包裹实现全局样式与 tRPC 状态注入。Pages Router_app与页面组件分别位于 cli/template/extras/src/pages/_app/ 与 cli/template/extras/src/pages/index/。两种形态的选择直接决定了数据获取 API 的使用方式详见下一节这也是原文档后续讨论Get Static/Server Props的背景。仓库文档 www/src/pages/no/folder-structure-pages.mdx 对 Pages Router 目录结构有专门讲解App Router 版本对应 www/src/pages/en/folder-structure-app.mdx。数据获取Get Static / Server Props 与增量静态再生ISR数据获取是 Next.js 的核心特性也是原文档重点提醒开发者仔细研读的部分。核心结论如下getServerSideProps阻塞调用谨慎使用getServerSideProps服务端渲染时的数据获取在每次请求时于服务端执行它是一个阻塞调用blocking call会让页面变慢因此原文档强烈建议除非有充分的理由否则一般不要使用它getServerSidePropsis generally discouraged unless there is a good reason for it。ISR动态数据的更优替代当数据是动态的、但可以增量获取时增量静态再生Incremental Static RegenerationISR 是getServerSideProps的出色替代方案——它既保留了静态生成的性能优势又能按需通过revalidate时间或按需触发重新生成页面兼顾动态性与吞吐量。原文档明确建议阅读官方数据获取文档以理解各方法间的差异。面向新架构App Router 下的服务端数据获取需要说明的是原文档写作时主要面向 Pages Router 的getServerSideProps/getStaticProps范式。而在 create-t3-app 当前的 App Router 模板中数据获取的核心场景已由React Server ComponentsRSC与 tRPC 的 hydration 机制承载。模板在 cli/template/extras/src/trpc/server.ts 中实现了这一能力import server-only; import { createHydrationHelpers } from trpc/react-query/rsc; import { headers } from next/headers; import { cache } from react; import { createCaller, type AppRouter } from ~/server/api/root; import { createTRPCContext } from ~/server/api/trpc; import { createQueryClient } from ./query-client; // 在 RSC 中包装 createTRPCContext为服务端 tRPC 调用提供请求上下文 const createContext cache(async () { const heads new Headers(await headers()); heads.set(x-trpc-source, rsc); return createTRPCContext({ headers: heads }); }); const getQueryClient cache(createQueryClient); const caller createCaller(createContext); export const { trpc: api, HydrateClient } createHydrationHelpersAppRouter( caller, getQueryClient );这段代码展示了与静态生成/服务端渲染一脉相承的新思路在服务端RSC直接调用 tRPC 路由获取数据再通过HydrateClient把数据水合到客户端避免客户端二次请求瀑布waterfall。配合 cli/template/extras/src/server/api/trpc-app/base.ts 中initTRPC.context...().create({ transformer: superjson })建立的上下文与 superjson 序列化整个链路保持端到端类型安全。运行时环境校验t3-oss/env-nextjs 与 SKIP_ENV_VALIDATIONcreate-t3-app 的 Next.js 模板把类型安全延伸到环境变量层。模板根目录 cli/template/base/src/env.js 使用t3-oss/env-nextjs与 zod 定义 schemaserver.NODE_ENV限定为development | test | production枚举确保应用不会被无效环境变量构建客户端变量必须以NEXT_PUBLIC_前缀暴露client块中预置了NEXT_PUBLIC_CLIENTVAR的注释示例由于 Next.js 的 Edge runtime 与客户端不能直接解构process.env需要通过runtimeEnv手动映射skipValidation: !!process.env.SKIP_ENV_VALIDATION允许在build/dev时跳过校验——这一点对Docker 构建尤为实用cli/template/base/next.config.js 顶部注释也重复强调Run build or dev with SKIP_ENV_VALIDATION to skip env validationemptyStringAsUndefined: true让空字符串按undefined处理避免z.string()校验被空串绕过。tRPC 与 Next.js 的桥接Route Handler 与 API 入口当在客户端组件中发起请求时请求会进入 Next.js 的Route Handler。模板在 cli/template/extras/src/app/api/trpc/[trpc]/route.ts 中通过trpc/server/adapters/fetch的fetchRequestHandler暴露GET/POST两个处理器const handler (req: NextRequest) fetchRequestHandler({ endpoint: /api/trpc, req, router: appRouter, createContext: () createContext(req), onError: env.NODE_ENV development ? ({ path, error }) { console.error( ❌ tRPC failed on ${path ?? no-path}: ${error.message} ); } : undefined, }); export { handler as GET, handler as POST };可见环境变量校验env.NODE_ENV与 tRPC 错误日志策略在真实请求链路中联动而 Pages Router 版本则对应 cli/template/extras/src/pages/api/trpc/[trpc].ts。两套入口共用 cli/template/extras/src/server/api/root.ts 定义的appRouter从源码结构可以推断模板刻意把路由定义与HTTP 适配层解耦便于在不同路由模式下复用。常用资源官方渠道一览原文档末尾提供了一份 Next.js 官方资源清单。由于本仓库为镜像仓库以下仅列出资源名称与用途读者可自行在官方渠道搜索资源说明Next.js Dokumentasjon官方文档数据获取、路由、图片优化等全部 API 的权威参考Next.js GitHub源码与 issue 跟踪可查看版本发布与 RFCNext.js Blogg官方博客新版本特性、最佳实践与生态动态Next.js Discord社区实时交流与官方支持Next.js Twitter版本发布与官方公告的快速渠道Vercel/Next.js YouTube-kanalYouTube 频道官方教程与会议演讲如 Theo 在 Next.js Conf 上关于Next.js 是后端框架的演讲此外本仓库内还有与上述主题强相关的本地文档可作补充阅读www/src/pages/no/usage/trpc.mdtRPC 在 Next.js 中的集成、www/src/pages/no/usage/typescript.md类型安全实践以及 www/src/pages/no/usage/next-auth.md鉴权与 API 路由的结合。小结回归原文档的立意Next.js 之于 create-t3-app是那个把 React 引向好决策的框架层——它提供轻度主张、重度优化的路由、API 与渲染能力配合 Vercel 实现一键部署在数据获取上getServerSideProps因阻塞特性应被谨慎使用动态数据优先考虑 ISR而在模板当前实现中App Router 下的 RSC tRPC hydration 已成为服务端数据获取的主流路径并与t3-oss/env-nextjs的类型安全环境校验、Route Handler 的 tRPC 桥接共同构成一套可复制的全栈实践。理解这一层定位是高效使用 create-t3-app 一切能力的前提。【免费下载链接】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），仅供参考