如何在NextJS服务启动时添加钩子以执行一次性初始化操作

Next.js 目前没有官方稳定的启动钩子API，可通过以下几种方式实现启动时执行一次性初始化操作： #

方案1：自定义启动入口（全场景通用、最稳定） #

该方案适用于所有Next.js版本和路由模式，初始化完成后才会启动服务接收请求，不会出现初始化未完成就处理业务请求的问题。

• 第一步：在项目根目录新建server.js文件，内容如下：

const next = require('next')
const http = require('http')
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

// 自定义一次性初始化逻辑
async function runOnceInit() {
  // 示例：数据库连接、全局配置加载、缓存预热等操作
  console.log('执行服务启动一次性初始化...')
  // await connectDatabase()
  // await loadGlobalConfig()
}

app.prepare().then(async () => {
  // 先执行初始化，完成后再启动服务
  await runOnceInit()
  const server = http.createServer((req, res) => {
    handle(req, res)
  })
  server.listen(3000, (err) => {
    if (err) throw err
    console.log('> 服务已启动，访问地址：http://localhost:3000')
  })
})

• 第二步：修改package.json中的启动脚本：

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

方案2：App Router 专用 instrumentation 钩子 #

适用于Next.js 13.4+版本的App Router项目，无需修改启动入口。

• 第一步：在next.config.js中开启实验性配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
}
module.exports = nextConfig

• 第二步：在项目根目录（或src目录下，对应你的项目结构）新建instrumentation.ts文件：

export async function register() {
  // 仅在Node.js运行环境执行，排除Edge Runtime场景
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // 此处为一次性初始化逻辑
    console.log('App Router 服务启动初始化执行')
  }
}

注意：该钩子目前为实验性特性，后续版本API可能存在变动。

方案3：Pages Router 轻量实现 #

适用于Pages Router项目，无需修改启动入口，初始化会在第一次收到请求时触发。

• 在pages/_app.tsx中添加全局标记控制初始化仅执行一次：

import type { AppProps } from 'next/app'

let initDone = false
async function globalInit() {
  if (initDone) return
  initDone = true
  // 此处为一次性初始化逻辑
  console.log('Pages Router 一次性初始化执行')
}

function MyApp({ Component, pageProps }: AppProps) {
  // 仅在服务端执行，排除客户端渲染场景
  if (typeof window === 'undefined') {
    globalInit()
  }
  return <Component {...pageProps} />
}

export default MyApp

注意事项 #

若你将项目部署在无服务器运行环境（如Vercel、Netlify函数），实例会按需冷启动，每次冷启动都会执行一次初始化逻辑，属于正常现象。如果需要全局唯一的一次性操作，可配合外部存储加分布式锁实现幂等控制。

内容的提问来源于stack exchange，提问作者Guy