> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud 应用无法启动：EADDRINUSE、Cannot Find Module、INVALID_DEPENDENCY

> 修复 Square Cloud 上的 EADDRINUSE 端口已被占用、Cannot find module / ModuleNotFoundError、INVALID_DEPENDENCY、CONTAINER_TEMPORARILY_SUSPENDED、KEEP_CALM、better-sqlite3 绑定错误以及 LACK_OF_RAM。

如果你的应用在启动时崩溃，或始终无法上线，控制台日志几乎总会指出确切的问题。请对照下方的错误信息。

## EADDRINUSE（端口已被占用）

**含义：** 应用尝试将同一个网络端口绑定两次。

**发生原因：** 代码中启动了两个服务器，或者某个监听器/`app.listen(...)` 调用在事件处理程序内部被再次创建（例如每次请求或每次重新连接时），而不是只在启动时创建一次。

**如何修复：**

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

```javascript theme={null}
// Correct: one listener, at the top level
app.listen(80, "0.0.0.0", () => {
  console.log("Server running");
});
```

<Note>Square Cloud 的动态应用必须绑定到主机 `0.0.0.0` 和端口 `80`。绑定到 `localhost`/`127.0.0.1` 或其他端口会导致站点超时，而不是正常启动。</Note>

## "Cannot find module"（Node.js）和 ModuleNotFoundError（Python）

**含义：** 代码中引入的某个包在依赖文件中缺失。

**发生原因：** 该库未列在 `package.json` 的 `dependencies`（Node）或 `requirements.txt`/`pyproject.toml`（Python）中，因此即使在你本机可以运行，平台上也不会安装它。

**如何修复：**

1. 将缺失的包及有效版本号添加到依赖文件中。
2. 确认依赖文件本身已包含在你上传的 `.zip` 中。
3. 重启应用。对于 Node.js，彻底重装需要先清除 `node_modules`（删除它和 `package-lock.json`，然后重启），这样平台才会从干净的状态重新安装。

## INVALID\_DEPENDENCY

**含义：** 部署失败，因为依赖文件中的某一项不存在，或指向了一个无效/不可用的版本。

**如何修复：** 打开 `package.json` / `requirements.txt` / `pyproject.toml`，修正被标记条目中拼写错误的包名或版本范围，然后重新部署。

## CONTAINER\_TEMPORARILY\_SUSPENDED

**含义：** 容器被平台暂停。

**发生原因：** 该状态由自动资源滥用防护触发，最常见的情况有：

* **OOM（内存不足）：** 应用尝试超出其配置的 `MEMORY`，进程被终止。
* **CPU 滥用：** 应用持续超出其分配的 CPU，进程为保护节点而被暂停。
* **请求滥用：** 触发了针对 `.squareweb.app` 域名或消息类 API（Discord、Telegram、WhatsApp）流量的安全上限，这几乎总是由无限循环或缺失缓存导致，而非真实的高人气。

**如何修复：** 查看与你账户关联的邮箱，其中会说明触发暂停的具体原因。然后在重启之前修复根本原因（内存泄漏、死循环，或失控的请求模式）。

## KEEP\_CALM

**含义：** 某个与 snapshot 相关的操作被请求得过于频繁。

**发生原因：** 要么你（或某个自动化流程）在平台短暂的 snapshot 请求冷却时间结束前再次请求了 snapshot，要么该账户当前套餐的每日 snapshot 上限已达到。请注意这与 `DAILY_SNAPSHOTS_LIMIT_REACHED` 不同，后者专门标记套餐的每日配额已耗尽：`KEEP_CALM` 也可能在较短的单应用请求冷却期内触发，与每日计数无关。

**如何修复：** 等待几分钟后重试。如果是达到了每日上限，请等到第二天，或升级套餐以获得更高的自动 snapshot 额度。

## 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. 重启应用以进行干净的重新安装，从而针对当前运行时重新构建原生绑定。

## LACK\_OF\_RAM

**含义：** 应用超出了其分配的 RAM，或内核发出了内存不足信号，进程被终止以保护宿主机的稳定性。

**如何修复：**

1. 使用性能分析工具查找内存泄漏（Node.js：`--inspect`，Python：`memory_profiler`）。
2. 将内存中的缓存迁移到 Redis 或其他外部存储，而不是让进程内缓存/Map 无限增长。
3. 在控制面板中增加分配给你应用的 `MEMORY` 值。

关于 RAM 最低要求、CPU 分配以及网络/存储限制的完整说明，请参见[限制与约束页面](/zh/platform/limitations-and-restrictions#lack_of_ram)。

<Tip>对照上述错误检查日志后仍无法解决？我们的支持团队可以与你一起查看具体的崩溃情况。</Tip>

## 联系我们

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