Next.js中App Router 全部特殊文件一览

文章目录

前言
- - [与页面渲染相关的 6 个约定文件](#与页面渲染相关的 6 个约定文件)
  - [与导航和路由相关的 4 个文件](#与导航和路由相关的 4 个文件)
  - [与 metadata 相关的](#与 metadata 相关的)
  - [优先级 / 层级关系](#优先级 / 层级关系)
  - 三个最常用的一图对比
  - 官方文档入口

前言

Next.js中App Router有一些约定好的页面功能。我们这里看看。

与页面渲染相关的 6 个约定文件

文件	类似 `loading.tsx`	触发时机	文档
`loading.tsx`	是	同级 page.tsx 数据还没准备好	Loading UI and Streaming
`error.tsx`	是	同级 page.tsx throw	Error Handling
`not-found.tsx`	是	`notFound()` 调用 / URL 不匹配	Not Found
`global-error.tsx`	是	根 layout 出错（必须自含 `<html><body>`）	Global Error
`template.tsx`	部分	每次导航都重新挂载（layout 不重新挂载）	Templates
`default.tsx`	是	Parallel Routes 中作为回退	Parallel Routes

与导航和路由相关的 4 个文件

文件	作用	文档
`middleware.ts`	请求拦截（重定向/重写/401）	Middleware
`sitemap.ts` / `robots.ts`	SEO 元信息	Sitemap
`opengraph-image.tsx`	社交分享卡片图片	OpenGraph
`route.ts`	API 路由（替代 pages/api）	Route Handlers

与 metadata 相关的

文件	作用	文档
`layout.tsx` / `page.tsx` 中的 `metadata` export	页面标题、描述、SEO	Metadata

优先级 / 层级关系

js 复制代码

page.tsx 加载中 → loading.tsx（同级优先，向上冒泡）
page.tsx throw   → error.tsx（同级优先，向上冒泡）
page.tsx notFound() → not-found.tsx（同级优先）
layout throw      → global-error.tsx（根层级兜底）
每次导航都重来   → template.tsx（layout 只挂载一次）

三个最常用的一图对比

js 复制代码

              loading.tsx          error.tsx          not-found.tsx
              ───────────         ──────────         ─────────────
触发方式:      自动(Suspense)       子组件 throw        notFound() / URL不匹配
需'use client': ❌                  ✅(接受reset prop)  看情况(onClick需要)
替换范围:      同级的 children      同级的 children     同级的 children
向上冒泡:      ✅                   ✅                  ❌(就近原则)
本项目使用:     ✅ 刚加              ✅ 已加             ✅ 已加

官方文档入口

App Router 总览: https://nextjs.org/docs/app
文件约定（全部 file-conventions）: https://nextjs.org/docs/app/api-reference/file-conventions
路由（Routing）: https://nextjs.org/docs/app/building-your-application/routing

loading.tsx 的原理就是 Next.js 用 <Suspense> 包裹了你页面，源码本质：

ts 复制代码

// Next.js 内部等价于
<Suspense fallback={<ConversationLoading />}>
  <ConversationChatPage />
</Suspense>

你只需创建文件，框架自动帮你包裹。