discord.js 之 discordjs/builders 指南从零构建 Discord API 载荷与斜杠命令【免费下载链接】discord.jsA powerful JavaScript library for interacting with the Discord API项目地址: https://gitcode.com/gh_mirrors/di/discord.jsdiscordjs/builders是 discord.js 官方发布的工具包位于本仓库 packages/builders用于以类型安全、可链式调用的方式构建 Discord API 载荷涵盖斜杠命令、上下文菜单、按钮与选择菜单等消息组件、模态框、Embed 与投票等场景。读完本文你将掌握该包的安装要求、核心构建器的使用方法含斜杠命令、参数、子命令/子命令组并能理解其内部基于 zod 的校验机制与toJSON()输出原理为机器人开发打下坚实基础。一、这个包是做什么的A utility package for easily building Discord API payloads.Discord 的绝大多数交互功能斜杠命令、按钮、下拉菜单、模态框、Embed、投票等本质上都是一段特定的 JSON 结构。直接手写这些 JSON 不仅繁琐而且极易因字段拼写错误、枚举值超界等问题在运行时被 Discord API 拒绝。discordjs/builders把这一切封装为一组可链式调用的 Builder 类你像写普通代码一样设置名称、描述、选项最后调用toJSON()拿到可以直接发给 Discord 的原始数据。从 src/index.ts 的导出清单可以看到该包覆盖了四大类构建能力交互命令interactions/commands聊天输入命令斜杠命令、用户/消息上下文菜单消息组件components按钮、各类选择菜单字符串/用户/角色/频道/Mentionable、文本输入框、Action Row以及 v2 组件Section、MediaGallery、TextDisplay 等模态框interactions/modals供交互弹窗使用消息内容messagesEmbed、投票Poll、AllowedMentions、附件等。这些 Builder 大多通过ts-mixer的Mixin组合而成内部数据统一保存在data字段中最终由toJSON()序列化为与discord-api-types/v10中定义的 API 类型完全对齐的 JSON。当前仓库中该包版本为 1.11.1见 package.json。二、安装与环境要求Node.js 版本要求README 与 package.json 的engines字段均明确要求Node.js 24.17.0 或更高版本如果你的运行环境低于该版本请先升级 Node.js 再安装本包。安装命令该包是标准 npm 包三种主流包管理器均支持npm install discordjs/builders yarn add discordjs/builders pnpm add discordjs/builders依赖方面它内部依赖discord-api-types用于 API 类型定义、zod用于载荷校验、ts-mixer用于 Mixin 组合以及同仓库的discordjs/util安装时会自动处理。三、快速上手构建第一条斜杠命令官方在 packages/builders/docs/examples/Slash Command Builders.md 中给出了完整的入门示例。最基本的 ping 命令只需三行核心逻辑import { SlashCommandBuilder } from discordjs/builders; // 创建一条斜杠命令构建器 const pingCommand new SlashCommandBuilder().setName(ping).setDescription(Check if this interaction is responsive); // 拿到可以发送给 Discord 的原始数据 const rawData pingCommand.toJSON();要点拆解setName()设置命令名setDescription()设置命令描述——这两个方法来自SharedNameAndDescriptionmixin见 SharedNameAndDescription.tstoJSON()是每个 Builder 的核心出口。对斜杠命令而言它返回RESTPostAPIChatInputApplicationCommandsJSONBody类型见 ChatInputCommand.ts并且在序列化时会自动补全type: ApplicationCommandType.ChatInputrawData就是可以直接交给 REST API如REST#post注册全局/服务器命令或随交互响应发送的载荷。为什么用 Builder 而不是手写 JSON因为 Builder 在构建期就能拦截错误。从 ChatInputCommand.ts 可以看到toJSON()返回前会调用validate(chatInputCommandPredicate, data, validationOverride)用 zod schema 对最终载荷做一次完整校验不合法就直接抛出ValidationError而不是等到请求被 Discord 拒绝后才排查。四、为命令添加参数选项Options与选择Choices基础参数用户与整数官方示例的 boop 命令展示了如何添加不同类型的参数import { SlashCommandBuilder } from discordjs/builders; // 创建一个 boop 命令 const boopCommand new SlashCommandBuilder() .setName(boop) .setDescription(Boops the specified user, as many times as you want) .addUserOption((option) option.setName(user).setDescription(The user to boop).setRequired(true)) // 添加一个整数选项 .addIntegerOption((option) option.setName(boop_amount).setDescription(How many times should the user be booped (defaults to 1)), ) // 也支持 choices .addIntegerOption((option) option .setName(boop_reminder) .setDescription(How often should we remind you to boop the user) .addChoices({ name: Every day, value: 1 }, { name: Weekly, value: 7 }), ); // 获取最终可发送给 Discord 的原始数据 const rawData boopCommand.toJSON();这里演示了三种能力addUserOption()通过回调拿到选项构建器链式设置setName/setDescription并用setRequired(true)标记必填addIntegerOption()整数选项若不设置setRequired则默认可选addChoices()为选项预置候选值用户只能在给定候选中选择。choices 中name是展示给用户的文本value是实际传回的值。选项类型一览从源码目录 options 可以看出斜杠命令支持以下选项类型每种都有对应的addXxxOption()方法选项类型方法典型用途字符串addStringOption自由文本、带 choices 的枚举整数addIntegerOption整数值浮点数addNumberOption带小数的数值布尔值addBooleanOption开关用户addUserOption选择服务器成员频道addChannelOption选择频道可配合addChannelTypes限定类型角色addRoleOption选择角色MentionableaddMentionableOption用户或角色二选一附件addAttachmentOption上传文件数值类选项还可以通过setMinValue/setMaxValue限制取值范围见 mixins 目录中的 ApplicationCommandNumericOptionMinMaxValueMixin.ts字符串/整数等选项支持setAutocomplete(true)开启自动补全见 ApplicationCommandOptionWithAutocompleteMixin.ts。这些能力组合起来足以覆盖绝大多数命令需求。五、子命令与子命令组当命令逻辑复杂时Discord 支持把一条命令拆分为子命令subcommand甚至用**子命令组subcommand group**做二级分组。官方示例的 points 命令是标准范式import { SlashCommandBuilder } from discordjs/builders; const pointsCommand new SlashCommandBuilder() .setName(points) .setDescription(Lists or manages user points) // 添加一个 manage 子命令组 .addSubcommandGroup((group) group .setName(manage) .setDescription(Shows or manages points in the server) .addSubcommand((subcommand) subcommand .setName(user_points) .setDescription(Alters a users points) .addUserOption((option) option.setName(user).setDescription(The user whose points to alter).setRequired(true), ) .addStringOption((option) option .setName(action) .setDescription(What action should be taken with the users points?) .addChoices( { name: Add points, value: add }, { name: Remove points, value: remove }, { name: Reset points, value: reset }, ) .setRequired(true), ) .addIntegerOption((option) option.setName(points).setDescription(Points to add or remove)), ), ) // 添加一个 info 子命令组 .addSubcommandGroup((group) group .setName(info) .setDescription(Shows information about points in the guild) .addSubcommand((subcommand) subcommand.setName(total).setDescription(Tells you the total amount of points given in the guild), ) .addSubcommand((subcommand) subcommand .setName(user) .setDescription(Lists a users points) .addUserOption((option) option.setName(user).setDescription(The user whose points to list).setRequired(true), ), ), ); // 获取最终可发送给 Discord 的原始数据 const rawData pointsCommand.toJSON();这段代码体现的结构是points ├── manage子命令组 │ └── user_points子命令带 user / action / points 三个参数 └── info子命令组 ├── total子命令无参数 └── user子命令带必填 user 参数使用要点命令最外层一旦使用addSubcommand或addSubcommandGroup该命令就不再接受普通的addXxxOption二者互斥由 zod schema 保证子命令内部可以继续使用全部选项方法子命令组下只能挂子命令不能直接挂选项参数、choices 等在子命令层级完全复用组合非常灵活。子命令相关能力由 SharedSubcommands.ts 提供与命令本体通过 Mixin 组合保证toJSON()输出的结构始终合法。六、原理深挖toJSON 与 zod 校验很多使用者只把 builders 当作省事工具其实它内部有一套严谨的构建期校验管线值得理解链式设置阶段每个setXxx()方法只修改内部data对象的字段不做网络 I/O序列化阶段toJSON()对data做structuredClone深拷贝避免外部意外修改内部状态补全type等必需字段并对 options 递归调用各自toJSON()校验阶段调用validate(chatInputCommandPredicate, data, validationOverride)其中chatInputCommandPredicate是预定义的 zod schema一旦字段缺失、类型不符或枚举越界立即抛出ValidationError见 ValidationError.ts。校验开关集中在 validation.ts提供三个全局控制函数import { enableValidators, disableValidators, isValidationEnabled } from discordjs/builders; enableValidators(); // 开启校验默认开启 disableValidators(); // 关闭全局校验 isValidationEnabled(); // 查询当前状态此外toJSON()还接受可选的validationOverride布尔参数用于单次调用强制开启/跳过校验——源码中正是利用这一点让子选项序列化时跳过重复校验option.toJSON(false)最终只在顶层做一次完整校验兼顾正确性与性能。在追求极限性能的生产环境中可以全局disableValidators()关闭校验此时由调用方保证载荷合法这是该包设计上提供的灵活性。七、能力全景除了斜杠命令还能构建什么discordjs/builders不止于命令。结合 src/index.ts 的导出你可以构建消息组件components按钮PrimaryButtonBuilder/SecondaryButtonBuilder/SuccessButtonBuilder/DangerButtonBuilder/LinkButtonBuilder等见 button。前四者通过setCustomId()绑定回调标识LinkButtonBuilder通过setURL()跳转外链所有按钮都支持setLabel()/setEmoji()见 EmojiOrLabelButtonMixin.ts选择菜单StringSelectMenuBuilder可加StringSelectMenuOptionBuilder选项、UserSelectMenuBuilder、RoleSelectMenuBuilder、ChannelSelectMenuBuilder、MentionableSelectMenuBuilder文本输入框TextInputBuilder配合ModalBuilder构建弹窗Action RowActionRowBuilder用于承载一行内的组件一行最多 5 个按钮或 1 个选择菜单v2 组件ContainerBuilder、SectionBuilder、MediaGalleryBuilder、TextDisplayBuilder等新一代布局组件。模态框modalsModalBuilder与TextInputBuilder组合用于在交互弹窗中收集多字段输入。消息内容messagesEmbedEmbedBuilder支持标题、描述、字段、作者、页脚、缩略图、图片等完整结构见 embed投票PollBuilder配合PollAnswerBuilder、PollMediaBuilder等构建消息投票AllowedMentions / Attachment / MessageReference控制消息的提及范围、附件与引用关系。上述所有 Builder 都遵循同一设计哲学链式配置 →toJSON()→ 合法载荷。八、把构建结果交给谁toJSON()产出的数据是纯 JSON因此不依赖任何特定发送渠道在 discord.js 中可交给 REST 模块注册命令REST#post到 applications routes或通过Interaction的reply/update等 API 随交互响应发送组件也可以脱离 discord.js 单独用于其他运行时。包本身对运行时零耦合——这一点从 package.json 的依赖列表只有discordjs/util、discord-api-types、ts-mixer、tslib、zod即可看出。也正因如此官方在仓库内提供了tests目录用 vitest 对组件、交互、消息等构建器做全面的单元测试命令可通过pnpm --filter discordjs/builders test运行保证toJSON()输出的结构始终与discord-api-types/v10的类型定义一致。九、进一步阅读完整示例代码见 Slash Command Builders 示例包源码入口packages/builders/src/index.ts版本与工程配置packages/builders/package.json、tsup.config.ts类型与校验实现validation.ts、ValidationError.ts变更历史见 packages/builders/CHANGELOG.md该包遵循 Apache-2.0 许可见 LICENSE。如果你在升级旧版本v13 → v14时遇到 API 变动困惑也可参考本仓库 apps/guide/content/docs/legacy 中的更新指南类文档。遇到问题优先查阅上述源码与测试用例它们是理解构建器行为最权威的参照。【免费下载链接】discord.jsA powerful JavaScript library for interacting with the Discord API项目地址: https://gitcode.com/gh_mirrors/di/discord.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考