Hostinger Node.js "Failed to build the application" 错误解决方法详解

当 Hostinger 的部署引擎无法完成项目中定义的构建脚本时，就会出现 Failed to build the application error（构建应用程序失败错误）。

这是一条通用错误信息。确切原因通常与配置不匹配、缺少依赖项或环境设置不正确有关，可以通过构建日志来定位。

步骤 1 – 在 Hostinger 控制面板中核对 Node.js 参数

构建失败的常见原因之一，是你本地开发环境与 Hostinger 控制面板中的配置参数不匹配。

1. 打开 Hostinger 控制面板 → Websites。
2. 点击你的 Node.js 网站旁边的 Dashboard（控制面板）。
3. 打开 Deployments（部署）部分。
4. 点击失败的部署旁边的箭头（❯）。

请检查以下内容：

• 确保显示的 Node.js 版本与你的 package.json 文件中的 engines 字段一致，并且你的项目使用的是受支持的版本（18.x、20.x、22.x 或 24.x）。
• 核对框架和根目录是否与你的设置一致。

如果发现不匹配：

1. 点击 Redeploy（重新部署）。
2. 根据需要更新配置。
3. 重新上传或同步你的项目。
4. 点击 Save and redeploy（保存并重新部署）。

步骤 2 – 配置 Hostinger 环境变量

缺少或错误的环境变量可能导致构建失败。

1. 前往 Deployments（部署）→ Redeploy（重新部署）。
2. 滚动到 Environment Variables（环境变量）。
3. 确保所有必需的变量（例如数据库 URL 或 API 密钥）都已正确定义。根据需要添加、更新或删除变量。你也可以点击 import .env 批量导入变量。
4. 点击 Save and redeploy（保存并重新部署）应用更改。

步骤 3 – 检查构建命令和依赖项

确保你的项目已正确配置以便部署。

• 构建和启动脚本：确认你的 package.json 中包含有效的 scripts，并且启动命令指向正确的入口文件。支持的包管理器包括 npm、yarn 和 pnpm。
• 依赖项：如果错误是在最近的更改之后出现的，请检查是否新增了软件包。通过 ZIP 上传或提交到代码仓库时，不要包含 node_modules 文件夹，因为依赖项会在部署过程中自动安装。
• 端口配置：确保你的应用程序在 3000 端口上监听。
• 未找到 package.json： 如果构建日志显示 package.json not found 错误，说明 Hostinger 的构建系统找不到用于配置你的 Node.js 应用的该文件。请确认 package.json 位于项目根目录下。
  
  如果通过 GitHub 部署，请确认该文件已提交到仓库中。如果上传的是 ZIP 压缩包，请确认 package.json 位于压缩包的根目录下（而不是在某个子文件夹内）。修复后，点击 Redeploy（重新部署）。

大多数“Failed to build the application”错误都可以通过使 Node.js 设置、环境变量和项目配置与应用程序需求保持一致来解决。修正这些问题后，请重新部署你的应用程序，并查看构建日志以确认问题已解决。

其他资源

• 如需更全面地了解如何阅读和解读部署日志，请参阅 排查 Node.js 部署失败 指南。
• 如果你的应用程序构建成功但运行时失败，请参阅 如何在 Hostinger 使用 Node.js 运行时日志。
• 如果你的 stderr.log 文件显示为空，请参阅 了解 Node.js 应用中 stderr.log 文件为空的原因。