Next.js 13.4.0部署Vercel时预渲染失败，本地构建正常

问题背景 #

• 项目基于Next.js 13.3.4运行正常，升级至13.4.0后，Vercel控制台所有页面预渲染失败
• 本地执行yarn run build构建完全正常，尝试移除所有Headless UI组件后问题依然存在
• 核心报错：TypeError: Cannot read properties of null (reading 'useRef')，链路指向@headlessui/react的use-sync-refs钩子

报错详情 #

Error occurred prerendering page "/careers/content-specialist". 
TypeError: Cannot read properties of null (reading 'useRef')
    at exports.useRef (/vercel/path0/node_modules/react/cjs/react.production.min.js:25:337)
    at y (file:///vercel/path0/node_modules/@headlessui/react/dist/hooks/use-sync-refs.js:1:178)
    at Ke (file:///vercel/path0/node_modules/@headlessui/react/dist/components/listbox/listbox.js:1:4762)
    at Ge (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:118:245)
    at Z (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:120:91)
    at He (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:123:155)
    at Ge (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:115:215)
    at Z (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:120:91)
    at Ge (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:115:9)
    at Z (/vercel/path0/node_modules/next/dist/compiled/react-dom/cjs/react-dom-server.browser.production.min.js:120:91)

解决方案 #

1. 对齐React与Next.js版本 #

Next.js 13.4.0内置依赖React 18.2.0，确保package.json中react、react-dom版本与之一致，避免版本冲突：

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "next": "13.4.0"
  }
}

执行以下命令重装依赖并清除本地缓存：

yarn cache clean && yarn install

2. 清除Vercel构建缓存 #

Vercel的构建缓存可能残留旧版本依赖，导致与本地环境不一致。在项目控制台的「Build & Development Settings」中点击「Clear Build Cache」，然后重新触发构建。

3. 升级Headless UI至兼容版本 #

即使移除了组件，依赖缓存或残留代码可能仍引发问题。升级@headlessui/react到v1.7.14及以上版本（该版本修复了Next.js 13.4的SSR兼容问题）：

yarn add @headlessui/react@latest

4. 隔离客户端专属逻辑 #

确保使用useRef的组件不会在服务端预渲染阶段执行客户端代码，可通过useEffect包裹或动态导入禁用SSR：

import dynamic from 'next/dynamic'

// 动态导入组件并禁用服务端渲染
const ListboxComponent = dynamic(() => import('../components/Listbox'), {
  ssr: false
})

5. 本地模拟Vercel构建环境 #

使用Vercel CLI在本地复现构建过程，排查是否为环境差异问题：

vercel build

如果本地Vercel构建也报错，说明问题出在代码或依赖配置，而非平台环境。

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