Next.js部署cPanel遇动态路由ChunkLoadError 404问题求助

1. 对齐构建环境与命令 #

• 必须使用生产环境构建命令：next build && next export（静态导出场景）或next build（Node.js服务器场景），本地开发的next dev产物和生产构建的chunk哈希逻辑完全不同，严禁上传开发环境产物。
• 不要随意修改next.config.js中的output配置，默认输出结构更适配cPanel环境。

2. 确保文件上传完全一致 #

• 删除服务器上旧的_next目录，重新上传本地最新构建的.next或out目录（根据构建方式），避免新旧chunk文件混杂。
• 核对_next/static/chunks下的文件，确保本地构建生成的所有chunk都已上传，杜绝漏传或上传旧版本的情况。

3. 配置cPanel的URL重写规则 #

在项目根目录创建或修改.htaccess文件，添加以下规则，确保Apache服务器能正确转发动态路由请求：

RewriteEngine On
RewriteBase /
RewriteRule ^_next/static/ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

4. 临时固定构建ID排查哈希问题 #

如果chunk文件名哈希始终不匹配，可在next.config.js中强制固定构建ID，排除哈希生成差异：

/** @type {import('next').NextConfig} */
const nextConfig = {
  generateBuildId: () => 'fixed-build-id',
  output: 'export',
}

module.exports = nextConfig

构建后重新上传验证，此方法仅用于排查，不建议长期使用（会破坏缓存优化）。

5. 统一Node.js版本 #

确保cPanel上配置的Node.js版本和本地开发版本完全一致（如v18.x或v20.x），版本差异可能导致构建产物的哈希生成逻辑异常。

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