NextJS 笔记

这是一篇课堂笔记，课程为 Udemy React - The Complete Guide 2024。该笔记包含了该课程中有关 NextJS 的部分内容。

NextJS 允许你使用 React 开发全栈应用。

服务端组件

在 NextJS 中，你使用常规的 JSX 语法创建组件。但在默认情况下，这些组件都是服务端组件（React Server Components, RSC），这意味着，如果你在其中添加一句 console.log()，然后打开浏览器的控制台，你并不能在此处看到任何输出。相反，你可以在你运行这个 NextJS App 的终端中看到它们。

export default function Page() {
  // console.log("My component!"); // no output on client side
  return <p>My component!</p>;
}

原生 React 中就存在着客户端与服务端组件的区分，但是当我们使用 Vite 等构建系统时，默认都使用客户端组件。使用服务端组件的好处是：服务端会将最后渲染完成的代码发给客户端显示，它们更小，并且对 SEO 更友好（因为如果使用客户端组件，页面实际上都是空的，其中的内容都是其中的 JS 代码在填充；而使用服务端组件，右键查看源代码，可以看到显示的就是已经渲染的组件的代码）。但是，不是所有的 React 功能都在服务端组件可用，例如 Hooks、事件处理就仅在客户端组件中可用（这是合理的）。

为了在 NextJS 中使用客户端组件，需要在组件文件首行添加：

"use client";

App 路由

NextJS 使用一个基于目录的路由，默认推荐使用的是 App Router。在项目目录中，你可以找到一个名为 app 的目录。通过在此目录下创建相应的文件，就可以创建出路由。例如，如果希望创建 /about 页面，就需要在 app 中创建 about 目录，并在其中添加 page.js。你必须遵循特定的名称，这些特定名称的文件对应不同的功能：

page.js：定义页面组件
layout.js：定义页面的包装器
not-found.js：定义 404 页面
error.js：定义错误页面
loading.js：定义加载页面
route.js：创建 API 路由，它不返回 JSX 代码，而直接返回 JSON 数据
…（更多见文档）

顺便一说，既可以使用 .js，也可以使用 .jsx。现在你可以在 app/about/page.js 中定义关于页面的组件了。该组件的名称是无关紧要的：

export default function AboutPage() {
  return <h1>About Us</h1>;
}

为了在 NextJS 中切换路由，可以这样做：

import Link from "next/link";
// ...
<Link href="/about">Go to about</Link>;

动态路由

如果我们有很多博客文章，它们位于 /posts/post-1 、/posts/post-2 等等路由下。我们可以在posts 目录下，创建一个特殊的以 [] 包裹的目录，例如 [slug]，然后在其中编辑 page.js：

export default function BlogPostPage({ params }) {
  return <h1>{params.slug}</h1>;
}

“Slug” 指的是一种用于生成 URL 的字符串。它是一个较短的、可读的、通常是唯一的标识符，用于在 URL 中表示某个特定的资源。它通常是从资源的标题或名称中派生出来的，并且通常是小写字母、数字和连字符的组合，以便在浏览器中更容易阅读和理解。

例如，如果你有一篇博客文章标题为 “如何学习编程”，那么对应的 slug 可能是 “ru-he-xue-xi-bian-cheng”。

获取路由的路径

为了获取当前路由，可以使用 usePathname:

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";

export default function NavLink({ href, children }) {
  const path = usePathname();
  return (
    <Link href={href} className={path.startsWith(href) ? "active" : undefined}>
      {" "}
      {children}{" "}
    </Link>
  );
}

Layout

NextJS 允许你使用 layout.js 来决定页面应该如何显示在什么位置。项目中必须包含一个 RootLayout，它定义在 app/layout.js 中：

import "./global.css";

export const metadata = {
  title: "NextJS Course App",
  description: "Your first NextJS app!",
};

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

注意到两件事情：

我们在该函数组件中使用了 <html> 和 <body>，这在一般的 React 项目中是没有的；
我们没有在 <html> 中包含 <head> 并定义一些 metadata，相反，我们导出了一个名为 metadata 的变量，并在其中配置了一些 metadata。事实上，变量 metadata 在 NextJS 中是保留的，它会自动地插入到最后生成的 HTML 中。

你也可以创建一个嵌套的 Layout，只需要在子目录中创建一个 layout.js。这个 Layout 始终会嵌套在上层 Layout 中。

网站图标

通过在 app 目录下直接添加一个名为 icon 的文件（例如 icon.png），就可以将该图片作为 NextJS App 的 Favicon。

自定义组件

可以创建一个与 app 同级的目录 components 专门用于存放自定义组件，例如，如果存在 components/header.js，可以在需要使用它的地方按如下方法使用：

import Header from "@/components/header";
// ...
<Header />;

导入语句中的 @ 用于标识根目录。它实际上是个别名，定义于根目录下的 jsconfig.json 文件中。

图像

就像在原生 React 中那样，你可以使用类似于下面的语句导入一张图片：

import logoImg from "@/assets/logo.png";

但是，与原生 React 不同的是，你不能这样做：

<!-- wrong way in next.js -->
<img src={logoImg} alt="Logo" />

而必须使用其 src 属性：

<img src={logoImg.src} alt="Logo" />

但是更建议的做法是，使用 NextJS 提供的 <Image>。它提供了自动的懒加载、自动检测图片大小、自动为不同设备提供不同大小的图片、自动以 WebP 格式传输以提高效率以及大量其他高级功能（这里添加了 priority 关闭了懒加载功能，因为这是个 Logo，始终应该显示）：

import Image from 'next/image';
import logoImg from '@/assets/logo.png';

<!-- pass the object directly -->
<Image src={logoImg} alt="Logo" priority />

可以使用 fill prop，来指定图片填充于父组件定义的空间中。这种方法适用于需要显示长宽未知的图片的情况。

CSS

在前面我们已经看到了全局 CSS 的导入方法，在我们的 Root Layout 中：

import "./global.css";

NextJS 还支持 CSS 模块，只需要使用类似 *.module.css 的命名方式，就可以使用下面的方法导入并使用该 CSS 定义的内容，并且将其限定在特定的组件中：

.header {
  /* ... */
}

.logo {
  /* ... */
}

import classes from './header.module.css'; // you can choose any name
// ...
<header className={classes.header}>
  <Link className={classes.logo}>
    <!-- ... -->
  </Link>
</header>

配置 SQLite 数据库

下面使用 better-sqlite3 配置了一个 SQLite 数据库供后面使用：

npm install better-sqlite3

const sql = require("better-sqlite3");
const db = sql("meals.db");

const dummyMeals = [
  {
    title: "Juicy Cheese Burger",
    slug: "juicy-cheese-burger",
    image: "/images/burger.jpg",
    summary: "...",
    instructions: `...`,
    creator: "John Doe",
    creator_email: "johndoe@example.com",
  },
  // ...
];

db.prepare(
  `
   CREATE TABLE IF NOT EXISTS meals (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       slug TEXT NOT NULL UNIQUE,
       title TEXT NOT NULL,
       image TEXT NOT NULL,
       summary TEXT NOT NULL,
       instructions TEXT NOT NULL,
       creator TEXT NOT NULL,
       creator_email TEXT NOT NULL
    )
`
).run();

async function initData() {
  const stmt = db.prepare(`
      INSERT INTO meals VALUES (
         null,
         @slug,
         @title,
         @image,
         @summary,
         @instructions,
         @creator,
         @creator_email
      )
   `);

  for (const meal of dummyMeals) {
    stmt.run(meal);
  }
}

initData();

获取数据

在 NextJS 中，你仍然可以像原生 React 中做的那样，使用 useEffect 配合 fetch 用请求的方式从某个后端获取数据。但是，由于我们在使用 NextJS 这样一个全栈框架，我们已经拥有了一个后端。所以，在这里直接操作数据库也是安全的。

创建 meals.js：

import sql from "better-sqlite3";
const db = sql("meals.db");

export async function getMeals() {
  // 模拟该操作会花费一些时间
  await new Promise((resolve) => setTimeout(resolve, 2000));
  return db.prepare("SELECT * FROM meals").all();
}

然后，在需要使用它的组件代码中：

与原生 React 不同，你可以将组件函数使用 async 修饰

import { getMeals } from "@/lib/meals";

export default async function MealsPage() {
  const meals = await getMeals();
  // ...
}

加载

为了添加加载页面，只需要在对应路由的目录下，添加 loading.js，并编辑一些自定义的加载代码即可：

export default function MealsLoadingPage() {
  return <p>Fetching meals...</p>;
}

这样的加载是面向整个页面组件的。如果我们希望只是加载部分元素，可以使用 Suspense：

import { Suspense } from "react";

async function Meals() {
  const meals = await getMeals();
  // ...
}

// ...

<Suspense fallback={<p>Fetching meals...</p>}>
  <Meals />
</Suspense>;

错误

通过在对应路由目录下添加 error.js，可以创建错误页面。该组件必须是客户端组件：

"use client";

export default function Error({ error }) {
  return <h1>An error occured!</h1>;
}

Not Found

通过在对应路由目录下添加 not-found.js，可以创建 Not Found 页面。

export default function NotFound() {
  return <h1>Not Found</h1>;
}

如果希望以编程方式手动切换到 Not Found 组件，可以使用：

import { notFound } from "next/navigation";

if (!meal) {
  notFound();
}

Server Action

通过在函数中添加 'use server'; 可以确保某个函数在服务器上执行，此外，还必须将该函数使用 async 修饰。顺便一说，这个功能在原生 React 中是存在的。但为了让其生效，你必须使用一个像是 NextJS 这样的框架。

export default function ShareMealPage() {
  async function shareMeal(formData) {
    'use server';
    const meal = {
      title: formData.get('title'),
      // ...
    };
    // ...
  }

  return (
    <form action={shareMeal}>
      <!-- ... -->
    </form>
  );
}

'use server'; 无法在客户端组件中使用，所以你可能需要将 Server Actions 存储到单独的文件中：

"use server";
import { redirect } from "next/navigation";

export async function shareMeal(formData) {
  const meal = {
    title: formData.get("title"),
    // ...
  };

  // ... server-side validation

  await saveMeal(meal);
  redirect("/meals");
}

添加 XSS 保护

如果我们需要将用户填写的内容创建为 HTML，就必须添加 XSS 保护。下面的例子还使用 Slugify 来根据标题创建 Slug：

// npm install slugify xss
export function saveMeal(meal) {
  meal.slug = slugify(meal.title, { lower: true });
  meal.instructions = xss(meal.instructions);
}

保存文件和数据

使用 NodeJS 提供的 fs，可以存储将文件存储到服务器本地：

import fs from 'node:fs';

export function saveMeal(meal) {
  meal.slug = slugify(meal.title, { lower: true });
  meal.instructions = xss(meal.instructions);

  const extension = meal.image.name.split('.').pop();
  const fileName = `${meal.slug}.${extension}`;

  const stream = fs.createWriteStream(`public/images/${fileName}`);
  const bufferedImage = await meal.image.arrayBuffer();

  stream.write(Buffer.from(bufferedImage), (error) => {
    if (error) {
      throw new Error('Saving image failed!');
    }
  });

  meal.image = `/images/${fileName}`;
  db.prepare(`
    INSERT INTO meals ...
  `).run(meal);
}

但这不是推荐的做法。为了存储文件，最好还是使用像是 AWS S3 这样的服务。

使用 `useFormStatus` 管理表单提交状态

"use client";

import { useFormStatus } from "react-dom";

export default function MealsFormSubmit() {
  const { pending } = useFormStatus();
  return (
    <button disabled={pending}>
      {pending ? "Submitting..." : "Share Meal"}
    </button>
  );
}

使用 `useFormState` 来接受 Server Action Response

注意这里是 useFormState，与 useFormStatus 区分。它有点像 useState。

它接受两个参数：第一个是实际应当在表单提交时触发的 Server Action；第二个是表单的初始值。
它返回两个参数：第一个是表单初始值，或者 Server Action 的响应；第二个用于和 form 绑定。需要注意 useFormState 仅在客户端组件中可用。

'use client';
import { useFormState } from 'react-dom';

export default function ShareMealPage() {
  const [state, formAction] = useFormState(shareMeal, { message: null });
  return (
    <form action={formAction}>
      <!-- ... -->
      { state.message && <p>{ state.message }</p> }
    </form>
  );
}

我们还需要更改我们的 Server Action shareMeal（添加 prevState 作为第一个参数）：

export async function shareMeal(prevState, formData) {
  // ...
}

生产部署和缓存

运行下面的命令来创建生产环境的部署，并启动生产环境的服务器：

npm run build
npm start

我们会遇到一个问题，即我们新添加的内容并不显示。这是因为 NextJS 默认情况下采取一个非常激进的缓存策略，即在创建生产环境的项目文件时，默认静态生成所有页面以供缓存。为了解决这个问题，我们可以使用 revalidatePath ：

import revalidatePath from "next/cache";
// ...
await saveMeal(meal);
revalidatePath("/meals"); // only that path, no nest path
redirect("/meals");

默认情况下，revalidatePath 仅会对 exact 那个目录生效，这是因为它其实可以接受第二个参数，默认值为 page。如果希望对当前路由及其子路由均生效，可以使用 layout：

revalidatePath("/meals", "layout");

元数据

通过在 Root Layout 中导出 metadata 这一变量，我们已经为整个站点设置了元数据：

export const metadata = {
  title: "NextLevel Food",
  description: "Delicious meals, shared by a food-loving community.",
};

我们也可以为页面单独设置元数据，只需要在对应页面中导出名为 metadata 的变量即可。

对于动态页面，你可能希望添加动态的元数据，可以这样做：

export async function generateMetadata({ params }) {
  // ...
  return {
    title: /* ... */,
    description: /* ... */,
  };
}

BlockLune's Blog

Table of Content

Table of Content

服务端组件

App 路由

动态路由

获取路由的路径

Layout

网站图标

自定义组件

图像

CSS

配置 SQLite 数据库

获取数据

加载

错误

Not Found

Server Action

添加 XSS 保护

保存文件和数据

使用 `useFormStatus` 管理表单提交状态

使用 `useFormState` 来接受 Server Action Response

生产部署和缓存

元数据

Table of Content

NextJS 笔记

Table of Content

服务端组件

App 路由

动态路由

获取路由的路径

Layout

网站图标

自定义组件

图像

CSS

配置 SQLite 数据库

获取数据

加载

错误

Not Found

Server Action

添加 XSS 保护

保存文件和数据

使用 useFormStatus 管理表单提交状态

使用 useFormState 来接受 Server Action Response

生产部署和缓存

元数据

使用 `useFormStatus` 管理表单提交状态

使用 `useFormState` 来接受 Server Action Response