TurboRepo+Next.js部署到cPanel后JavaScript无法正常运行

可能的原因及排查修复步骤 #

1. 核对资源路径与cPanel站点结构 #

• 确认next.config.js中trailingSlash: true已生效，上传到public_html的文件结构需和导出的out目录完全一致：每个页面的HTML应在对应子文件夹的index.html中（比如about.html对应about/index.html），cPanel静态服务器默认优先加载文件夹下的index.html，路径不匹配会导致JS资源请求404。
• 打开浏览器开发者工具（F12）的网络标签，刷新页面查看JS文件的请求状态：若显示404，说明资源路径错误。
  • 如果你的站点部署在cPanel的子目录下（比如example.com/your-site），需在next.config.js中添加basePath配置，重新构建导出：

    const withTM = require("next-transpile-modules")(["ui"]);
    
    module.exports = withTM({
      // ...原有配置
      basePath: '/your-site', // 替换为实际子目录名称
    });
    

2. 检查cPanel文件权限 #

• cPanel上的静态文件需设置正确权限：JS、CSS文件权限设为644，文件夹权限设为755。
• 通过cPanel文件管理器选中out目录下所有文件，右键选择更改权限，设置对应数值即可。

3. 确保TurboRepo构建导出的完整性 #

• 避免根目录TurboRepo任务可能出现的资源遗漏，可单独进入apps/client目录，执行pnpm build && pnpm export，再将生成的out文件夹上传到cPanel。

4. 验证Next.js版本与静态导出兼容性 #

• 若使用Next.js 13+的App Router，需确保所有页面均为静态生成（未使用getServerSideProps或动态fetch请求），否则静态导出会缺失部分JS资源；若使用Pages Router，确认版本为稳定版即可。

替代部署方案 #

如果静态导出仍有问题，可尝试以下更稳定的方式：

• cPanel Node.js应用管理器部署：若cPanel支持Node.js，直接部署Next.js生产构建产物（.next文件夹）：
  1. 本地执行pnpm build，得到apps/client/.next文件夹。
  2. 将.next、package.json、pnpm-lock.yaml上传到cPanel的应用专属目录。
  3. 在cPanel Node.js管理器中设置启动命令为npx next start -p 端口号，并配置域名指向该应用。

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