Next.js应用本地运行正常 部署服务器后抛出TypeError类型错误

错误场景 #

本地开发、本地生产构建运行均正常，部署到服务器启动时抛出如下错误：

TypeError: Cannot convert undefined or null to object
at Function.keys (<anonymous>)
at NextNodeServer.getEdgeFunctions (...node_modules/next/dist/server/next-server.js:656:23)
at NextNodeServer.generateCatchAllMiddlewareRoute (...node_modules/next/dist/server/next-server.js:991:22)
at NextNodeServer.generateRoutes (...node_modules/next/dist/server/base-server.js:464:41)
at new Server (...node_modules/next/dist/server/base-server.js:109:48)
at new NextNodeServer (...node_modules/next/dist/server/next-server.js:62:9)
at NextServer.createServer (...node_modules/next/dist/server/next.js:128:16)
at async ...node_modules/next/dist/server/next.js:137:31

从错误栈可以定位到，报错触发于Next.js服务初始化阶段读取Edge函数清单、生成中间件路由的逻辑，按以下优先级排查即可：

排查步骤 #

• 第一优先级：校验构建流程与环境一致性

  • 禁止直接上传本地生成的.next构建目录、本地node_modules目录到服务器部署。跨操作系统（Windows/macOS本地到Linux服务器）的构建产物存在路径、二进制依赖差异，会直接导致Edge清单解析失败
  • 服务器端拉取对应迭代版本的代码后，优先执行npm ci安装依赖（不要用npm install，避免依赖版本锁不一致导致的版本漂移），再执行npm run build完成生产构建，最后执行npm start启动服务
  • 核对本地与服务器的Node.js版本、Next.js版本完全一致，Next.js 12+ 对Node版本最低要求为14.6，Next.js 13+ 要求Node.js 16.8及以上，版本不匹配会触发服务端运行时逻辑异常
  • 检查服务器上项目目录的文件权限，确保启动服务的用户对.next目录、node_modules目录有可读权限，权限不足会导致构建产物读取失败返回null

• 第二优先级：排查Edge运行时相关代码
  报错直接关联getEdgeFunctions方法，90%的同类报错都是Edge运行时代码/配置异常导致：

  • 检查项目根目录的middleware.js/middleware.ts文件：确认文件没有语法错误，没有导入仅浏览器端可用的依赖（比如直接调用window、document API的包），必须合法导出中间件处理函数或matcher配置，禁止导出undefined、空值
  • 排查所有标注了export const runtime = 'edge'的页面、路由处理器文件：确认这类文件没有导入Node.js原生模块（Edge Runtime不支持fs、path等Node原生API），没有语法错误。如果近期新增过Edge路由，可以先临时移除edge runtime配置改回Node.js运行时，重新构建验证，逐步缩小问题范围
  • 检查app目录下的路由拦截、平行路由、嵌套布局文件，确认没有空文件、错误导出的文件，这类文件会被Next.js识别为路由模块，解析失败时会返回空值触发上述错误

• 第三优先级：校验配置与插件兼容性

  • 检查根目录next.config.js/next.config.mjs配置：重点核对rewrites、redirects、headers、experimental相关配置项，确保这些配置项不会返回undefined、null值；如果近期修改过webpack配置、Edge相关实验性开关，可逐个回滚配置项验证触发点
  • 排查项目中使用的和路由、中间件强相关的插件（比如国际化插件、MDX插件、WASM相关插件），确认插件版本和当前Next.js主版本兼容，可临时移除插件配置重新构建验证

• 第四优先级：排查路径大小写问题
  Linux服务器文件系统默认大小写敏感，本地开发环境（Windows/macOS）默认大小写不敏感，会导致本地运行正常、服务器加载文件失败：

  • 全局检查所有import语句的路径大小写，和实际文件的命名完全匹配，比如导入@/components/Header但实际文件路径是./components/header.tsx就会触发加载异常
  • 检查所有路由文件、目录的命名，不要包含特殊字符、和Next.js路由约定冲突的命名

快速调试技巧 #

本地先切换到和服务器完全一致的Node.js版本，执行npm run build && npm start以生产模式启动。如果本地生产模式可以复现报错，直接本地调试即可，不需要反复部署到服务器；如果本地生产模式运行正常，问题一定出在服务器的构建流程、文件权限、环境一致性上，优先排查第一优先级的问题。

内容的提问来源于stack exchange，提问作者B. Mélicque