Next.js App Router 特殊文件全解（Next.js 15 最新）

发表于

Next.js App Router 特殊文件大全（Next.js 15 最新）

在 Next.js App Router 中，有一些文件名具有特殊含义，只要放在 app 目录的特定位置，Next.js 就会自动识别并应用对应功能。
本文将系统整理这些特殊文件的作用、使用方式和注意事项。

1. page.tsx / page.jsx

作用：定义当前路由的页面内容。

使用方法：

1
2
3
export default function Page() {
  return <h1>首页</h1>;
}

注意事项：
- 每个目录只能有一个 page.tsx。
- 必须是默认导出（default export）。
- 与 layout.tsx 搭配可实现共享布局。

2. layout.tsx

作用： 定义当前路由及其子路由的共享布局。

使用方法：
1
2
3
4
5
6
7
8
9
10
11
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <header>公共头部</header>
        {children}
        <footer>公共底部</footer>
      </body>
    </html>
  );
}

注意事项：
- 接收 children 属性。
- 可嵌套，形成分层布局。
- 元数据可在 layout.tsx 中配置，作用于所有子页面。

3. template.tsx

作用： 类似布局，但不会缓存，每次导航都会重新渲染。

使用场景：

  • 需要强制刷新 UI 状态的布局，如动画过渡页面。
1
2
3
export default function Template({ children }: { children: React.ReactNode }) {
  return <div className="fade">{children}</div>;
}

注意事项：

  • 与 layout.tsx 不同，template.tsx 不会在客户端保留状态。
  • 适合做页面切换动画或临时状态隔离。

4. not-found.tsx

作用： 定义当前路由下的 404 页面。
1
2
3
export default function NotFound() {
  return <h2>页面不存在</h2>;
}

注意事项：
- 只影响所在目录及子路由。
- 可在代码中调用 notFound() 来触发。

5. error.tsx

作用： 捕获并渲染当前路由的运行时错误。
1
2
3
4
5
6
7
8
9
10
"use client";

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>出错了</h2>
      <button onClick={() => reset()}>重试</button>
    </div>
  );
}

注意事项：
- 必须是客户端组件（”use client”）
- reset() 可重新渲染页面

6. loading.tsx

作用： 定义当前路由的加载状态 UI。
1
2
3
export default function Loading() {
  return <p>加载中...</p>;
}

注意事项：
- 会在页面加载或切换时自动显示。
- 适合与 流式渲染（Streaming） 搭配。

7. default.tsx

作用： 用于并行路由中定义默认子路由。

1
2
3
export default function Default() {
  return <p>这是默认视图</p>;
}

注意事项：

  • 仅用于并行路由 (folder) 机制。

8. route.ts / route.js

作用： 定义 API 路由（取代 pages/api）。

1
2
3
export async function GET() {
  return Response.json({ message: 'Hello API' });
}

注意事项：

  • 可导出 GET, POST, PUT, DELETE 等方法。
  • 返回 Response 对象。

9. head.tsx

作用： 自定义 HTML 内容。

1
2
3
4
5
6
7
8
export default function Head() {
  return (
    <>
      <title>我的网站</title>
      <meta name="description" content="描述内容" />
    </>
  );
}

注意事项：

  • 仅在当前路由及子路由生效。
  • 不推荐与 metadata API 混用。

10. metadata API（非文件，但常用）

作用： 配置页面 SEO 信息。
1
2
3
4
export const metadata = {
  title: '产品详情',
  description: '这是产品详情页'
};

11. opengraph-image.tsx / twitter-image.tsx

作用： 动态生成社交分享图片。

1
2
3
4
5
6
7
import { ImageResponse } from 'next/og';

export const size = { width: 1200, height: 630 };

export default function Image() {
  return new ImageResponse(<div>分享图</div>, { width: 1200, height: 630 });
}

12. icon.tsx / apple-icon.tsx / favicon.ico

作用： 定义网站图标。
1
2
3
export default function Icon() {
  return <svg>...</svg>;
}

13. manifest.webmanifest

作用： PWA 应用清单。

⸻

总结

文件名 作用
page.tsx 页面内容
layout.tsx 共享布局
template.tsx 非缓存布局
not-found.tsx 404 页面
error.tsx 错误处理
loading.tsx 加载状态
default.tsx 并行路由默认页
route.ts API 路由
head.tsx 自定义 head
opengraph-image.tsx 分享图片
icon.tsx 网站图标
manifest.webmanifest PWA 配置