NNext.js 中文网 GitHub

如何在 Next.js 中设置自定义服务器

使用自定义服务器以编程方式启动 Next.js 应用。

Next.js 默认包含自己的服务器,可通过 next start 启动。如果你已有后端,仍然可以将其与 Next.js 一起使用(这不是自定义服务器)。自定义 Next.js 服务器允许你以编程方式启动服务器以实现自定义模式。大多数情况下,你不需要这种方法。不过,如果你需要“退出”(eject),它也是可用的。

小知识:

  • 在决定使用自定义服务器之前,请记住,只有在 Next.js 的集成路由器无法满足你的应用需求时才应使用它。
  • 使用 standalone 输出模式时,它不会追踪自定义服务器文件。该模式会改为输出一个单独的最小化 server.js 文件。两者不能一起使用。

请查看以下自定义服务器示例:

server.ts
import { createServer } from 'http'
import next from 'next'

const port = parseInt(process.env.PORT || '3000', 10)
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    handle(req, res)
  }).listen(port)

  console.log(
    `> Server listening at http://localhost:${port} as ${
      dev ? 'development' : process.env.NODE_ENV
    }`
  )
})
server.js
import { createServer } from 'http'
import next from 'next'

const port = parseInt(process.env.PORT || '3000', 10)
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    handle(req, res)
  }).listen(port)

  console.log(
    `> Server listening at http://localhost:${port} as ${
      dev ? 'development' : process.env.NODE_ENV
    }`
  )
})

在调用 handle 之前设置你自己的响应头:Next.js 会在 handle(req, res) 内部开始发送响应,因此当它的 promise 解析时,res.headersSent 已经是 true,之后任何 res.setHeader() 调用都会被静默丢弃。在将请求交给 Next.js 之前,先设置你自己的响应头(例如 Set-Cookie):

js
res.setHeader('Set-Cookie', 'sessionId=abc123; Max-Age=2592000')

await handle(req, res)

将 Next.js 包装在另一个框架中时,同样的顺序也适用,例如 Fastify 中的 reply.raw 或 Express 中的 res。

server.js 不经过 Next.js 编译器或打包过程。请确保此文件所需的语法和源代码与你当前使用的 Node.js 版本兼容。查看示例。

要运行自定义服务器,你需要像这样更新 package.json 中的 scripts:

package.json
{
  "scripts": {
    "dev": "node server.js",
    "build": "next build",
    "start": "NODE_ENV=production node server.js"
  }
}

或者,你可以设置 nodemon(示例)。自定义服务器使用以下 import 将服务器与 Next.js 应用程序连接起来:

js
import next from 'next'

const app = next({})

上面的 next import 是一个函数,它接收一个包含以下选项的对象:

选项类型描述
confObject与你在 next.config.js 中使用的对象相同。默认为 {}
devBoolean(可选)是否在开发模式下启动 Next.js。默认为 false
dirString(可选)Next.js 项目的位置。默认为 '.'
quietBoolean(可选)隐藏包含服务器信息的错误消息。默认为 false
hostnameString(可选)服务器运行所在的主机名
portNumber(可选)服务器运行所在的端口
httpServernode:http#Server(可选)Next.js 运行所依赖的 HTTP 服务器
turbopackBoolean(可选)启用 Turbopack(默认启用)
webpackBoolean(可选)启用 webpack

然后可以使用返回的 app 让 Next.js 按需处理请求。

禁用文件系统路由#

默认情况下,Next 会为 pages 文件夹中的每个文件提供与文件名匹配的路径名。如果你的项目使用自定义服务器,这种行为可能导致相同内容从多个路径提供,这会给 SEO 和 UX 带来问题。

要禁用此行为并阻止基于 pages 中文件的路由,请打开 next.config.js 并禁用 useFileSystemPublicRoutes 配置:

next.config.js
module.exports = {
  useFileSystemPublicRoutes: false,
}

请注意,useFileSystemPublicRoutes 会禁用来自 SSR 的文件名路由;客户端路由仍可能访问这些路径。使用此选项时,你应该防止以编程方式导航到你不想访问的路由。

你可能还希望配置客户端路由器以禁止客户端重定向到文件名路由;为此请参阅 router.beforePopState。

Next.js 中文网