Next.js并行路由搭配Webpack构建出现Chunk加载错误的配置咨询

问题场景 #

在Next.js应用中使用并行路由构建仪表盘，目录结构如下：

Dashboard
- @header
  - loading.tsx
  - page.tsx
- @content
  - loading.tsx
  - page.tsx

采用独立构建模式（next build && next start）部署到Docker容器后，访问仪表盘页面时出现Chunk Load Error：

Chunk Load Error: 
Loading chunk 6635 failed. (404) *** dashboard/%40header/loading-eacb3abac99bee42.js

原因分析及修复方案 #

1. 升级Next.js到最新稳定版 #

并行路由是Next.js 13+ App Router的特性，早期版本存在带@前缀路由的chunk路径编码bug。执行升级命令：

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

2. 配置Webpack的publicPath（自定义部署路径时） #

如果应用部署在子路径下（如https://xxx.com/dashboard），需在next.config.js中明确静态资源前缀，避免chunk路径解析错误：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  assetPrefix: process.env.NEXT_PUBLIC_ASSET_PREFIX || '',
  webpack: (config) => {
    config.output.publicPath = `${process.env.NEXT_PUBLIC_ASSET_PREFIX || ''}/_next/`;
    return config;
  },
};

module.exports = nextConfig;

部署时通过环境变量指定前缀：NEXT_PUBLIC_ASSET_PREFIX=/dashboard

3. 检查Docker容器的静态资源映射 #

独立构建模式下，Next.js的静态chunk文件存储在/.next/static目录，Dockerfile必须正确复制该目录：

FROM node:18-alpine

WORKDIR /app

COPY .next/standalone ./
COPY .next/static ./.next/static
COPY public ./public

ENV PORT 3000
EXPOSE 3000

CMD ["node", "server.js"]

遗漏复制.next/static会导致chunk文件无法被访问。

4. 临时禁用Chunk分割（排查用） #

若以上方案无效，可临时合并所有chunk验证问题根源：

// next.config.js
const nextConfig = {
  output: 'standalone',
  webpack: (config) => {
    config.optimization.splitChunks = {
      chunks: 'all',
      name: 'main',
    };
    return config;
  },
};

module.exports = nextConfig;

此方案会增大初始包体积，仅用于排查，不建议生产环境长期使用。

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