Next.js 自定义服务器实战:TypeScript + Nodemon 开发自定义 Server 的完整指南
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
}`,
);
});
逐步拆解:
const dev = process.env.NODE_ENV !== "production":以NODE_ENV判断当前是开发还是生产模式,这是 Next.js 自定义服务器的惯例判据。const app = next({ dev }):调用next默认导出创建一个 Next.js 应用包装实例。这个实例是连接自定义 HTTP 服务与 Next.js 渲染引擎的桥。const handle = app.getRequestHandler():拿到 Next.js 的请求处理函数。任何进入该函数的req/res都会按 Next.js 的路由规则被渲染(页面、静态资源、API 等),对开发者完全透明。app.prepare().then(() => { ... }):prepare是启动前置钩子,用于完成 Next.js 内部的初始化(加载配置、构建信息等)。必须等prepare完成后再开始监听,否则首个请求会因内部状态未就绪而出错。createServer((req, res) => { handle(req, res); }):用 Node 内置http模块创建服务器,把每个请求原样转交给handle。- 端口:从
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 应用时有几条硬性约束:
- 入口切换:生产环境运行的是
node dist/server.js(start脚本),而不是server.ts。dev与start两条链路必须与build的产物严格对应; dist目录忽略:README 明确要求将dist加入.gitignore,编译产物不入库;NODE_ENV语义:server.ts中dev = process.env.NODE_ENV !== "production",因此任何非production的NODE_ENV(如test)都会进入开发模式分支,启动日志也会显示对应的环境名。这一点在start脚本中通过cross-env NODE_ENV=production保证了正确性;prepare前置:无论怎样扩展自定义逻辑(鉴权中间件、额外路由),都要保证它们注册在app.prepare().then(...)回调内,确保 Next.js 初始化完成;- 避免使用废弃的细粒度方法:如前文源码所示,
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 产物。