Next.js启动时出现SyntaxError、ChunkLoadError及Hydration错误求助

问题症状 #

• 执行npm run dev启动项目后，Chrome控制台频繁抛出 layout.js:160 Uncaught SyntaxError: Invalid or unexpected token 错误
• Link组件和onClick事件直接失效，一段时间后页面崩溃，伴随Unhandled Runtime Error、Uncaught ChunkLoadError及Warning: An error occurred during hydration提示
• 错误为偶发状态（5次启动约出现3次），仅浏览器端报错，Node终端无任何异常输出

已排查操作 #

• 检查项目代码语法无问题，对比服务端与客户端渲染的HTML结构一致
• 尝试删除.next文件夹、清空node_modules并重新安装、清除浏览器缓存，仅能临时解决问题，重启后错误仍会复现
• 注释Link组件和onClick事件后错误消失，使用原生<a>标签无异常

核心代码示例 #

layout.tsx #

import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import Navbar from './Navbar';
import Footer from './Footer';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Navbar />
        {children}
        <Footer />
      </body>
    </html>
  );
}

Navbar.tsx #

import Link from 'next/link';

export default function Navbar() {
  const handleClick = () => {
    console.log('Navbar clicked');
  };

  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
      <button onClick={handleClick}>Click Me</button>
    </nav>
  );
}

Footer.tsx #

export default function Footer() {
  return (
    <footer>
      <p>© 2024 My Next.js App</p>
    </footer>
  );
}

依赖配置（package.json） #

{
  "name": "my-next-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "14.0.4",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "postcss": "^8",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

解决方案 #

1. 临时关闭React Strict Mode验证 #

在next.config.js中关闭Strict Mode，验证是否为重复渲染导致的资源加载冲突：

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: false,
};

module.exports = nextConfig;

若关闭后问题消失，说明是Strict Mode触发的组件重复初始化导致资源加载异常，需进一步排查组件中是否存在非幂等的初始化逻辑。

2. 调整Next.js版本 #

尝试升级到最新稳定版，或降级至14.0.3版本（部分开发者反馈14.0.4存在开发环境chunk加载bug）：

npm install next@14.0.3

3. 添加Chunk加载错误处理 #

在app/layout.tsx中添加全局错误边界，处理ChunkLoadError并提供重试机制：

'use client';

import { useEffect, useState } from 'react';
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import Navbar from './Navbar';
import Footer from './Footer';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const [hasError, setHasError] = useState(false);

  useEffect(() => {
    const handleChunkLoadError = (error: ErrorEvent) => {
      if (error.error instanceof Error && error.error.name === 'ChunkLoadError') {
        setHasError(true);
      }
    };

    window.addEventListener('error', handleChunkLoadError);
    return () => window.removeEventListener('error', handleChunkLoadError);
  }, []);

  if (hasError) {
    return (
      <html lang="en">
        <body className={inter.className}>
          <div>资源加载失败，正在重试...</div>
          <button onClick={() => window.location.reload()}>点击重试</button>
        </body>
      </html>
    );
  }

  return (
    <html lang="en">
      <body className={inter.className}>
        <Navbar />
        {children}
        <Footer />
      </body>
    </html>
  );
}

4. 排查自定义配置冲突 #

若项目中有自定义Babel/PostCSS配置，检查是否存在与Next.js默认配置冲突的规则，比如不必要的语法转换或压缩选项，导致客户端代码解析异常。

5. 排除浏览器扩展干扰 #

在Chrome隐身模式下运行项目，排除广告拦截器、脚本注入类扩展对Next.js chunk加载的干扰。

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