NextJS 13.4部署后TypeError破坏客户端路由问题求助

问题概况 #

• 仅在执行npm run build + npm run start后出现异常，npm run dev模式完全正常
• 本地环境与Vercel部署均复现该问题
• 客户端路由（NextJS核心特性）完全失效，所有导航触发全页面刷新
• 错误指向Next内部代码中尝试读取document.getElementById("__NEXT_DATA__").textContent时失败，目标元素为null

错误详情 #

错误栈 #

TypeError: Cannot read properties of null (reading 'textContent')
    at Object.<anonymous> (main-4f563ee09e593a2f.js:1:8408)
    at Generator.next (<anonymous>)
    at n (17-bbe337a8760cd758.js:1:134)
    at u (17-bbe337a8760cd758.js:1:331)
    at 17-bbe337a8760cd758.js:1:390
    at new Promise (<anonymous>)
    at Object.<anonymous> (17-bbe337a8760cd758.js:1:272)
    at Object.Q (main-4f563ee09e593a2f.js:1:9011)
    at t.initialize (main-4f563ee09e593a2f.js:1:7055)
    at 8577 (main-4f563ee09e593a2f.js:1:15791)

触发错误的Next内部函数 #

function Q() {
            return (Q = g(function*() {
                arguments.length > 0 && void 0 !== arguments[0] && arguments[0],
                a = JSON.parse(document.getElementById("__NEXT_DATA__").textContent),
                window.__NEXT_DATA__ = a,
                h = a.defaultLocale;
                let e = a.assetPrefix || "";
                if (n.p = "".concat(e, "/_next/"),
                x.setConfig({
                    serverRuntimeConfig: {},
                    publicRuntimeConfig: a.runtimeConfig || {}
                }),
                l = N.getURL(),
                D.hasBasePath(l) && (l = I.removeBasePath(l)),
                a.scriptLoader) {
                    let {initScriptLoader: e} = n(6507);
                    e(a.scriptLoader)
                }
                o = new O.default(a.buildId,e);
                let t = e=>{
                    let[t,n] = e;
                    return o.routeLoader.onEntrypoint(t, n)
                }
                ;
                return window.__NEXT_P && window.__NEXT_P.map(e=>setTimeout(()=>t(e), 0)),
                window.__NEXT_P = [],
                window.__NEXT_P.push = t,
                (u = R.default()).getIsSsr = ()=>r.isSsr,
                i = document.getElementById("__next"),
                {
                    assetPrefix: e
                }
            })).apply(this, arguments)
        }

排查与解决方案 #

1. 移除手动安装的Webpack依赖 #

你的package.json中手动安装了webpack和webpack-cli，但NextJS自带适配版本的Webpack，手动安装的高版本可能与Next内置版本冲突，导致构建产物异常。执行以下命令移除：

npm uninstall webpack webpack-cli

2. 检查根布局/文档文件是否缺失关键元素 #

• App Router（13.x+）：检查app/layout.js是否正确渲染{children}，确保Next能正常注入__NEXT_DATA__脚本。正确示例：

import './globals.css'

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

• Pages Router：检查pages/_document.js是否正确继承Document并包含NextScript，这是注入__NEXT_DATA__的关键。正确示例：

import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    return { ...initialProps }
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

3. 排查客户端代码中的DOM操作 #

搜索项目中是否存在在页面初始化阶段执行的DOM操作代码（如innerHTML、removeChild），这些代码可能误删除了#__NEXT_DATA__元素。重点检查：

• Firebase初始化脚本
• Contentful富文本渲染相关代码
• 自定义的全局DOM操作逻辑

4. 升级NextJS到稳定版本 #

当前使用的NextJS版本为13.1.6，该版本可能存在已知的构建bug。升级到13.4.x或更高稳定版本：

npm install next@latest react@latest react-dom@latest

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