从0死磕全栈之Next.js 自定义 Server 指南：何时使用及如何实现

Next.js 默认自带一个高性能的内置服务器，通过 next start 命令即可启动生产环境服务。但在某些特殊场景下，你可能需要对请求处理流程进行更精细的控制，这时就可以考虑使用 自定义 Server。本文将详细介绍 Next.js 自定义 Server 的使用场景、实现方式、注意事项以及最佳实践。

---

一、什么是自定义 Server？

自定义 Server 是指通过 Node.js 原生 HTTP 模块（或其他框架如 Express、Koa）手动启动一个服务器，并将 Next.js 应用"挂载"到该服务器上，从而实现对请求路径、中间件、代理等更灵活的控制。

⚠️ 重要提示 ：官方文档明确指出，绝大多数情况下你并不需要自定义 Server 。因为这样做会失去 Next.js 的一些关键性能优化，例如：

• 自动静态优化（Automatic Static Optimization）
• 静态资源预渲染（ISR/SSG）的部分能力受限
• 与 Standalone 输出模式不兼容

因此，仅在 Next.js 内置路由系统无法满足需求时才考虑使用。

---

二、适用场景

以下是一些可能需要自定义 Server 的典型场景：

• 需要在 Next.js 应用前添加自定义中间件（如身份验证、日志记录、请求改写）
• 需要将 Next.js 与其他后端服务（如 REST API、WebSocket 服务）集成在同一端口
• 需要对特定路径进行代理或重定向（且无法通过 next.config.js 的 rewrites/redirects 实现）
• 需要完全控制 HTTP 服务器生命周期（如优雅关闭、自定义错误处理）

---

三、实现步骤

1. 创建 server.js 文件

在项目根目录下创建 server.js（或 server.ts，但需注意语法兼容性）：

// server.js
import { createServer } from 'http';
import { parse } from 'url';
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) => {
    const parsedUrl = parse(req.url!, true);
    handle(req, res, parsedUrl);
  }).listen(port);

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

📌 注意：server.js 不会经过 Next.js 的编译或打包流程，因此必须使用当前 Node.js 版本原生支持的语法（如不支持 JSX、TypeScript 等，除非自行编译）。

2. 修改 package.json 脚本

更新启动命令，不再使用 next dev 或 next start，而是直接运行 server.js：

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

💡 提示：开发时仍需先运行 npm run build（除非 dev: true），因为自定义 Server 也需要加载构建产物。

3. （可选）使用 Express 增强功能

如果你需要更强大的路由或中间件能力，可以结合 Express：

// server.js (with Express)
import next from 'next';
import express from 'express';

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(() => {
  const server = express();

  // 自定义中间件
  server.use((req, res, next) => {
    console.log('Request URL:', req.url);
    next();
  });

  // 自定义 API 路由
  server.get('/api/hello', (req, res) => {
    res.json({ message: 'Hello from custom server!' });
  });

  // 将所有其他请求交给 Next.js 处理
  server.all('*', (req, res) => {
    return handle(req, res);
  });

  server.listen(port, (err) => {
    if (err) throw err;
    console.log(`> Ready on http://localhost:${port}`);
  });
});

记得安装依赖：

npm install express

---

四、配置选项说明

next() 函数接受一个配置对象，常用选项如下：

选项	类型	说明
dev	boolean	是否启用开发模式，默认 false
dir	string	Next.js 项目目录，默认 '.'
conf	object	等同于 next.config.js 的配置对象
quiet	boolean	是否隐藏服务器日志，默认 false
hostname / port	string / number	服务器运行的主机和端口（用于内部识别）

示例：

const app = next({
  dev: false,
  dir: './my-next-app',
  conf: { experimental: { appDir: true } }
});

---

五、注意事项与限制

1. 性能损失：自定义 Server 会绕过 Next.js 的自动静态优化，所有页面将被视为 SSR 页面，即使它们可以静态生成。
2. 不支持 Standalone 模式 ：如果你在 next.config.js 中启用了 output: 'standalone'，则无法使用自定义 Server，因为该模式会生成独立的 server.js，与你的自定义逻辑冲突。
3. 部署复杂度增加 ：你需要自行处理进程管理、错误监控、日志收集等，而 next start 已内置这些能力。
4. TypeScript 支持有限 ：server.ts 需要额外配置编译（如使用 ts-node），否则 Node.js 无法直接运行。

---

总结

Next.js 的自定义 Server 是一把"双刃剑"------它提供了极致的灵活性，但代价是牺牲性能与简化部署的优势。除非你有明确且无法通过其他方式解决的需求，否则应避免使用。

当你确实需要它时，请确保：

• 充分测试性能影响

• 明确部署和维护成本

• 保持 server.js 逻辑简洁、兼容当前 Node.js 版本