Next.js部署Coolify（Hostinger VPS+MySQL）后API路由全500错误排查求助

一、精准定位500错误原因的步骤 #

1. 深挖API端点的详细错误日志 #

• 在Coolify控制台找到部署的Next.js应用，查看完整服务器端日志（不要仅看启动日志）。500错误通常会输出具体错误栈，比如数据库连接失败、SQL语法错误、权限问题等。
• 在极简测试端点/api/test.js中主动添加日志，明确问题环节：

export default async function handler(req, res) {
  try {
    console.log("DB_HOST:", process.env.DB_HOST);
    console.log("DB_USER:", process.env.DB_USER);
    // 尝试建立数据库连接
    const connection = await mysql.createConnection({
      host: process.env.DB_HOST,
      user: process.env.DB_USER,
      password: process.env.DB_PASS,
    });
    await connection.connect();
    console.log("数据库连接成功");
    await connection.end();
    res.status(200).json({ message: "测试成功" });
  } catch (error) {
    console.error("API错误详情:", error);
    res.status(500).json({ error: error.message });
  }
}

部署后查看日志，即可明确是环境变量未加载还是数据库连接出错。

2. 验证Coolify中环境变量的实际可用性 #

• 即使本地.env配置正确，Coolify部署时可能存在变量未注入的情况。修改应用启动命令，添加变量打印步骤：

echo "DB_HOST: $DB_HOST" && echo "DB_USER: $DB_USER" && npm start

查看启动日志输出，确认变量是否正确加载（请勿打印DB_PASS，避免敏感信息泄露）。

3. 测试Coolify容器到MySQL的网络连通性 #

• 若MySQL安装在Hostinger VPS本地而非容器化，Coolify容器无法通过localhost/127.0.0.1访问，需改用VPS的内网IP或公网IP作为DB_HOST。
• 进入Next.js容器内部，执行telnet <DB_HOST> 3306或nc -zv <DB_HOST> 3306，测试端口连通性。若不通，检查VPS防火墙规则（含Hostinger自带防火墙和iptables），确保容器网络能访问3306端口。

4. 检查MySQL的用户权限与连接限制 #

• 终端能连接不代表Coolify容器IP在MySQL用户的允许访问范围内。若用户权限为user@localhost，容器IP不在允许列表会导致连接被拒绝，需修改权限：

GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;

生产环境建议将%替换为容器子网IP，提升安全性。

二、MySQL与Coolify搭配的特定配置注意事项 #

• 容器化MySQL的网络配置：若MySQL通过Coolify部署为容器，需确保Next.js应用容器与MySQL容器在同一Coolify网络中，此时DB_HOST可直接使用MySQL容器的服务名称（如mysql-service），无需IP。
• 环境变量注入时机：Next.js的NEXT_PUBLIC_*变量会在next build时嵌入静态资源，但服务器端变量（如DB_HOST）需在运行时可用。Coolify部署时要确保环境变量设置为运行阶段注入，而非仅构建阶段。
• Hostinger VPS的MySQL配置：若用公网IP访问MySQL，需在Hostinger控制面板开启端口转发，同时修改MySQL配置文件my.cnf，将bind-address设为0.0.0.0（允许外部访问），而非默认的127.0.0.1。

三、极简测试端点的排查技巧 #

既然/api/test.js也返回500，说明问题大概率在基础配置而非业务逻辑。可简化端点仅打印环境变量：

export default function handler(req, res) {
  res.status(200).json({
    dbHost: process.env.DB_HOST || "未加载",
    nodeEnv: process.env.NODE_ENV || "未加载"
  });
}

若返回的dbHost为“未加载”，说明Coolify未正确注入环境变量，需检查Coolify的环境变量配置（是否勾选“运行时可用”选项）。

内容的提问来源于stack exchange，提问作者bernabé le prolo