Vercel部署时出现ReferenceError: self is not defined问题

问题情况 #

本地执行npm run dev项目运行正常，但部署到Vercel时触发以下错误：

ReferenceError: self is not defined
    at Object.<anonymous> (/vercel/path0/.next/server/pages/middleware.js:1:1)
    at Module._compile (node:internal/modules/cjs/loader:1256:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1310:10)
    at Module.load (node:internal/modules/cjs/loader:1119:32)
    at Module._load (node:internal/modules/cjs/loader:960:12)
    at Module.require (node:internal/modules/cjs/loader:1143:19)
    at require (node:internal/modules/cjs/helpers:110:18)
    at Object.requirePage (/vercel/path0/node_modules/next/dist/server/require.js:88:12)
    at /vercel/path0/node_modules/next/dist/server/load-components.js:48:73
    at async Object.loadComponents (/vercel/path0/node_modules/next/dist/server/load-components.js:48:26)
> Build error occurred
Error: Failed to collect page data for /middleware
    at /vercel/path0/node_modules/next/dist/build/utils.js:963:15 {
  type: 'Error'
}
Error: Command "npm run build" exited with 1

问题根源 #

核心原因是：Next.js的Middleware运行在Node.js服务器环境中，但代码里使用了浏览器专属的全局变量self。本地开发时Next.js做了兼容处理，没暴露这个问题，但Vercel的生产构建会严格区分运行环境，直接触发报错。

另外也有可能是你引入的第三方库默认依赖浏览器环境，在Middleware加载时触发了这个错误。

解决办法 #

1. 检查并替换Middleware里的self引用 #

打开你的middleware.js文件，查找所有self的使用场景：

• 如果是用来指代全局对象，直接替换为globalThis（这是浏览器和Node.js都支持的全局对象）
• 如果是调用浏览器专属API（比如self.addEventListener），这类代码不能放在Middleware中，需要移到标记了'use client'的客户端组件里

2. 动态导入依赖浏览器的第三方库 #

如果是第三方库导致的问题，在Middleware中使用动态导入并禁用SSR：

// 在middleware.js中
import dynamic from 'next/dynamic';

// 仅在客户端加载依赖浏览器环境的库
const BrowserOnlyLib = dynamic(() => import('你的第三方库名'), { ssr: false });

注意：Middleware本身运行在服务器端，如果该库不支持Node.js环境，只能在客户端逻辑中调用它，不要在Middleware里执行相关代码。

3. 用webpack配置兼容环境 #

如果无法修改第三方库代码，可在next.config.js中添加如下配置，让webpack屏蔽对self的依赖：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      self: false,
    };
    return config;
  },
};

module.exports = nextConfig;

4. 确认Middleware的文件位置 #

Next.js的Middleware必须放在项目根目录或src目录下，不能放在pages文件夹中！旧版本可能允许该路径，但新版本会把pages里的文件当作页面组件处理，构建时触发环境判断错误。

• 正确路径：/middleware.js 或 /src/middleware.js
• 错误路径：/pages/middleware.js

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