React Academy · 课时

App Router 文件约定

了解 app/ 目录以及 page.tsx、layout.tsx、loading.tsx 和 error.tsx 文件。

App Router 文件约定 是 CoddyKit 上的免费 React Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 React Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Academy 课程共包含 4 节课。

app/ 目录

Next.js App Router 使用 app/ 目录。文件夹定义 URL 路径段；文件夹中的特殊文件定义每个路径段的行为。

page.tsx — 路由界面

page.tsx 导出针对某个 URL 路径段渲染的 React 组件。没有 page.tsx 时，该路由无法公开访问。

// app/dashboard/page.tsx
export default function DashboardPage() {
  return <h1>Dashboard</h1>;
}
// → accessible at /dashboard

layout.tsx — 持久外壳

layout.tsx 包裹子路由。它会在导航过程中持续存在——子路由变化时，其状态不会重置。

// app/layout.tsx (root layout — required)
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  );
}

loading.tsx — 即时加载界面

loading.tsx 会在页面的异步数据加载期间立即渲染。它会将页面包裹在自动创建的 Suspense 边界中。

// app/dashboard/loading.tsx
export default function Loading() {
  return <Skeleton />;
}
// Shown while dashboard/page.tsx is fetching

error.tsx — 错误边界

error.tsx 是该片段的 React 错误边界。它会接收错误和用于重试的 reset 函数。

'use client';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <p>Something went wrong: {error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

not-found.tsx — 404 界面

当服务器组件调用 notFound()，或没有路由匹配时，not-found.tsx 会进行渲染。

// app/not-found.tsx
export default function NotFound() {
  return (
    <div>
      <h2>404 — Page not found</h2>
      <Link href="/">Go home</Link>
    </div>
  );
}

template.tsx — 重新挂载布局

template.tsx 类似于 layout.tsx，但会在每次导航时创建新实例——状态会重置，副作用会重新运行。它适用于动画或分析。

// app/shop/template.tsx
export default function ShopTemplate({ children }: { children: React.ReactNode }) {
  return <div className="shop-fade-in">{children}</div>;
}

route.ts — API 路由

route.ts（不是 route.tsx）会导出 HTTP 方法处理器（GET、POST 等），用于在 app/ 目录中创建 API 端点。

// app/api/users/route.ts
export async function GET() {
  const users = await getUsers();
  return Response.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await createUser(body);
  return Response.json(user, { status: 201 });
}

middleware.ts — 边缘中间件

项目根目录中的 middleware.ts 会在边缘环境中、每个匹配的请求之前运行——用于身份验证检查、重定向和请求标头重写。

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token) return NextResponse.redirect(new URL('/login', request.url));
  return NextResponse.next();
}

export const config = { matcher: ['/dashboard/:path*'] };

文件共置

您可以将非路由文件（组件、工具函数、测试）与路由文件放在 app/ 文件夹中。只有使用特殊约定命名的文件（page、layout 等）才会被视为路由片段。

嵌套布局

每个文件夹都可以拥有自己的 layout.tsx。嵌套布局只包裹其片段的子内容，并与上层的父布局组合。

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  return (
    <div className="dashboard">
      <Sidebar />
      <main>{children}</main>
    </div>
  );
}

快速检查

哪个 App Router 文件会在页面的异步数据加载期间提供自动的 Suspense 回退界面？

回顾

App Router 使用特殊文件：page.tsx（路由界面）、layout.tsx（持久外壳）、loading.tsx（Suspense 回退界面）、error.tsx（错误边界）、not-found.tsx（404）、route.ts（API）和 middleware.ts（边缘逻辑）。

常见问题解答

「App Router 文件约定」课时是免费的吗？

是的 — 「App Router 文件约定」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Academy 课程共包含 4 节课。

「App Router 文件约定」这节课中我会学到什么？

了解 app/ 目录以及 page.tsx、layout.tsx、loading.tsx 和 error.tsx 文件。你通过在浏览器中直接运行的动手代码来练习 React Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「App Router 文件约定」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Academy 课中编写并运行代码吗？

能。每节 React Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 React Academy