Nextjs的实践 - 豆米的博客

1、背景

原有的博客网站采用malagu前后端一体化框架，前端静态文件部署在CDN上，服务端部署在ECS上，所有的请求都是走的jsonRPC的方式，这导致了整体的博客内容无法SEO，并且首屏加载时间很慢，得先请求到前端静态资源之后才可以请求接口，因此本次重构就是为了解决上述的问题。其实博客网站的整体重构，算上这次，已经两次了，最开始的版本是Sailjs + Jquery，之后Malagu + React，到如今的Nextjs。

整体代码开源：https://github.com/linxiaowu66/doumi-nextjs

2、开始开发

首先我们按照官网给的初始化方式，初始化一下整体的代码结构（我们使用官方推荐的APP Router）：

npx create-next-app@latest

PS：关于新版Next.js的APP Router和Page Router的区别，看下面的表格：

Feature	App Router	Pages Router
Routing type	Server-centric	Client-side
Support for Server Components	Yes	No
Complexity	More complex	Simpler
Performance	Better	Worse
Flexibility	More flexible	Less flexible
初始化完成之后，开始将旧版的代码迁移到Next.js上，组件库我们继续使用@mui，升级到最新版本。

2.1、开始迁移

目录结构如下：（为了展示，有所删除）

1.
2├── app
3│   ├── about
4│   │   ├── blog  ->  /about/blog 路由
5│   │   │   ├── Timeline // 私域内的组件，不会形成路由，下同
6│   │   │   └── page.tsx // 主渲染文件，名字一定得是page,下同
7│   ├── api
8│   │   ├── archive
9│   │   │   └── list -> /api/archive/{method}，api路由
10│   │   │       └── route.ts // api接口处理文件，名字一定得是route
11│   │   ├── auth
12│   │   │   ├── [...nextauth] -> /api/auth/[...nextauth]，捕获/api/auth/x/xx 后面的所有路由
13│   │   │   │   └── route.ts
14│   ├── auth
15│   │   └── [type] -> /auth/:type，捕获/auth/login(register)的路由
16│   │       └── page.tsx
17│   ├── layout.tsx // 主应用的布局文件，后续会拆分两个
18│   ├── page.tsx // 主应用入口
19│   └── providers.tsx
20├── database // 数据库的定义以及实例初始化
21│   ├── entities
22│   └── index.ts
23├── features // 存放所有公共的业务组件
24│   ├── BlogConfig
25├── logger // 服务端日志服务
26│   └── index.ts
27├── middleware.ts // 服务端中间件，用来中间鉴权
28├── service // 服务端原子服务
29├── theme.ts // 主题定义
30

上述的目录结构涉及到Next.js的路由定义的部分知识，这里讲解一下：

2.1.1、Pages和Layouts

每一个UI页面的路由下面都可以创建layout.js、page.js、template.js三个文件来形成我们想要表达的UI界面；因为支持嵌套Layout，所以如果声明多个，渲染的结果会是这样：

至于template.js文件，比较特殊（此次实践没有用到该能力），按照官网的解释：

与Layout持续跨路由和保存状态不同，template为导航上的每个子级创建一个新实例。这意味着当用户在共享模板的路由之间导航时，一个新实例组件将被挂载，DOM 元素将重新创建，不保留状态，并且重新同步效果。 在某些情况下，您可能需要这些特定行为，而模板将是比布局更合适的选择。例如： 依赖于 useEffect （例如记录页面视图）和 useState （例如每页反馈表）的功能。 更改默认框架行为。例如，布局内的 Suspense Boundaries 仅在第一次加载布局时显示回退，而不是在切换页面时显示回退。对于模板，回退可以显示在每次路由切换上。

官网提到的局部加载以及流式传输，这次的博客也暂时没机会用到；

2.1.2、动态路由

上述路由的/auth/:type用的就是动态路由，比如/auth/login就能够匹配上该路由，并且可以从page.tsx文件中获取对应的参数：

1import { useParams, usePathname } from "next/navigation";
2
3// 使用Hook,这个只能在前端使用
4const params = useParams<{ type: "login" | "register" }>();
5// 获取path
6const pathname = usePathname();
7
8// 或者直接在props里面传进来，这个在后端使用
9export default function Page({ params }: { params: { slug: string } }) { 
10	return <div>My Post: {params.slug}</div>
11}

还有另外一种是直接捕获命中前缀之后的所有路由格式：/api/auth/[...nextauth]，这个路由就可以捕获所有带有前缀/api/auth的路由，比如：/api/auth/callback/credentials、/api/auth/session，如果把中括号改成两个中括号[[...nextauth]]，那么这个匹配就是可选的，可以匹配上/api/auth这样的路由

2.1.3、平行路由

平行路由允许在同一个layout之下同时或者条件渲染一个或者更多的页面。类似于vue的slot理念，在某些条件下使用插槽A，某些条件下使用插槽B。如下图，文件命名是使用@folder的格式，目前的博客貌似可以改成这样的结构

2.1.4、拦截路由

拦截路由的意思就是可以做到不跳转页面的情况下，也能够查看别的页面。Nextjs通过提供诸如(.)这种关键词，来帮助你匹配找到你想跳转的路由界面，这个功能一般都是和上面的平行路由一起使用，官方提供了一个例子：nextgram，一看就能明白是做了个啥

2.1.5、路由处理

除了使用默认的page.js来处理界面渲染，我们还可以使用Request和Response的API自定义创建一些处理函数，也就是api请求，上述结构中的 /api/archive/{method}就是这样的例子。

在使用route的过程中，我们遇到一些问题的解决，收集在这里：

• 解析query参数，可以使用：req.nextUrl.searchParams.get("slug")
• 获取登录用户的session，可以使用：getServerSession(authOptions);

2.2、迁移后的写法改变

Nextjs区分服务端组件和客户端组件，默认都是服务端组件，并且支持服务端组件里面嵌入客户端组件，因此在代码编写的时候就需要格外注意，哪些组件是服务端组件，哪些是客户端组件。

举个🌰，博客首页有个热门文章：

我们SSR肯定想着可以进行后端直接获取数据后渲染进去的，于是我们就写成这样：

1export default async function Home() {
2  // 这里直接调用后端服务获取最热门的文章
3  const res = await queryArticles(1, 5, JSON.stringify({ pv: "DESC" }));
4
5  return (
6    <Container maxWidth="md" className={styles.homeContainer}>
7      <DouMiIntroduction avatarSize={120} fontSize={16} />
8      <DoumiLinks />
9      <HottestArticles list={res.list} />
10      <FootPrint />
11    </Container>
12  );
13}

这样在获取首页的时候就可以看到，页面已经是同构直出了：

但是并不是所有的页面都是可以这样做的，只要涉及到状态报错的、人机交互的、事件监听的，你都必须加上use client这个声明，以表示该组件是客户度渲染的组件。

但是一个页面是可以做到服务端组件与客户端组件共同交错使用的，比如博客列表页面，它是一个分页的页面，存在人机交互行为，但是我们又想在首次加载的时候，第一页数据可以直接从服务端直出的，于是我们在写的时候就会这样：

1const BlogList = async () => {
2  // ...省略一些代码
3  // 后端直接获取前6篇文章，作为初始化参数给BlogPagination组件
4  const result = await queryArticles(
5    1,
6    6,
7    null,
8    queryTag,
9    queryArch,
10    queryCat,
11    "published"
12  );
13
14  return (
15    <BlogContainer contentClass={styles.blogListWrapper}>
16      <BlogPagination
17        initialPosts={result}
18        queryArch={queryArch}
19        queryCat={queryCat}
20        queryTag={queryTag}
21      />
22    </BlogContainer>
23  );
24};

之后BlogPagination组件初始化的时候接收这个初始化列表：

1"use client";
2import { DouMiBlog } from "@/interface";
3import { Pagination } from "@mui/material";
4import { useState } from "react";
5import BlogItem from "../BlogItem";
6import axios from "axios";
7import styles from "./index.module.css";
8
9export default function BlogPagination({
10  initialPosts,
11  queryArch,
12  queryCat,
13  queryTag,
14}: {
15  initialPosts: {
16    list: DouMiBlog.ArticleBrief[];
17    currentPage: number;
18    pageCount: number;
19  };
20  isLogin?: boolean;
21  queryArch?: string | null;
22  queryCat?: string | null;
23  queryTag?: string | null;
24}) {
25  const [blogList, setBlogList] = useState<DouMiBlog.ArticleBrief[]>(
26    initialPosts.list
27  );
28  const [pageCount, setPageCount] = useState(initialPosts.pageCount);
29  const [currentPage, setCurrentPage] = useState(initialPosts.currentPage);
30
31  // ... 省略一些代码
32}
33

最后当访问列表页面的时候，就可以看到我们第一页的数据其实已经跟着html渲染回来了，减少了一次请求，整体页面也做到了秒出；

2.3、集成数据库

原先的博客使用的typeorm+mysql，为了不再折腾，继续复用这个组合；那么摆在我们目前的一个问题是，正常nodejs服务器启动的时候，是需要创建连接实例化的，但是nextjs没有提供这样的入口给我们呀？怎么办？

于是我们取巧，借助nodejs中关于模块的加载原理，在database文件夹中创建index.ts文件，将实例化缓存在该文件：

1const AppDataSource = new DataSource({
2  type: "mysql",
3  host: process.env.DB_HOST,
4  port: 3306,
5  username: process.env.DB_USER, // 替换成你自己的用户名
6  password: process.env.DB_PASS, // 替换成你自己的密码
7  database: "douMiBlog",
8  synchronize: false,
9  logging: false,
10  entities: [Archive, Article, Category, Reader, Tag, User, Website],
11  subscribers: [],
12  migrations: [],
13});
14
15export const getDataSource = (delay = 3000): Promise<DataSource> => {
16  if (AppDataSource.isInitialized) return Promise.resolve(AppDataSource);
17
18  return new Promise((resolve, reject) => {
19    setTimeout(() => {
20      if (AppDataSource.isInitialized) resolve(AppDataSource);
21      else reject("Failed to create connection with database");
22    }, delay);
23  });
24};

一开始我是直接export AppDataSource出去给应用方使用的，但每次重启服务器后第一次使用都会报：EntityMetadataNotFoundError的错误，很明显，当应用要使用的时候，该实例其实还没初试完的，因此加上getDataSource保证实例是可用的。

之后，在所有地方就可以正常这么使用了：

1const AppDataSource = await getDataSource();
2const repo = AppDataSource.getRepository(Archive);
3
4const result = await repo.find({ relations: ["articles"] });

一开始使用mysql，会报错Client does not support authentication protocol requested by server; consider upgrading MySQL client，发现mysql包好几年没更新了，有个新的适配包mysql2，更新一下，问题解决~~

2.4、集成next-auth

数据对接ok之后，开始接入认证模块，我们使用了NextAuth.js。按照官方文档正常接入即可，没遇到太多问题，期间会用到中间件的能力，刚好介绍一下中间件吧。

2.4.1、中间件

Nextjs的中间件运行在缓存内容和路由匹配之前，可以基于入口的请求，对响应进行重写，重定向，修改请求或者响应的头部信息，比如我就在中间件里埋了个x-url的数据，记录请求的url：

1  const requestHeaders = new Headers(req.headers);
2  requestHeaders.set("x-url", req.url);

之后在渲染文件中可以这样直接取出header里面的参数：

1import { headers } from "next/headers";
2
3...
4const heads = headers();
5const url = heads.get("x-url");

我们还可以api请求的结果进行整体包装，而不需要每个api请求都返回一样的数据结构，比如：

中间件还允许针对某些api才启用，可以在middleware.ts文件中增加：

1export const config = { matcher: '/api/:function*',}

PS：目前中间件最不好的地方就是不支持Nodejs运行时，而只能用在边缘计算运行时，什么意思呢？就是Nodejs的一些模块，比如fs、path等模块都是在中间件文件里面不能够直接require的。

2.4.2、NextAuth.js

我们使用jwt的方式来做鉴权校验，nextAuth直接使用一个配置生成一个通用的handler来处理所有/api/auth的请求：

1// 有删减，完整的参考博客源码
2export const authOptions: NextAuthOptions = {
3  session: {
4    strategy: "jwt",
5    maxAge: 24 * 60 * 60, // 24 hours
6  },
7  // 必须加这个，否则会报错：'JWEDecryptionFailed: decryption operation failed\n'
8  secret: process.env.NEXTAUTH_SECRET,
9  callbacks: {
10    // session会把下面的user信息塞到/api/auth/session里面，前端就会拿到用户信息，后端使用getServerSession拿到的session数据也是{id, email}，尝试追加更多信息，做不到！
11    session: async ({ session, token }) => {
12      session.user.id = token.uid as number;
13      session.user.email = token.email as string;
14      return session;
15    },
16    jwt: async ({ user, token }) => {
17      if (user) {
18        token.uid = user.id;
19        token.email = user.email;
20        // TODO: 如何加入用户名字？
21      }
22      return token;
23    },
24  },
25  providers: [
26    CredentialsProvider({
27      credentials: {
28        email: { label: "Email", type: "email" },
29        password: { label: "Password", type: "password" },
30      },
31      // /api/auth/login会进入这里的函数
32      async authorize(credentials): Promise<any> {
33        const { email, password } = credentials ?? {};
34        if (!email || !password) {
35          throw new Error("邮箱或者密码必填，请重新输入");
36        }
37        const AppDataSource = await getDataSource();
38        const user = await AppDataSource.getRepository(User).findOne({
39          where: {
40            email,
41          },
42        });
43        // if user doesn't exist or password doesn't match
44        if (!user || !(await compare(password, user.password))) {
45          throw new Error("邮箱或者密码不正确，请重新输入");
46        }
47        return user;
48      },
49    }),
50  ],
51};
52
53const handler = NextAuth(authOptions);
54
55// 拦截GET/POST请求，统一都是handler函数通吃
56export { handler as GET, handler as POST };

在前端使用const res = await signIn("credentials", { ...data, redirect: false });的方式进行登录请求，里面的redirect参数是表示如果登录失败了，也不要重定向。

目前这里还有一点问题是，如果失败了，NextAuth直接throw Error，返回非我们规定的数据结构，而是这样的一串：

1http://localhost:3000/api/auth/error?error=邮箱或者密码不正确，请重新输入

这样导致前端都无法规范化处理，后续看看怎么解决？

2.5、集成winston

数据和权限集成ok之后，就离部署不远了，这个时候我们需要加下服务端日志，以打印一些重要的节点。

在src/logger下新建主文件，引入winston和winston-daily-rotate-file，按照正常的配置即可；之后导出logger实例，在任意文件(Server Component)使用即可；

1import { logger } from "@/logger";
2
3logger.info(
4    `search blog list with query condition: ${JSON.stringify(finalQuery)}`
5  );

2.6、部署前的准备

快要开发完了，需要设置一些环境变量，Nextjs的环境有点意思，容易让人混淆，这里需要特意提一下。

Nextjs默认使用.env.local环境变量，因此只要有.env.local存在的话，你其他环境定义的环境变量都会被其覆盖；但是如果有些公共配置，可以放在.env下面，因此整体体验下来，最好的配置应该是：

1.env // 公共配置
2.env.development // 开发环境配置
3.env.production // 线上配置

3、线上编译遇到的问题

开发完成了，准备部署，部署之前需要编译，编译的时候就发现报错了：

3.1、TypeORM又报错了

1initialization TypeORMError: Entity metadata for r#articles was not found. Check if you specified a correct entity object and if it's connected in the connection options.
2

从错误提示发现，代码被混淆了，导致Typeorm的Entity找不到了。Nextjs看样子是对所有的代码进行预编译和预执行了，这个错误全网搜了好久，终于发现有个配置解决：

在next.config.mjs文件中增加如下配置，让代码不要进行压缩混淆即可：

1experimental: {
2    serverComponentsExternalPackages: ["typeorm"],
3    serverMinification: false, // 不能压缩，一压缩在生产环境下就会报 xx#Aritcles metadata not found，本质原因就是代码被混淆压缩了导致的
4  },

3.2、预渲染页面报错

所有的api预渲染都报错了如下的错误：

1Error occurred prerendering page "/api/archive/list". Read more: https://nextjs.org/docs/messages/prerender-error
2

想了一下api的接口没必要预渲染呀，那为啥会进行预渲染？预渲染应该只只对静态的页面的，于是又阅读了官网文章，发现# Route Segment Config有提及到允许开发者配置Page、Layout、Route Handler的行为。也就是可以对其进行强制动态或者强制静态的配置。因此我们在所有绝对动态的api请求中全部加入：force-dynamic：

export const dynamic = "force-dynamic";

其表达的意义是：强制动态渲染，每个用户在每次请求的时候重新渲染，不使用任何缓存，不使用任何# Revalidating的能力；

4、继续探索

Nextjs还有很多高阶的能力目前没有体验到，包括：

• 错误处理
• 流式传输
• 缓存（使用fetch）
  • 缓存数据避免每次请求的时候都要重新请求一次
  • 重新校验数据，为了每次能够获取最新的数据
  • 不使用fetch的话，也可以使用cache，这块可以进行针对性优化
• Server Actions
• 优化，比如图片、字体等
• 平行路由+拦截路由+路由组(就是将一些共同的路由放在一起，共享一些比如layout之类的，有点类似于通过目录聚合，但是该目录名称不会作为路由解释)
• Layout嵌套+template能力

后续会持续对博客进行相关优化，优化的记录也会产出对应的文章；敬请期待~