> ## 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 上的 Discord 机器人错误：LoginFailure、被禁用的 Intents、Lavalink 1006

> 修复 LoginFailure Improper token has been passed、TOKEN_INVALID、Used disallowed intents、Message Content Intent、Lavalink connection closed with code 1006，以及 Square Cloud 上 Discord 机器人离线的问题。

Square Cloud 上的 Discord 机器人错误通常可以追溯到令牌、网关 intents，或与 Lavalink 的版本不匹配。请对照下方确切的错误信息。

## "LoginFailure: Improper token has been passed" / TOKEN\_INVALID

**含义：** 库拒绝了你用于登录的令牌（discord.js 抛出 `LoginFailure`/"An invalid token was provided"；其他技术栈会返回 401 `TOKEN_INVALID`）。

**发生原因：**

* 令牌在 Discord 开发者门户中被重新生成或撤销。生成新令牌会立即使旧令牌在所有使用它的地方失效。
* 令牌字符串中不小心复制进了多余的空格或引号。
* 代码读取了错误的环境变量。

**如何修复：**

1. 前往[开发者门户](https://discord.com/developers/applications) → 你的应用 → **Bot** → **Reset Token**。
2. 在 Square Cloud 控制面板中，更新该应用的**环境变量**里的令牌。切勿将令牌提交到会被上传到 `.zip` 中的文件里。
3. 仔细检查该值周围是否有多余的空格或引号。
4. 更新库版本（`discord.js@latest` 或 `pip install -U discord.py`）。
5. 重启应用。

<Warning>切勿在源文件中硬编码你的机器人令牌。请始终从控制面板中设置的环境变量读取它。</Warning>

## "Used disallowed intents" / Message Content Intent

**含义：** 机器人登录成功并显示在线，但会忽略所有消息，或者网关以 "used disallowed intents" 拒绝连接。

**发生原因：** 自 2022 年起，**Message Content** 成为特权 intent。如果没有在两处都明确启用它，消息内容将为空（或者如果你的代码声明了一个该应用未启用的 intent，网关连接会被拒绝）。

**如何在两处都修复：**

1. Discord 开发者门户 → 你的应用 → **Bot** → **Privileged Gateway Intents** → 启用 **Message Content Intent**。
2. 同时在代码中声明它：

```javascript theme={null}
// discord.js
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});
```

```python theme={null}
# discord.py
intents = discord.Intents.default()
intents.message_content = True
client = commands.Bot(command_prefix="!", intents=intents)
```

3. 重启应用。

<Note>一旦机器人加入的服务器超过 100 个，特权 intents（包括 Message Content）还需要在同一个开发者门户页面申请 Discord 的审批。</Note>

## Lavalink connection closed with code 1006

**含义：** 机器人的 Lavalink 客户端异常关闭了 WebSocket 连接，代码为 1006，通常之前还会出现 "Unexpected server response: 400"。

**发生原因：** 这是版本不匹配导致的。Lavalink v4 基于 REST，与为 v3 构建的客户端封装库不兼容，因此握手失败，连接以 1006 关闭。

**如何修复：**

1. 使机器人的 Lavalink 客户端封装库版本与 Lavalink 服务器的主版本保持一致（v3 客户端配 v3 服务器，v4 客户端配 v4 服务器）。
2. 在 Square Cloud 上，Lavalink 服务器本身绑定端口 `80`，但你的机器人必须通过边缘节点的端口 `443` 并设置 `secure: true` 来连接它。
3. 修复版本不匹配问题后，重启 Lavalink 应用和机器人应用两者。

关于完整的 Lavalink 托管配置（配置文件、端口、部署方式），请参见 [Lavalink 服务器教程](/zh/tutorials/how-to-create-your-lavalink-server)。

## 机器人在本地正常运行，但部署后离线

**含义：** 机器人在你本机运行时登录正常，但部署后离线（或反复重启）。

**最常见的发生原因：**

* 网关层的连接不稳定，且没有重连处理。
* 你本地测试的依赖版本与依赖文件中的版本冲突或不兼容。
* 由于过于频繁地触及速率限制，触发了 Discord API 滥用检测（此时账户会收到通知邮件）。

**如何修复：**

1. 首先查看控制面板中的应用日志，它们会显示实际的崩溃原因。
2. 添加错误处理程序，避免瞬时错误使进程崩溃：discord.js 中的 `process.on("unhandledRejection", ...)` 和 `client.on("error", ...)`，discord.py 中的等效处理方式。
3. 当上一次运行时长超过 60 秒、退出状态为 1，且过去 60 分钟内尚未自动重启过时，Square Cloud 会自动重启崩溃的应用（清单中的 `AUTORESTART`）。这能让机器人在瞬时错误中保持存活，但永远无法修复底层的代码错误、语法错误或缺失的依赖，这些仍需要在代码中修复。
4. 留意 Discord API 速率限制（429）：全局限制约为每个机器人令牌每秒 50 个请求，各路由还有更严格的限制（例如频道创建/编辑大约每个频道每 10 分钟允许 2 次更改）。请积极使用缓存，使用能遵循 `X-RateLimit-Remaining`/`X-RateLimit-Reset-After` 响应头的异步队列，并对批量发送使用 webhook。

关于从零开始的完整设置，请参见 [Discord 机器人托管教程](/zh/tutorials/bots/discord)。

<Tip>如果日志没有指出明确的原因，我们的支持团队可以帮你进一步排查。</Tip>

## 联系我们

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