Next.js 15.2.2生产环境ChunkLoadError问题求助

环境信息 #

• Next.js ^15.2.2
• Node:20.17.0-alpine
• 部署方式：Docker（基于Vercel示例Dockerfile）+ EC2 Nginx反向代理
• 涉事页面为Client组件（标注'use client'）

报错信息 #

1. 语法错误：

Uncaught SyntaxError: Unexpected token '<'

2. Chunk加载失败：

ChunkLoadError: Loading chunk 2295 failed.
(missing: https://somesite.com/_next/static/chunks/app/(nextui)/(application)/(organizations)/choose-organization/page-b454073fbe962ee8.js)
    at r.f.j (webpack-18adaa73af8330a5.js:1:2997)
    at webpack-18adaa73af8330a5.js:1:1226
    at Array.reduce (<anonymous>)
    at r.e (webpack-18adaa73af8330a5.js:1:1205)
    at i (1684-d227fb5768204d34.js:1:153136)
    at 1684-d227fb5768204d34.js:1:165710
    at 1684-d227fb5768204d34.js:1:165914
    at t (1684-d227fb5768204d34.js:1:167167)

已确认情况 #

Docker容器内对应chunk文件page-b454073fbe962ee8.js实际存在：

/app/.next/static/chunks/app/(nextui)/(application)/(organizations)/choose-organization $ ls -la
total 16
drwxr-xr-x    2 nextjs   nodejs          38 Mar 20 00:52 .
drwxr-xr-x    4 nextjs   nodejs          94 Mar 20 00:52 ..
-rw-r--r--    1 nextjs   nodejs       15154 Mar 20 00:52 page-b454073fbe962ee8.js

解决步骤 #

1. 修正Nginx静态资源代理配置 #

Unexpected token '<'本质是请求静态资源时返回了HTML（通常是404页面），说明Nginx未正确将/_next/static/路径的请求转发给Next.js服务。修改Nginx配置：

server {
    listen 443 ssl;
    server_name somesite.com;

    # 优先处理静态资源请求
    location /_next/static/ {
        proxy_pass http://localhost:3000; # 替换为你的Next.js服务端口
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 静态资源长期缓存（可选）
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 其他请求转发给Next.js处理
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

2. 检查Next.js路径配置 #

如果站点部署在根域名下，确保next.config.js中未错误设置basePath或assetPrefix；若部署在子路径下，需正确配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  // 根域名部署时注释以下两行
  // basePath: '/your-subpath',
  // assetPrefix: 'https://cdn.yourdomain.com',
}

module.exports = nextConfig

3. 修复容器内文件权限 #

即使文件存在，Next.js进程可能无读取权限。在Dockerfile中添加权限设置：

# 复制构建产物后执行
RUN chown -R nextjs:nodejs /app/.next
RUN chmod -R 755 /app/.next

或进入容器手动执行：

chown -R nextjs:nodejs /app/.next/static/
chmod -R 755 /app/.next/static/

4. 处理URL特殊字符 #

路径中的括号()可能被Nginx拦截，在server块中添加规则允许特殊字符：

server {
    # ...其他配置
    # 允许URL中的括号等特殊字符
    if ($request_uri ~* "[()]" ) {
        set $allow_unsafe_chars 1;
    }
    # 确保完整路径传递给Next.js
    location /_next/static/ {
        proxy_pass http://localhost:3000$request_uri;
        # ...header配置同步骤1
    }
}

5. 清除缓存重新部署 #

• 执行next build生成新的chunk哈希
• 部署后强制刷新浏览器（Ctrl+F5）
• 若使用CDN，同步清除CDN缓存

核心原因 #

Nginx未正确代理/_next/static/路径的请求，导致客户端请求JS chunk时收到HTML页面，进而触发Unexpected token '<'和ChunkLoadError。按上述步骤逐一排查即可解决。

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