应用无法启动：部署、网站与启动错误

如果你的应用在上传时被拒绝、启动时崩溃，或者始终没有响应，错误代码或控制台日志几乎总会指出确切的问题。请对照下方内容。

​

上传和部署错误

当 Square Cloud 拒绝一次上传时，控制面板、CLI 或 API 会返回这些代码。此时不会部署任何内容，请修复原因后重新上传。

​

INVALID_DEPENDENCY

含义： 上传内容中没有其语言对应的依赖文件，或者该文件为空。Square Cloud 在安装任何内容之前，会检查该文件是否位于 zip 的根目录。 如何修复： 将依赖文件放在 zip 的根目录，与 squarecloud.app 放在一起，并确保它不为空：package.json（Node.js、Bun、Deno）、requirements.txt 或 pyproject.toml（Python）、Cargo.toml（Rust）、Gemfile（Ruby）、go.mod 或 go.work（Go）或 mix.exs（Elixir）。然后重新上传。拼写错误的包名或版本会在之后以安装错误的形式出现在日志中。

​

KEEP_CALM

含义： 你或某个自动化流程重复某个操作（例如重启、上传或 snapshot）的速度太快。 如何修复： 稍等片刻后重试。被拒绝的操作只是没有执行：KEEP_CALM 永远不会停止或影响正在运行的应用。如果 snapshot 改为以 DAILY_SNAPSHOTS_LIMIT_REACHED 失败，说明你套餐当天的 snapshot 额度已用完，需要等到第二天。

​

网站无法加载

含义： 应用已经部署，但打开它的地址时显示的是以下页面之一，而不是你的网站：

• “The website took too long to respond”：Square Cloud 找到了你的应用，但没有收到它的响应。
• “This site couldn’t be found”：该地址上没有发布任何网站。

如何修复超时：

1. 让你的服务器监听 80 端口和主机 0.0.0.0。绑定到 localhost、127.0.0.1 或其他端口（3000、5173、8080 等）的服务器无法被访问。运行时已把 PORT 和 HOST 环境变量设置为这两个值，直接读取即可：
   Node.js (Express)

   Python (Flask)

   app.listen(process.env.PORT || 3000, process.env.HOST || "0.0.0.0", () => {
     console.log("Server running");
   });
   
2. 打开日志：如果应用崩溃了，或者仍在安装依赖或构建，网站就还无法响应。请修复日志中显示的错误，或等待构建完成。
3. 检查 MEMORY 是否给构建留出了足够的空间：内存不足的框架构建会让应用以 LACK_OF_RAM 停止。

如何修复 “This site couldn’t be found”：

1. 检查地址：它是 https://<SUBDOMAIN>.squareweb.app，其中的子域名来自你的配置文件。
2. 如果刚刚部署，请等待最多一分钟，让地址完成发布。
3. 没有设置 SUBDOMAIN 就部署的应用不是网站，也无法变成网站：请设置 SUBDOMAIN 后把它作为新应用重新上传。
4. 如果使用自定义域名，DNS 可能仍在传播中。参见为什么你的域名还没有生效。

​

EADDRINUSE（端口已被占用）

含义： 应用尝试将同一个网络端口绑定两次。 发生原因： 代码中启动了两个服务器，或者某个 listen(...) 调用在事件处理程序内部被再次创建（例如每次请求或每次重新连接时），而不是只在启动时创建一次。 如何修复：

1. 只启动一个 web 服务器，且只启动一次，监听端口 80 和主机 0.0.0.0。
2. 在代码中查找是否有多个 .listen()（Node.js）或 run()（Python/Flask/Django）调用，并删除多余的那个。
3. 确保 listen 调用位于启动文件的顶层，而不是在可能多次触发的回调内部。

​

“Cannot find module”（Node.js）和 ModuleNotFoundError（Python）

含义： 代码中引入的某个包没有被安装。 发生原因：

• 该库未列在 package.json 的 dependencies（Node.js）或 requirements.txt/pyproject.toml（Python）中，因此即使在你本机可以运行，平台上也不会安装它。
• 在 Node.js 中，该包只列在 devDependencies 中。应用以 NODE_ENV=production 运行，因此 npm install 会跳过开发依赖。

如何修复：

1. 将缺失的包及有效版本号添加到 dependencies（或你的 Python 依赖文件）中。
2. 确认依赖文件本身已包含在你上传的 zip 中。
3. 重启应用。对于 Node.js，只有在 node_modules 不存在时才会安装依赖：请在控制面板的文件管理器中删除 node_modules（如果你上传过 package-lock.json，也一并删除），然后重启，进行一次干净的重新安装。

​

better-sqlite3 / 原生绑定错误

含义： 当你的应用使用 better-sqlite3（直接使用，或通过 quick.db）时出现类似 Could not locate the bindings file 的错误。 发生原因： 已安装的 better-sqlite3 版本早于平台当前的 Node.js LTS 版本，因此其预编译的原生绑定与运行时不匹配。 如何修复：

1. 将 better-sqlite3 更新到 12.5.0 或更高版本（如果你使用 quick.db，请将其更新到 9.1.7 或更高版本）。
2. 删除 node_modules 和 package-lock.json。
3. 重启应用以进行干净的重新安装，从而针对当前运行时重新构建原生绑定。

​

因资源限制而停止

如果日志以 [SQUARE-SHIELD] LACK_OF_RAM、LACK_OF_CPU 或 ABUSE_REQUESTS 结尾，或者启动应用时以 CONTAINER_TEMPORARILY_SUSPENDED 失败，说明 Square Cloud 因为应用超出资源而停止了它。状态表解释了每一种状态及其修复方法。

​

时间差了几个小时

应用以 UTC 时间运行。安排在 09:00 的任务会在 UTC 09:00 运行，代码打印到日志中的时间也是 UTC。请在代码中转换时间，或参阅帮助中心的如何更改应用的时区。

​

相关指南

• 配置文件：每个字段及其可能引发的错误。
• 环境变量：设置密钥，然后重启使其生效。
• Discord 机器人错误和数据库连接错误。

​

联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud 4.9/5 评分（共 402 条评价）（Google 与 Trustpilot）的重要原因之一。