cPanel上部署Nuxt项目运行异常 寻求完整部署指导

前置环境配置要求 #

• 登录cPanel进入「设置Node.js应用」模块，严格匹配项目本地开发时的Node.js版本号，版本偏差超过1个大版本会直接出现模块兼容报错，不建议直接使用主机默认的全局Node环境跑项目
• 为项目创建独立的应用运行环境，记录下系统自动分配的专属运行端口，后续Nuxt配置要和这个端口完全匹配
• 项目所在目录权限设置为对应应用用户可读写，禁用全局777权限配置，避免主机安全机制拦截程序执行

本地文件预处理规则 #

• 上传文件前务必删除本地项目内的node_modules目录、.nuxt缓存目录，这类目录的编译产物和操作系统强绑定，直接上传到Linux主机必然出现模块加载失败
• 上传范围仅保留项目核心源文件：nuxt.config.js、package.json、锁文件（package-lock.json/yarn.lock）、pages、components、static、middleware、plugins目录下的源码文件
• 本地调整nuxt.config.js的生产配置：
  • target参数明确设置为'server'（服务端渲染模式）或'static'（静态生成模式），不使用默认配置值
  • server.host固定设置为0.0.0.0，server.port填写cPanel为应用分配的专属端口号，不要写固定的3000端口
  • 生产环境关闭sourcemap调试开关，避免资源加载超时

主机端构建部署操作 #

• 通过cPanel的内置终端进入项目根目录，执行生产依赖安装命令：npm install --production，跳过开发依赖安装环节，减少依赖冲突概率
• 安装完成后在主机端重新执行生产构建命令：nuxt build，不要复用本地生成的构建产物，跨平台编译产物不具备兼容性
• 启动命令统一填写为node node_modules/nuxt/bin/nuxt.js start，不要使用npm run start作为启动命令——cPanel的非交互终端不会自动加载npm脚本对应的环境变量，容易出现启动失败

高频异常修复操作 #

• 出现权限拒绝、端口占用报错：确认是否终止了残留的旧应用进程，在Node应用管理面板先执行停止操作，再加载新的配置项启动，不要直接刷新页面验证效果
• 出现静态资源404报错：检查项目根目录到public_html的软链接配置，确保所有静态资源请求能被正确映射到Nuxt的构建产物目录，不要在代码中写死本地绝对路径
• 出现500内部服务器错误：检查.env环境变量文件的位置，必须放在项目根目录（和nuxt.config.js同层级），cPanel的Node应用启动流程不会自动加载子目录下的环境变量文件
• 域名访问异常时，先通过cPanel分配的临时端口地址直连测试应用是否正常运行，确认应用无问题后再配置反向代理规则，把域名请求转发到对应Node端口

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