Discord 机器人错误：无效 Token、Intents、Lavalink

​

“LoginFailure: Improper token has been passed” / TokenInvalid

• discord.py： discord.errors.LoginFailure: Improper token has been passed.
• discord.js v14： Error [TokenInvalid]: An invalid token was provided.
• 旧版 discord.js： Error [TOKEN_INVALID]: An invalid token was provided.
• 其他库： 登录时返回 HTTP 401 Unauthorized。

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

1. 前往开发者门户 → 你的应用 → Bot → Reset Token。
2. 在应用的环境变量中更新令牌（控制面板的 Settings → Environment Variables，或使用 squarecloud app env set）。切勿将令牌提交到会被上传到 zip 中的文件里。
3. 仔细检查该值周围是否有多余的空格或引号。
4. 更新库版本（discord.js@latest 或 pip install -U discord.py）。
5. 重启应用，让它加载新的值。

​

“Used disallowed intents” / Message Content Intent

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

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

# discord.py
intents = discord.Intents.default()
intents.message_content = True
client = commands.Bot(command_prefix="!", intents=intents)

3. 重启应用。

​

Lavalink connection closed with code 1006

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

​

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

• 网关层的连接不稳定，且没有重连处理。
• 你本地测试的依赖版本与依赖文件中的版本冲突或不兼容。
• 机器人因超出 RAM 或 CPU，或因向 Discord API 发送过多请求而被停止。这种情况下日志中会出现一行 [SQUARE-SHIELD]，你也会收到一封邮件：参见状态表。

1. 首先查看控制面板中的应用日志，它们会显示实际的崩溃原因。
2. 添加错误处理程序，避免瞬时错误使进程崩溃：discord.js 中的 process.on("unhandledRejection", ...) 和 client.on("error", ...)，discord.py 中的等效处理方式。
3. 在 squarecloud.app 中添加 AUTORESTART=true，让 Square Cloud 在机器人崩溃后重启它。该选项默认关闭，并且只会在 AUTORESTART 中列出的情况下重启。它能让机器人在瞬时错误中保持存活，但永远无法修复无效的令牌、语法错误或缺失的依赖：这些仍需要在代码中修复。
4. 留意 Discord API 速率限制（429）：全局限制约为每个机器人令牌每秒 50 个请求，各路由还有更严格的限制（例如频道创建/编辑大约每个频道每 10 分钟允许 2 次更改）。请积极使用缓存，使用能遵循 X-RateLimit-Remaining/X-RateLimit-Reset-After 响应头的异步队列，并对批量发送使用 webhook。持续向 Discord 发送过多请求的机器人会以 ABUSE_REQUESTS 被停止。

​

相关指南

• Discord 机器人托管教程：从零开始设置并部署机器人。
• 环境变量：把令牌存放在代码之外。
• 应用无法启动：上传错误、缺失模块以及其他启动失败。

​

联系我们