Next.js Instrumentation提取条件到变量后行为异常原因咨询

这是之前一个已解决问题的后续，核心困惑在于Next.js Instrumentation实验特性的底层行为。该特性允许在应用启动时运行代码，且会同时在服务端和客户端执行，因此使用Node.js专属模块时必须做环境判断。

可正常运行的代码 #

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const os = await require('os');
    console.log(os.hostname());
  }
}

执行失败的代码 #

export async function register() {
  const isServer = process.env.NEXT_RUNTIME === 'nodejs'
  if (isServer) {
    const os = await require('os');
    console.log(os.hostname());
  }
}

报错信息 #

- error ./instrumentation.ts:12:21
Module not found: Can't resolve 'os'
  10 |   const isServer = process.env.NEXT_RUNTIME === 'nodejs'
  11 |   if (isServer) {
> 12 |     const os = await require('os');
     |                     ^
  13 |     console.log(os.hostname());
  14 |   }
  15 | }

原因分析 #

问题核心在于Next.js构建工具（Webpack/Turbopack）的静态代码分析能力：

• 第一种写法中，process.env.NEXT_RUNTIME === 'nodejs'直接作为if条件，构建工具能静态识别这个分支只会在Node.js环境执行，因此不会在客户端打包流程中尝试解析os这类服务端专属模块。
• 第二种写法把判断结果存入isServer变量后，构建工具无法静态确定该变量的最终值（尽管实际运行时不会被修改，但工具无法100%确定），会认为require('os')的代码路径可能在客户端执行，进而尝试在客户端环境解析不存在的os模块，最终触发报错。

简单来说，只有直接使用环境变量作为条件判断，才能让构建工具明确区分服务端/客户端代码分支，避免在客户端打包服务端专属模块。

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