在CPanel上部署Nuxtjs后页面无法渲染，求可行解决方案

前置校验 #

• 确认Nuxt部署模式：SSR/SSG/静态输出 对应完全不同的部署逻辑，cPanel基础版默认仅适配静态站点，若使用SSR模式需先确认cPanel是否开通Node.js应用托管权限，这是最常见的故障原因
• 检查构建产物完整性：本地执行对应构建命令后确认输出目录正常生成，SSG/静态模式默认输出dist目录，SSR模式默认输出.output目录

不同模式故障解决 #

静态部署（SSG/预渲染） #

• 根目录映射校验：cPanel默认站点根目录为public_html，需将dist目录下的所有文件直接上传到public_html根目录，不要上传dist文件夹本身，否则会出现路径匹配错误
• 路由重写配置：在public_html下新建.htaccess文件，填入以下配置解决刷新404问题：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

• 文件权限校验：所有静态文件权限设置为644，文件夹权限设置为755，权限错误会导致静态资源加载失败引发白屏

SSR部署 #

• Node版本匹配校验：Nuxt3要求Node.js版本 >= 18.x，Nuxt2要求Node.js版本 >= 14.x，不要使用cPanel默认的低版本Node运行时
• Node应用配置校验：在cPanel「Setup Node.js App」面板创建应用时需符合以下规则：
  • 应用根目录选择SSR源码上传的目录，不要绑定到public_html
  • 应用启动文件填写.output/server/index.mjs
  • 新增环境变量HOST=0.0.0.0、PORT=分配的Node应用端口、NODE_ENV=production
• pm2进程校验：执行pm2 list查看Nuxt进程是否处于online状态，若进程异常退出，执行pm2 logs 进程ID/名称查看具体报错信息
• 反向代理配置：若cPanel未自动配置端口转发，在public_html下的.htaccess文件中添加以下反向代理规则，将示例端口替换为你的Node应用分配端口：

RewriteEngine On
RewriteRule ^(.*)$ http://localhost:你的Node应用端口/$1 [P,L]

• 依赖校验：在Node应用管理面板执行NPM Install，或手动进入应用目录执行npm ci安装生产依赖，避免本地与服务器依赖版本不一致

通用排查步骤 #

• 打开浏览器开发者工具控制台，查看是否有资源加载404、JS运行报错：若出现静态资源404，检查Nuxt配置中的app.baseURL是否配置为当前站点域名，二级目录部署需补充子目录路径
• SSR模式下查看Node应用运行日志，确认服务启动过程中无异常报错

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