CPanel部署Next.js应用报500内部服务器错误排查

你遇到的500错误并非Next.js本身代码逻辑问题，核心矛盾是手动在终端执行node server.js可以正常启动，但CPanel的NodeJS应用托管机制的运行上下文、路径解析规则和你手动登录终端执行的环境存在差异，按以下优先级排查修复即可：

1. 第一优先级修复：server.js硬编码本地Windows路径 #

你standalone构建使用的server.js里，sassOptions.includePaths字段写死了你本地开发环境的Windows绝对路径：

"C:\\Users\\johnk\\OneDrive\\Documents\\Elikya Academy\\global.client\\src\\styles"

这个路径在Linux系统的CPanel服务器上完全不存在，手动在终端执行时因为当前工作目录匹配可能没有触发路径解析错误，但CPanel拉起Node应用时的工作目录、权限上下文和手动执行环境不一致，解析到不存在的路径直接抛出异常就会返回500。
修复方式：不要在server.js里硬编码全量Next配置，直接删掉自定义server.js里整个conf对象的硬编码内容，让Next自动读取项目根目录的next.config.js即可，你当前手写的conf不仅带本地无效路径，还和next.config.js的配置存在冗余冲突。
正确的最简standalone server.js代码如下：

process.env.NODE_ENV = "production";
const NextServer = require("next/dist/server/next-server").default;
const http = require("http");
const path = require("path");

process.on("SIGTERM", () => process.exit(0));
process.on("SIGINT", () => process.exit(0));

const currentPort = parseInt(process.env.PORT, 10) || 3000;

const nextServer = new NextServer({
  hostname: "localhost",
  port: currentPort,
  dir: __dirname,
  dev: false,
});
const handler = nextServer.getRequestHandler();

const server = http.createServer(async (req, res) => {
  try {
    await handler(req, res);
  } catch (err) {
    console.error(err);
    res.statusCode = 500;
    res.end("internal server error");
  }
});

server.listen(currentPort, (err) => {
  if (err) {
    console.error("Failed to start server", err);
    process.exit(1);
  }
  console.log("Listening on port", currentPort);
});

2. CPanel NodeJS应用配置核对 #

手动执行能跑通说明依赖、代码本身无致命问题，需要逐一核对CPanel创建Node应用的配置项：

• 应用启动文件必须填server.js，不要填next start类的npm脚本，CPanel的Node应用不会自动加载package.json里的scripts配置
• Node版本必须和本地构建时的大版本一致，Next 12.1.5要求Node版本至少12.22.0，推荐选择16.x版本，不要选18以上版本，存在已知兼容性问题
• 应用根目录要选中上传代码的最外层目录，也就是存放package.json、server.js的层级，不要选到.next、src这类子目录
• 创建完应用后，必须在CPanel的Node应用管理界面点击一次「Run NPM Install」，不要手动在终端装依赖，CPanel的Node应用使用独立虚拟环境，终端全局安装的依赖无法被应用识别
• 不要手动在.htaccess里添加自定义端口转发规则，CPanel创建Node应用后会自动生成反向代理规则，自定义规则容易引发端口冲突导致500

3. standalone部署文件完整性检查 #

使用standalone模式构建后，不要只上传.next/standalone目录内的文件，必须额外复制两个目录到对应位置：

• 把项目根目录的public文件夹整个复制到standalone输出目录的根目录
• 把.next/static文件夹整个复制到standalone输出目录的.next路径下
  缺失这两个目录会导致静态资源加载失败，也会触发500错误。

4. 权限问题修复 #

CPanel的Node应用运行时使用账号的普通用户权限，不要给项目文件设置777权限，正确权限规则为文件夹设755、文件设644，尤其是.next目录下的构建产物，如果权限不足导致进程无法读取文件，会直接抛出500错误。

修复验证方式：所有配置调整完成后，先在CPanel的Node应用界面点击「Restart」，再查看应用日志，如果日志输出Listening on port xxx且无报错，说明服务启动成功，直接访问绑定的域名即可，不需要额外加端口号。

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