Next.js 自定义服务器实战:TypeScript + Nodemon 开发自定义 Server 的完整指南

原创2026-09-06 17:00:501,696 阅读
文章标签:前端Web框架SSR路由前端构建后端

Next.js 自定义服务器实战:TypeScript + Nodemon 开发自定义 Server 的完整指南

本篇基于 Next.js 官方示例 custom-server 展开,讲解如何在 Next.js 项目中用 TypeScript 同时编写服务端与客户端代码,并通过 Nodemon 实现服务器代码的热重载。读完本文,你将掌握 next() 包装 API 的核心用法(getRequestHandler、prepare)、服务端独立的 tsconfig 编译策略,以及开发态(server.ts)与生产态(dist/server.js)两种入口的切换机制,能够把 Next.js 嵌入到任意自定义 Node.js 服务中。

一、自定义服务器能解决什么问题

Next.js 默认提供自己的 Node.js 服务进程(next dev / next start)。但在真实工程中,经常需要接管 HTTP 服务层:接入已有的网关或监听逻辑、在服务端做统一鉴权/日志/中间件、复用公司内部的服务框架。自定义服务器(custom server)就是让开发者自己创建 HTTP 服务,再把请求"委托"给 Next.js 去渲染。

官方示例 examples/custom-server 的定位(见 README):在服务器端和客户端同时使用 TypeScript,并用 Nodemon 实现服务器代码的实时热重载,同时不影响 Next.js 自身的 universal 代码热更新。

两个关键结论先摆出来:

  • 开发态入口是 server.ts,生产态入口是 dist/server.js;
  • 编译产物目录 dist 应加入 .gitignore。

二、用 create-next-app 脚手架启动示例

仓库 README 给出了三种包管理器的引导命令,任选其一:

npx create-next-app --example custom-server custom-server-app
yarn create next-app --example custom-server custom-server-app
pnpm create next-app --example custom-server custom-server-app

执行后会在 custom-server-app 目录下生成完整示例项目,结构如下(对应仓库中的目录):

examples/custom-server/
├── app/                  # App Router 路由
│   ├── layout.tsx        # 根布局
│   └── b/page.tsx        # /b 页面
├── pages/                # Pages Router 路由
│   ├── index.tsx         # 首页,含导航链接
│   └── a.tsx             # /a 页面
├── server.ts             # 开发态服务器入口
├── nodemon.json          # Nodemon 配置
├── tsconfig.json         # 客户端 + 通用 TS 配置
├── tsconfig.server.json  # 服务端专属 TS 配置
└── package.json

值得注意的是,这个示例同时保留了 app/ 与 pages/ 两套路由目录。首页 pages/index.tsx 中用 next/link 同时链接到 Pages Router 的 /a 和 App Router 的 /b:

import Link from "next/link";

export default function Home() {
  return (
    <ul>
      <li>
        <Link href="/a">/a (Pages Router)</Link>
      </li>
      <li>
        <Link href="/b">b (App Router)</Link>
      </li>
    </ul>
  );
}

这验证了自定义服务器对两种路由体系是透明且通用的——无论页面来自哪套路由,最终都由同一个 handle(req, res) 处理。

三、server.ts:自定义服务器的核心代码逐行解析

整个示例的服务端逻辑全部集中在 server.ts,共 19 行:

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
    }`,
  );
});

逐步拆解:

  1. const dev = process.env.NODE_ENV !== "production":以 NODE_ENV 判断当前是开发还是生产模式,这是 Next.js 自定义服务器的惯例判据。
  2. const app = next({ dev }):调用 next 默认导出创建一个 Next.js 应用包装实例。这个实例是连接自定义 HTTP 服务与 Next.js 渲染引擎的桥。
  3. const handle = app.getRequestHandler():拿到 Next.js 的请求处理函数。任何进入该函数的 req/res 都会按 Next.js 的路由规则被渲染(页面、静态资源、API 等),对开发者完全透明。
  4. app.prepare().then(() => { ... }):prepare 是启动前置钩子,用于完成 Next.js 内部的初始化(加载配置、构建信息等)。必须等 prepare 完成后再开始监听,否则首个请求会因内部状态未就绪而出错。
  5. createServer((req, res) => { handle(req, res); }):用 Node 内置 http 模块创建服务器,把每个请求原样转交给 handle。
  6. 端口:从 process.env.PORT 读取,缺省 3000,便于部署平台注入端口。

这段代码的最小骨架可以总结为三行:next({ dev }) → app.prepare() → handle(req, res)。

从源码看 getRequestHandler 的官方地位

在 Next.js 源码 packages/next/src/server/next.ts 中,NextWrapperServer 接口明确注释了“这里的成员是自定义服务器的公开 API,改动时需要考虑向后兼容”:

interface NextWrapperServer {
  // NOTE: the methods/properties here are the public API for custom servers.
  // Consider backwards compatibilty when changing something here!

  options: NextServerOptions
  ...
  getRequestHandler(): RequestHandler
  prepare(serverFields?: ServerFields): Promise<void>
  close(): Promise<void>
  ...
}

同一文件中还定义了一个 warnDeprecatedCustomServerMethod 机制(next.ts#L108-L114):像 render、renderToHTML、renderError、logError、revalidate 等旧式方法在自定义服务器场景下已被标记废弃,调用时会输出一次性警告,统一引导开发者使用"app.getRequestHandler() + 自行调整 parsed URL"的方式。也就是说,示例中"只暴露一个 handle 函数"的写法正是官方推荐的现代姿势——不要依赖那些细粒度的 render 方法。

四、TypeScript 双配置:客户端与服务端各管一摊

示例中最有工程价值的设计是两套 tsconfig 分工,这解决了"浏览器代码与 Node 服务器代码模块格式不同"的矛盾。

客户端配置 tsconfig.json

tsconfig.json 负责页面、组件等会被 Next.js 编译的代码:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": false,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "strictNullChecks": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

要点:

  • noEmit: true:类型检查交给 Next.js 的构建流水线(SWC),tsc 只做类型校验,不产出文件;
  • "plugins": [{ "name": "next" }]:启用 Next.js 的 TS 语言服务插件,提供路由类型检查等能力;
  • lib 包含 dom,因为客户端代码需要浏览器 API 类型。

服务端配置 tsconfig.server.json

tsconfig.server.json 只编译服务器入口:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "dist",
    "lib": ["es2019"],
    "target": "es2019",
    "isolatedModules": false,
    "noEmit": false
  },
  "include": ["server.ts"]
}

四个关键覆盖项:

  • module: "commonjs":Node.js 服务端直接 node dist/server.js 运行,CommonJS 最稳妥,无需处理 ESM 加载问题;
  • noEmit: false + outDir: "dist":真正产出编译文件到 dist;
  • target / lib 提升到 es2019:服务端运行在现代 Node 上,不必像浏览器那样回落到 es5;
  • include: ["server.ts"]:严格限定只编译服务器文件,避免把页面组件也打进 dist。

这种"一个配置管类型、一个配置管编译"的拆分,正是 README 标题 TypeScript + Nodemon 中"服务端 TypeScript"落地的方式。

五、Nodemon:让服务器代码支持热重载

开发态下,next dev 本身会热更新 Next.js 的页面代码,但自定义的 server.ts(属于纯 Node 代码)不在其热更新范围内。示例用 Nodemon 补上这块:nodemon.json

{
  "watch": ["server.ts"],
  "exec": "ts-node --project tsconfig.server.json server.ts",
  "ext": "js ts"
}
  • watch: ["server.ts"]:只监听服务器入口文件,避免页面文件变化触发不必要的重启;
  • exec:检测到变化时重新执行 ts-node --project tsconfig.server.json server.ts——用 ts-node 直接运行 TS 源码(省去开发态编译一步),并显式指定服务端 tsconfig 以保证 commonjs 模块格式正确;
  • ext: "js ts":将 .js 与 .ts 扩展名都纳入重载判断。

由此形成开发态的双层热更新:

变更对象 负责热更新的机制
页面/组件(pages/、app/) Next.js 自身的开发时 HMR
服务器入口 server.ts Nodemon 重启进程

这正是 README 所说"live reload the server code without affecting the Next.js universal code"的含义。

六、package.json 中的三个脚本

package.json 定义了完整的开发/构建/启动链路:

{
  "scripts": {
    "dev": "nodemon",
    "build": "next build && tsc --project tsconfig.server.json",
    "start": "cross-env NODE_ENV=production node dist/server.js"
  }
}
  • dev:启动 Nodemon,读取上面的 nodemon.json,即运行 ts-node 加载 server.ts。开发时执行 npm run dev;
  • build:两步串行——先 next build 产出 .next 中的页面与资源,再用 tsc --project tsconfig.server.json 把 server.ts 编译成 dist/server.js;
  • start:用 cross-env 跨平台设置 NODE_ENV=production 后运行编译产物。cross-env 作为依赖(^7.0.3)解决了 Windows 下无法直接用 NODE_ENV=... 内联环境变量赋值的问题。

依赖方面:运行时依赖仅 next、react、react-dom、cross-env 四个;nodemon、ts-node、typescript、@types/* 全部位于 devDependencies——这与"开发态跑 server.ts 源码、生产态跑编译产物"的设计完全吻合:生产环境不再需要 TypeScript 工具链。

七、生产部署注意事项

结合 README 与示例代码,部署自定义服务器版 Next.js 应用时有几条硬性约束:

  1. 入口切换:生产环境运行的是 node dist/server.js(start 脚本),而不是 server.ts。dev 与 start 两条链路必须与 build 的产物严格对应;
  2. dist 目录忽略:README 明确要求将 dist 加入 .gitignore,编译产物不入库;
  3. NODE_ENV 语义:server.ts 中 dev = process.env.NODE_ENV !== "production",因此任何非 production 的 NODE_ENV(如 test)都会进入开发模式分支,启动日志也会显示对应的环境名。这一点在 start 脚本中通过 cross-env NODE_ENV=production 保证了正确性;
  4. prepare 前置:无论怎样扩展自定义逻辑(鉴权中间件、额外路由),都要保证它们注册在 app.prepare().then(...) 回调内,确保 Next.js 初始化完成;
  5. 避免使用废弃的细粒度方法:如前文源码所示,app.render 等方法已被废弃并输出警告,新代码应始终只使用 getRequestHandler(),如需拦截/改写请求,应在传给 handle 之前调整 req 或 parsed URL。

八、小结:这个示例的工程价值

examples/custom-server 虽只有十余行服务端代码,但它把三件容易踩坑的事给出了官方参考答案:

  • API 面:自定义服务器只需 next({ dev })、prepare、getRequestHandler 三个接触点,源码(next.ts)中它被明确标注为面向自定义服务器的公开 API;
  • 类型工程:用 tsconfig.json(noEmit,管类型)+ tsconfig.server.json(commonjs + outDir,管编译)双配置,隔离浏览器与 Node 的模块差异;
  • 开发体验:Nodemon + ts-node 只监听 server.ts,让自定义服务代码获得与 Next.js 页面同等的热重载体验。

当你需要把 Next.js 嵌入自研服务、加统一网关逻辑或复用现有 Node.js 基础设施时,直接以 examples/custom-server 为模板起步即可:create-next-app --example custom-server 拉取骨架,按上文三节改配置、按 README 约定管理 dist 产物。

登录后查看全文
next.js