Next.js：instrumentation.ts无法服务端运行及初始化方案咨询

关于 instrumentation.ts 的运行环境 #

instrumentation.ts 确实运行在服务端，但Next.js默认会把该文件同时打包到客户端和服务端环境（尽管register函数仅在服务端执行），直接引入Node.js核心模块会因为客户端打包环境无法识别这类模块而报错。

解决 os 模块引入报错的方法 #

方式1：动态导入+服务端环境判断 #

修改instrumentation.ts代码，确保仅在服务端环境下加载Node.js模块：

export async function register() {
  // 仅服务端执行时导入模块
  if (typeof window === 'undefined') {
    const os = await import('os');
    // 注意：os.hostname是方法，需要加()调用
    console.log('i am running server side. ' + os.default.hostname());
  }
}

方式2：配置Webpack排除Node.js核心模块打包 #

在next.config.js中添加配置，告知Webpack服务端打包时保留Node.js核心模块：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.externals.push({
        os: 'commonjs os',
      });
    }
    return config;
  },
};

module.exports = nextConfig;

配置后可直接导入os模块，但仍建议搭配环境判断避免潜在问题。

其他服务端启动初始化方案 #

1. 服务端组件初始化 #

创建仅在服务端运行的组件，在应用根布局中引入：

// app/ServerInit.tsx
'use server';

import os from 'os';

export default async function ServerInit() {
  // 执行初始化逻辑
  console.log('Server init from Server Component: ' + os.hostname());
  return null;
}

在app/layout.tsx中引入该组件：

import ServerInit from './ServerInit';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ServerInit />
        {children}
      </body>
    </html>
  );
}

该逻辑会在服务端渲染根布局时执行。

2. 自定义服务器（Custom Server） #

使用自定义服务器（如Express），在服务器启动阶段直接执行初始化代码：

// server.js
const { createServer } = require('http');
const { parse } = require('url');
const next = require('next');
const os = require('os');

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

app.prepare().then(() => {
  // 启动时执行初始化
  console.log('Server init from custom server: ' + os.hostname());

  createServer((req, res) => {
    const parsedUrl = parse(req.url, true);
    handle(req, res, parsedUrl);
  }).listen(3000, (err) => {
    if (err) throw err;
    console.log('> Ready on http://localhost:3000');
  });
});

修改package.json启动脚本：

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

注意：自定义服务器会失去Next.js部分自动优化特性（如Edge Runtime支持），需谨慎使用。

3. API Route 初始化 #

创建API Route，利用Next.js缓存机制让初始化逻辑仅执行一次：

// app/api/init/route.ts
import os from 'os';
import { NextResponse } from 'next/server';

// 首次请求时执行（默认缓存静态API Route）
export async function GET() {
  console.log('Server init from API Route: ' + os.hostname());
  return NextResponse.json({ status: 'ok' });
}

在根布局的服务端逻辑中调用该API：

// app/layout.tsx
async function initServer() {
  await fetch('http://localhost:3000/api/init');
}

export default async function RootLayout({ children }) {
  await initServer();
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

适合需通过HTTP请求触发的初始化场景。

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