Next.js 应用开发实践：用 next-connect 补上中间件和错误处理

Randy Lu（GitHub djyde）写过一本很薄的中文小书《Next.js 应用开发实践》，专门补官方文档里不太讲的那几块：API 中间件、统一错误处理、Cookie、Prisma，以及用 React Query 管前端请求。配套示例在 fullstack-nextjs-in-action-example。书是 Pages Router 时期写的，现在 App Router 已经自带 Route Handler 和 Cookie API，但把鉴权、日志、错误处理抽成一层这件事没变。下面按现在的写法走一遍。

书里在补什么

早期 Next.js 的 pages/api 不像 Express / Koa：没有中间件链，throw 出去只剩一个空的 500，写登录时连 Set-Cookie 都要自己拼。小书的做法是三件套：

next-connect：给 API 接上 connect 风格中间件，顺带按 HTTP 方法分流
Prisma：Schema 加 Migrate，在 Next 里访问数据库
TanStack Query（当年叫 react-query）：Query、Mutation、Invalidation，别把请求散落在组件里

后面两个实例是用户系统（注册、登录、JWT、Cookie）和简易 Hacker News（提交、列表、编辑、删除）。库的 API 去官方文档看，书只讲怎么拼进 Next。

在线阅读：https://nextjs-in-action-cn.taonan.lu/

作者 GitHub：https://github.com/djyde

示例仓库：https://github.com/djyde/fullstack-nextjs-in-action-example

next-connect 仓库：https://github.com/hoangvvo/next-connect

先装 next-connect

现在不要抄书里的默认导出 nc。v1 起入口改成 createRouter（Pages / Node API）和 createEdgeRouter（Edge / App Router）。包名仍是 next-connect，装 next 标签那一档。

在 pages/api 里：用 createRouter 建实例，use 挂中间件，get / post 写各方法，最后把 router.handler 的 onError、onNoMatch 导出去。onError 把 throw 收成带状态码的 JSON，onNoMatch 处理不支持的方法。

中间件里一定要等待 next 完成。漏掉的话，后面的异步 handler 抛错会变成未处理的 Promise，统一 onError 也接不住。

多个 API 文件不要共享同一个 router 实例再分别挂方法，会互相污染。需要公共中间件时用 clone。完整示例见 next-connect 仓库 README。

App Router 里怎么接

App Router 的 Route Handler 已经按 HTTP 方法拆文件，Cookie 也不用自己拼头了。还想复用中间件链，就用 createEdgeRouter，在 route 文件里对 GET / PUT 调用 run。动态参数在较新的 Next 里是 Promise，要先 await 再取 id。

很多场景其实不必上 next-connect。鉴权、跳转、改头这类「请求进页面之前」的逻辑，Next.js 16 把原来的 middleware 文件改名叫 proxy。官方文档：

next-connect 更适合你还想在同一条链上挂 cors、日志、鉴权，并且 Pages 和 App 两套路由还要共存的时候。

Cookie 和登录

书里花了不少篇幅讲登录后往客户端写 Cookie。现在 App Router 直接用 next/headers 里的 cookies：读 get，写 set，退出 delete。设置时记得 httpOnly、sameSite、生产环境 secure、合理的 maxAge 和 path。

JWT 实现可以继续用 node-jsonwebtoken，Edge / Proxy 场景更常见的是 jose。密钥只放环境变量，不要写进客户端。书里的登录、创建账号、用户信息、退出登录这几步，换成这套 Cookie API 就能在 App Router 里复现。

Prisma 在 Next 里的坑

书里用 Prisma 做模型和 migration，这套现在仍然成立：schema 里定义模型，migrate 出迁移。Next 开发模式会热重载，每次新建 PrismaClient 容易把数据库连接打满。做法是把实例挂到 globalThis 上复用，生产环境每个进程一个实例即可。Route Handler 和 Server Component 都 import 同一个单例。Prisma 文档：https://www.prisma.io/docs

前端请求

小书选 react-query，不选满屏零散请求。现在包名是 @tanstack/react-query。列表用 useQuery，提交用 useMutation，成功后 invalidateQueries 让列表自己刷新。这和书里的 Query / Mutation / Invalidation 三步是同一件事。文档：https://tanstack.com/query/latest/docs/framework/react/overview

怎么跟这本书练

打开 https://nextjs-in-action-cn.taonan.lu/ ，先读「缺失的技术」再跟两个实例
对照仓库 https://github.com/djyde/fullstack-nextjs-in-action-example
新项目优先 App Router：Cookie 用 cookies 助手，请求前逻辑用 proxy，API 中间件需要时再接 next-connect
数据层按 Prisma 走，前端请求按 TanStack Query 走

作者博客：https://lutaonan.com 。Cusdis 是他用这套栈做过的产品之一。