create-next-app 官方 Tailwind + TypeScript 默认模板（Pages Router）完整上手指南：从启动开发服务器到路由、API 与部署

create-next-app 官方 Tailwind TypeScript 默认模板Pages Router完整上手指南从启动开发服务器到路由、API 与部署【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js本篇指南解读 default-tw/ts 模板的 README-template.md 及其同目录工程骨架。这份文档会随着create-next-app脚手架的运行被原样落盘到新项目的根目录并更名为README.md成为开发者接触新项目的“第一份说明书”。读完本文你将掌握如何启动开发服务器、理解 Pages Router 目录约定、编写 API 路由、使用next/font优化字体以及把项目部署到云端与继续深入学习的方向。文档的定位它是脚手架“生成物”不是仓库文档要正确阅读这份 README首先需要明确它的来源它不是人工维护在仓库根目录的项目文档而是一个模板文件template。它位于 packages/create-next-app/templates/default-tw/ts/ 目录下同目录还并列存放着pages/、public/、styles/以及next.config.ts、tsconfig.json、eslint.config.mjs、postcss.config.mjs、biome.json等文件。当用户执行create-next-app创建新项目时脚手架会把这些文件整体复制到目标目录。真正决定这份 README 命运的代码在 模板复制逻辑 中rename(name) { switch (name) { case gitignore: { return .${name}; } // README.md is ignored by webpack-asset-relocator-loader used by ncc case README-template.md: { return README.md; } default: { return name; } } },也就是说gitignore会被改名为隐藏文件.gitignore而README-template.md会在目标项目中变成README.md。这也是为什么模板文件名刻意写成README-template——打包器ncc 的 webpack-asset-relocator-loader会忽略名为README.md的文件改名既能避免打包遗漏又能保证用户项目拿到规范命名的说明文档。default-tw模板族同时提供js见 default-tw/js与ts两套实现本文聚焦的ts版本是“Pages Router Tailwind CSS TypeScript”的组合。生成项目的目录结构一览脚手架复制完成后新项目即拥有与模板一致的目录布局。以下路径均可对照仓库中的模板源文件查看pages/_app.tsx应用级组件外壳负责引入全局样式并透传页面组件pages/_document.tsx服务端渲染阶段自定义Html、Head、Main、NextScript的文档骨架pages/index.tsx首页组件即脚手架启动后的默认落地页pages/api/hello.ts一个开箱即用的 API 路由示例public/静态资源目录存放next.svg、vercel.svg、globe.svg、window.svg与favicon.icostyles/globals.cssTailwind CSS v4 入口样式与明暗主题变量next.config.tsNext.js 配置默认开启reactStrictModetsconfig.json、eslint.config.mjs、postcss.config.mjs、biome.json类型检查、Lint 与样式的工程化配置。值得一提的是 TS 版本与 JS 版本在配置命名上有差异TS 工程使用next.config.ts与tsconfig.json并附带next-env.d.ts而 JS 工程使用next.config.mjs与jsconfig.json。启动开发服务器四种包管理器任选模板 README 给出了启动开发服务器的全部命令这是新项目第一次“跑起来”的标准动作npm run dev # or yarn dev # or pnpm dev # or bun dev命令背后实际执行的是 Next.js 的next dev。启动成功后用浏览器打开http://localhost:3000即可看到模板首页页面上是 Next.js 与 Vercel 的 Logo、标题“To get started, edit theindex.tsxfile.”以及 “Deploy Now” 与 “Documentation” 两个入口按钮对应 UI 代码见 首页 JSX。开发服务器具备几项内建能力模板 README 用一句话点出最关键的一项“页面会随你的编辑自动更新”page auto-updates。也就是说保存 pages/index.tsx 后浏览器无需手动刷新即可看到改动这是 Next.js 的 Fast Refresh 热更新机制在起作用。同时可以留意模板的 tsconfig.json 的 include 字段 还包含了.next/types/**/*.ts与.next/dev/types/**/*.ts——启动开发服务器或执行构建时Next.js 会自动在.next目录中生成路由类型声明供编辑器提供强类型的页面级类型提示。从“编辑首页”认识 Pages Router 的文件即路由模板 README 指引你“通过修改pages/index.tsx开始编辑页面”。这句话背后的核心机制是 Next.js Pages Router 的文件系统路由约定文件位于pages/目录下即被当作页面而非普通模块pages/index.tsx对应根路径/pages/api/下的文件则被当作 API 路由而非 React 页面详见下一节。以首页实现为例模板通过 next/font/google 加载 Geist 字体变量再配合 Tailwind 的原子类如flex min-h-screen items-center justify-center bg-zinc-50 dark:bg-black完成居中布局与明暗主题适配。整个首页没有手写任何 CSS 文件样式完全由 Tailwind 工具类驱动这正是default-twdefault tailwind模板族的风格特征——样式体系直接建立在 styles/globals.css 之上import tailwindcss; :root { --background: #ffffff; --foreground: #171717; } theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } media (prefers-color-scheme: dark) { :root { --background: #0a0a0a; --foreground: #ededed; } }这段样式揭示了模板的明暗主题实现思路theme inline把 Tailwind 语义色background/foreground及字体变量与 CSS 自定义属性绑定并通过prefers-color-scheme媒体查询在暗色系统下切换前景/背景色。API 路由pages/api 目录即/api/*模板 README 对 API 路由做了清晰的约定说明pages/api目录映射到/api/*该目录下的文件被视为 API 路由而非 React 页面。模板自带的示例 pages/api/hello.ts 完整代码如下// Next.js API route support import type { NextApiRequest, NextApiResponse } from next; type Data { name: string; }; export default function handler( req: NextApiRequest, res: NextApiResponseData, ) { res.status(200).json({ name: John Doe }); }create-next-app会在create-app.ts的引导阶段探测 API 路由的存在进而决定是否询问用户“是否启用 App Router”之外的选项对使用者而言模板 README 提供了两类访问入口页面路由在pages/index.tsx接口路由则通过 http://localhost:3000/api/hello 访问返回{ name: John Doe }。注意上述示例导出的handler使用NextApiRequest/NextApiResponse显式标注类型并用泛型NextApiResponseData约束响应体的数据结构——这是 Pages Router 下编写 TS API 路由的标准姿势。想要再新增一个接口只需在pages/api/下新建文件即可例如pages/api/user.ts会自动获得/api/user路径。字体优化next/font 与 Geist 字族模板 README 特别提到项目使用next/font自动优化并加载 Geist 字体——Vercel 推出的新字体族。Geist 在模板中作为默认字体说明其视觉风格与 Next.js 官方生态的契合度较高。模板并没有把字体文件打包进项目而是从next/font/google运行时拉取并做构建期优化相关用法见 首页顶部的字体声明const geistSans Geist({ variable: --font-geist-sans, subsets: [latin], }); const geistMono Geist_Mono({ variable: --font-geist-mono, subsets: [latin], });其中两个细节值得关注variable参数把字体实例导出为 CSS 变量--font-geist-sans与--font-geist-mono随后在 globals.css 的theme inline块中被赋给 Tailwind 的--font-sans/--font-mono从而让font-sans、font-mono等 Tailwind 工具类直接命中 Geist 字体首页根节点在 className 中同时注入两个变量${geistSans.variable} ${geistMono.variable}CSS 变量由此作用于整个组件树。next/font的价值在于构建期下载与自托管字体文件避免运行时请求第三方字体服务从而减少布局偏移CLS并利于自包含部署。配套工程化配置速览除运行命令与目录约定外模板还为你预置了一整套开箱即用的工程化配置README 虽未逐条展开但均可从模板源文件直接验证TypeScript 配置tsconfig.json开启strict、esModuleInterop、isolatedModules使用moduleResolution: bundler与jsx: react-jsx并定义/*指向项目根目录的路径别名页面内import /styles/globals.css即由此解析见 _app.tsxNext.js 配置next.config.ts默认开启reactStrictMode: true帮助你在开发期尽早暴露潜在的渲染问题ESLint 配置eslint.config.mjs采用扁平化配置flat config风格基于eslint-config-next的core-web-vitals与typescript规则集并忽略.next/、out/等产物目录代码格式化biome.json提供 Biome 格式化/检查能力脚手架运行时会根据用户在 CLI 中的选择决定是否把biome.json与eslint.config.mjs一并复制进目标项目见 templates/index.ts 的 copySource 逻辑。部署与后续学习模板 README 的收尾部分给出两条主线部署README 建议直接使用 Vercel PlatformNext.js 的创建方提供来部署并指出更完整的部署细节可以参考 Next.js 官方部署文档。对于 Pages Router 项目部署前建议先执行生产构建与本地预览以验证产物继续学习模板分别指向 Next.js 官方文档与交互式教程。若想回到当前仓库查阅一手资料Pages Router 的路由、数据获取与优化相关文档位于 docs/02-pagesApp Router 体系见 docs/01-app若要研究脚手架本身的 CLI 选项与模板分发机制可直接阅读 packages/create-next-app/index.ts 与 模板目录。总体而言这份 README-template 的价值不在于罗列 API而在于为刚生成的工程划定“入口”开发服务器怎么跑npm run dev、页面去哪改pages/index.tsx、接口放哪写pages/api/hello.ts、字体怎么用next/font Geist、部署往哪走。它配合模板源码构成一套从零起步、可直接运行的完整示例工程。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考