NextJS应用部署至cPanel后出现503 Service Unavailable错误

503错误本质是Node应用未正常启动，或cPanel反向代理无法连通应用服务，对应故障点和修复方式如下：

已确认的故障点 #

• 端口监听配置错误：现有server.js中硬编码绑定localhost，且未正确适配cPanel分配的端口。cPanel的Node.js应用通过Passenger反向代理转发请求，应用必须监听0.0.0.0地址才能接收反向代理的请求，绑定localhost会导致反向代理无法连通服务，直接返回503。
• 环境变量未正确注入：cPanel启动Node应用时不会自动读取package.json中start脚本里的NODE_ENV=production配置，应用会默认以开发模式启动，而服务器端安装依赖时若未安装devDependencies，会直接因缺少Next.js开发依赖启动崩溃。
• 构建产物与环境不兼容：现有流程是在本地Node 14.18.1环境构建后上传.next目录，再在cPanel的14.18.3环境下重装依赖，.next构建产物与服务器端依赖版本、Node版本存在微小差异时就会导致app.prepare()阶段执行失败，服务无法启动。
• 上传文件不全：部署时仅上传.next、package.json、next.config.js、server.js四个文件，若项目存在public静态资源目录、服务端运行时需要读取的其他文件（如样式全局依赖、配置文件等），会因文件缺失启动报错。

分步修复操作 #

1. 修正server.js配置，替换为以下内容：

// server.js
const { createServer } = require('http');
const { parse } = require('url');
const next = require('next');

// 强制指定生产环境，规避cPanel环境变量注入问题
process.env.NODE_ENV = 'production';
const dev = false;
// 监听所有网卡地址，允许反向代理接入
const hostname = '0.0.0.0';
// 优先使用cPanel自动分配的端口
const port = process.env.PORT ? Number(process.env.PORT) : 3000;
const app = next({ dev, hostname, port });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  createServer(async (req, res) => {
    try {
      const parsedUrl = parse(req.url, true);
      const { pathname, query } = parsedUrl;

      if (pathname === '/a') {
        await app.render(req, res, '/a', query);
      } else if (pathname === '/b') {
        await app.render(req, res, '/b', query);
      } else {
        await handle(req, res, parsedUrl);
      }
    } catch (err) {
      console.error('Error occurred handling', req.url, err);
      res.statusCode = 500;
      res.end('internal server error');
    }
  }).listen(port, hostname, (err) => {
    if (err) throw err;
    console.log(`> Ready on http://${hostname}:${port}`);
  });
});

2. 调整部署流程，避免跨环境构建兼容问题：
   • 删除cPanel上原有上传的.next目录和node_modules目录
   • 将本地项目除node_modules、.next、.git等本地缓存目录外的所有文件（含pages、public、styles等业务目录）完整上传到cPanel应用根目录apps/nextjs-cpanel
   • 在cPanel的Node.js应用管理界面执行npm install安装全量依赖，待依赖安装完成后执行npm run build，在服务器端完成项目构建，保证构建产物和运行环境完全匹配
3. 校正cPanel应用配置：
   • Node版本选择14.18.3即可，14.18.1与14.18.3为同大版本的补丁更新，不存在API兼容问题，不是故障诱因
   • 在应用环境变量配置项中新增NODE_ENV，值设为production
   • 确认应用启动入口文件为server.js，应用根目录、绑定访问路径现有配置无需调整
   • 重启Node.js应用，等待10-20秒后再访问测试
4. 若仍返回503，直接在cPanel Node.js管理界面查看应用运行日志，根据启动报错定位具体问题：
   • 提示Cannot find module xxx：对应依赖未安装，重新执行npm install即可
   • 提示EACCES: permission denied：文件权限错误，将应用根目录下所有文件的所属用户修改为当前cPanel账号用户，权限设为755
   • 提示Port already in use：端口被占用，在cPanel界面重启应用即可释放端口

现有next.config.js中的basePath配置与绑定访问路径一致，无需调整。

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