Next.js hello-world 极简示例：用 create-next-app 起步一个最小可用的 App Router 项目-迪斯科星球

Next.js hello-world 极简示例：用 create-next-app 起步一个最小可用的 App Router 项目

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js

Next.js 官方仓库中的hello-world示例是整个 examples 集合里最精简的起点，它仅由 App Router 的布局与页面两个文件构成，展示了 Next.js 项目最低限度的目录结构与运行方式。本篇围绕 examples/hello-world/README.md 展开：先完整覆盖其中给出的三种包管理器引导命令，再结合示例目录内的真实文件（app/page.tsx、app/layout.tsx、package.json）逐一剖析这个"最小工程"到底由哪些部分组成，最后结合 packages/create-next-app 的源码说明--example参数在底层是如何把示例仓库拉取并转换成本地项目的。读完本文，你可以独立跑通这个示例、读懂每个配置文件的作用，并知道create-next-app --example背后的完整调用链。

一、什么是 hello-world 示例

原文档的定位非常直接：

This is the most minimal starter for your Next.js project.

它自称是 Next.js 项目的"最简起步模板"。从源码结构看，这个"最简"确实名副其实——整个示例目录只包含：

examples/hello-world/ ├── app/ │ ├── layout.tsx # 根布局：声明 <html> 与 <body> │ └── page.tsx # 首页：渲染 <h1>Hello, Next.js!</h1> ├── next.config.ts # 空配置占位 ├── package.json # 依赖与脚本 ├── tsconfig.json # TypeScript 编译选项 └── README.md

没有public/静态资源、没有样式文件、没有额外依赖，是理解 Next.js App Router 项目骨架的最佳入口。

二、用 create-next-app 引导项目（原文档完整命令）

原文档给出的核心操作是通过create-next-appCLI 以hello-world为模板引导新应用。三种包管理器的完整命令如下：

# npm npx create-next-app --example hello-world hello-world-app # Yarn yarn create next-app --example hello-world hello-world-app # pnpm pnpm create next-app --example hello-world hello-world-app

其中--example hello-world指定使用官方示例集合中的 hello-world 模板，第二个参数hello-world-app是本地项目目录名。引导完成后即可在该目录中执行npm run dev启动开发服务器。

原文档还提示可以借助 Vercel 将示例一键部署到云端，这里保留该部署思路作为延伸选项，但本地验证只需依赖 Node.js 与任一种包管理器即可。

三、create-next-app 的 --example 是如何工作的

--example是 create-next-app 提供的能力之一，其 CLI 参数定义见 packages/create-next-app/index.ts：

-e, --example <example-name|github-url>：指定示例名（官方仓库中的示例）或 GitHub URL，URL 可以指向任意分支和任意子目录；
--example-path <path-to-example>：用于 GitHub URL 中分支名含有斜杠（如bug/fix-1）时，单独指定示例路径以避免解析歧义。

从源码结构看，引导流程的关键调用链位于 packages/create-next-app/create-app.ts：

若传入的example是 URL，则用new URL(example)解析出仓库地址，再交给getRepoInfo提取仓库信息；
若是裸示例名（如hello-world），则调用existsInRepo(example)校验该示例是否存在于官方示例集合中，不存在时给出拼写提示（源码中对应Could not locate an example named ...的报错分支）；
校验通过后执行downloadAndExtractExample(root, example)下载并解压示例文件到目标目录，且套用了重试逻辑（retry(...)）；
对 TypeScript 示例，还会额外复制next-env.d.ts到项目中（源码注释：Copy next-env.d.ts to any example that is typescript）。

示例存在性的校验逻辑在 packages/create-next-app/helpers/examples.ts 中实现：它会请求官方仓库examples/目录的内容列表并检查package.json是否可下载，从而确认目标路径确实是一个合法的 Next.js 示例。这意味着--example hello-world之所以有效，正是因为当前仓库中确实存在 examples/hello-world/package.json。

此外，README 中还列出了若干与示例引导配合常用的参数：--skip-install（跳过依赖安装）、--disable-git（跳过 git 初始化）、--use-npm / --use-pnpm / --use-yarn / --use-bun（显式指定包管理器）、--reset-preferences与--yes（偏好控制）。这些参数与--example组合使用，可以完全无人值守地批量创建项目。

四、最小工程逐文件解析

app/page.tsx：首页即一个 React 函数组件

examples/hello-world/app/page.tsx 的全部内容：

export default function Page() { return <h1>Hello, Next.js!</h1>; }

在 App Router 中，app/page.tsx对应根路径/的页面。这里没有export const dynamic、没有数据获取钩子，说明它就是一个静态可预渲染的页面——这也是 Next.js 的默认行为：能静态化的路由默认静态化。

app/layout.tsx：根布局是 App Router 的强制要求

examples/hello-world/app/layout.tsx：

export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( <html lang="en"> <body>{children}</body> </html> ); }

根布局（root layout）必须提供<html>和<body>标签，children插槽承载路由页面的输出。该示例没有引入任何metadata导出，可见 Next.js 并不强制元数据——但实际项目中建议在此补充export const metadata来设置标题与描述。

package.json：三个脚本 + 四个运行时依赖

examples/hello-world/package.json 的关键内容：

{ "private": true, "scripts": { "dev": "next dev --turbopack", "build": "next build", "start": "next start" }, "dependencies": { "next": "latest", "react": "^18.2.0", "react-dom": "^18.2.0" }, "devDependencies": { "@types/node": "20.10.8", "@types/react": "18.2.47", "@types/react-dom": "18.2.18", "typescript": "^5.3.3" } }

几个值得注意的细节：

private: true防止示例项目被误发到包仓库；
dev脚本带--turbopack标志，即用 Turbopack 作为开发服务器打包器，这是当前仓库中官方示例推荐的开发体验；
next依赖固定为latest标签而非具体版本号，因为示例模板的定位是"跟随最新稳定行为"，而生产项目应锁定具体版本；
React 为^18.2.0，类型包版本与之配套，typescript为^5.3.3。

典型的使用闭环：npm run dev启动开发模式（热更新 + Turbopack），npm run build产出.next构建产物并执行预渲染，npm run start在本地以生产模式验证构建结果。

next.config.ts：零配置占位

examples/hello-world/next.config.ts：

import type { NextConfig } from "next"; const nextConfig: NextConfig = { /* config options here */ }; export default nextConfig;

这是一个 TypeScript 类型的空配置占位文件。它印证了最小项目的另一个特征：Next.js 的所有功能（路由、预渲染、图片、字体等）都开箱即用，next.config.ts只在需要定制（如rewrites、images、output等）时才需要填充。

tsconfig.json：Next.js 官方模板的编译器选项

examples/hello-world/tsconfig.json 是标准的 Next.js TS 项目配置，几个核心选项：

选项	值	说明
`target`	`es5`	最低运行时目标；实际产物由 Next.js 工具链决定，此值主要影响类型检查
`strict`	`false`	最小示例有意放宽严格模式以降低上手门槛；生产项目建议开启
`jsx`	`react-jsx`	使用自动 JSX 运行时，无需`import React`
`moduleResolution`	`node`	Node 风格模块解析
`noEmit`/`isolatedModules`	`true`	编译由 Next.js 接管，TS 仅做类型检查
`plugins`	`[{ "name": "next" }]`	启用 Next.js 语言服务插件，提供类型化路由提示
`include`	含`.next/types/*/.ts`	纳入 Next.js 生成的类型文件（如`page.tsx`参数校验类型）

exclude排除了node_modules与测试文件。include中对.next/dev/types的覆盖说明 Next.js 在 dev 与 build 两个模式下都会生成路由级类型定义。

五、从最小示例出发的扩展路径

hello-world 的价值在于"最小可运行"，而非功能完备。从该骨架出发，仓库中的示例集合提供了清晰的进阶方向，均可用同样的方式引导：

npx create-next-app --example <example-name> <project-dir>

例如需要 CMS 集成、认证（auth 系列示例）、样式方案（panda-css、with-sass 等）或数据库接入时，替换--example参数即可，引导机制与本文第三节的调用链完全一致。而当你需要完全自定义项目结构时，也可以不传--example，直接使用create-next-app的默认模板（TypeScript + Tailwind 为默认选项）。

小结

examples/hello-world是 Next.js 官方仓库中最精简的 App Router 起点：app/layout.tsx+app/page.tsx+ 空next.config.ts构成可运行的最小工程；
引导命令为npx create-next-app --example hello-world hello-world-app（或 yarn/pnpm 等价形式），引导完成后npm run dev / build / start即构成完整开发生命周期；
从 packages/create-next-app 源码可确认，--example会校验示例在官方仓库中的存在性，再下载、解压示例文件并对 TS 项目补齐next-env.d.ts，整个过程带重试与拼写纠错提示；
理解了这个最小骨架与引导机制后，即可按第三节所述参数灵活组合create-next-app，或以--example切换到集合中任何更复杂的官方示例继续扩展。

【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析