Mineflayer 快速上手指南：用 JavaScript 构建稳定、强大的 Minecraft 机器人

• 游戏开发

Mineflayer 是一个面向 Node.js 的高阶 Minecraft 机器人 API，它让你可以用十几行代码就能让一个机器人登录任意 Minecraft 服务器——自动聊天、挖掘方块、攻击生物、骑乘矿车、管理容器与附魔台，甚至用浏览器实时观察它的一举一动。读完本文，你将掌握 mineflayer 的安装方式、createBot核心配置、经典实战示例、底层模块架构，以及如何用官方测试体系验证某个 Minecraft 版本下机器人的行为。

本文内容以 docs/tr/README_TR.md 为主线，并结合仓库源码（index.js、lib/loader.js、lib/version.js 与 examples 目录）进行源码级佐证。

Mineflayer 概览与核心特性

Mineflayer 为 JavaScript 开发者提供了一套「强大、稳定、高阶」的 Minecraft 机器人 API。按照官方特性清单，其能力覆盖：

• 多版本支持：原文档声明支持 Minecraft 1.8、1.9、1.10、1.11、1.12、1.13、1.14、1.15、1.16、1.17、1.18、1.19、1.20 等版本。当前仓库的 lib/version.js 中，testedVersions数组已经扩展到 1.21.x 乃至 26.1，说明该项目的版本覆盖面仍在持续更新。
• 实体信息与追踪：感知并追踪周围的生物与玩家，包括矿车等载具。
• 方块信息：能够「环视四周」进行方块查询，定位某个方块仅需毫秒级耗时（对应bot.findBlock能力）。
• 物理与移动：完整处理游戏内的「虚拟碰撞箱」，支持行走、跳跃、潜行等控制。
• 攻击与载具：攻击生物、骑乘并操控载具。
• 背包管理：读写、排序、装备物品。
• 方块交互容器：工作台、箱子、发射器、附魔台等方块窗口。
• 挖放方块：按需挖掘与放置方块。
• 状态感知：获取生命值、判断是否下雨等环境状态。
• 物品使用与方块激活：右键使用物品、激活方块。
• 聊天：接收并发送聊天消息。

环境要求与安装

安装 mineflayer 只需一行命令：

npm install mineflayer

关于 Node.js 版本，原文档写的是「Node.js 14 或以上」，但需要注意：当前仓库的 package.json 中engines字段已声明"node": ">=22"，并且 index.js 在启动时会主动校验运行环境——若 Node 主版本小于 18，会直接打印提示并要求升级到 22.x 以上后退出。也就是说，以当前仓库为准，请使用 Node.js 22 或更高版本来运行 mineflayer 项目。

安装完成后，仓库的package.json中main指向index.js，index.js再导出 lib/loader.js 中的createBot函数——这是你与 mineflayer 打交道的第一入口。

文档与 Wiki 导航

原文档为使用者准备了完整的学习路径，以下链接均已转换为仓库根目录下的相对路径：

如果你有意参与贡献，请先阅读 CONTRIBUTING.md 以及 prismarine-contribute 指南（后者为外部项目，可在原文档中查看其链接）。

快速开始：创建你的第一个机器人

createBot 配置项速查

createBot(options)是机器人的唯一入口。仓库 lib/loader.js 中为未传入的选项提供了默认值，结合原文档注释，常用配置如下：

需要注意version的自动探测逻辑：从 lib/loader.js 可以看到，连接建立后 mineflayer 会读取服务器协商出的协议版本，再通过prismarine-registry加载对应版本数据；若服务器版本超出仓库支持范围（低于 lib/version.js 中的oldestSupportedVersion或高于latestSupportedVersion），会直接抛出「版本不受支持」的错误。

鹦鹉示例：让机器人复读你的话

原文档给出的入门示例，是一个会模仿（复读）玩家聊天内容的「鹦鹉」机器人：

const mineflayer = require('mineflayer') const bot = mineflayer.createBot({ host: 'localhost', // 服务器 IP 地址 username: 'email@example.com', // Minecraft 用户名 / 邮箱地址 password: '12345678' // Minecraft 密码，离线服务器可留空 // port: 25565, // 仅当端口不是 25565 时使用 // version: false, // 需要指定版本时取消注释并填入版本号 // auth: 'mojang' // 使用 Microsoft 账号时改为 'microsoft' }) bot.on('chat', (username, message) => { if (username === bot.username) return bot.chat(message) }) // 将错误与被踢出服务器的原因打印到控制台： bot.on('kicked', console.log) bot.on('error', console.log)

这段代码演示了两个最重要的概念：

1. bot.on('chat', ...)事件监听：每当有玩家说话，回调会收到说话者username与消息内容；通过if (username === bot.username) return避免机器人复读自己的发言，再调用bot.chat(message)把消息原样发回聊天频道。
2. 错误兜底：kicked事件携带被服务器踢出的原因，error事件捕获连接层错误。在 lib/loader.js 中可以看到，connect、error、end等底层minecraft-protocol客户端事件会被重新转发为 bot 上同名事件，因此你的监听器能拿到完整信息。

用 prismarine-viewer 实时观察机器人

调试机器人时「看不见它在干什么」是最头疼的问题。原文档推荐使用prismarine-viewer在浏览器标签页里实时观察 bot 的视角。

npm install prismarine-viewer

然后在 bot 代码中加入：

const { mineflayer: mineflayerViewer } = require('prismarine-viewer') bot.once('spawn', () => { mineflayerViewer(bot, { port: 3007, firstPerson: true }) // port: 视频流端口；firstPerson: true 为第一人称视角，false 为俯视（鸟瞰）视角 })

bot.once('spawn', ...)保证在机器人成功进入服务器后才启动可视化。仓库中的 examples/viewer/viewer.js 提供了完整可运行版本，其命令行用法为：

node viewer.js <host> <port> [<name>] [<password>]

启动后打开浏览器访问http://localhost:3007即可看到画面，其中默认使用firstPerson: false的鸟瞰视角。原文档还提到，作者提供的 YouTube 视频教程展示了「live 画面」的效果，并附有四个教学视频链接（含配套源码仓库），这些外部资源可在原文档 docs/tr/README_TR.md 中直接查看。

更多实战示例：从示例代码理解 API 用法

原文档用一张示例清单展示了各种能力，以下链接均已转换为仓库根目录下的相对路径：

仓库的 examples 目录还包含更多示例（如attack.js、fisherman.js、farmer.js、auto-eat.js、elytra.js等），以下挑几个关键示例深入说明其源码实现：

挖掘方块：digger

examples/digger.js 演示了「挖掉脚下方块、再用泥土搭柱子返回地面」的完整流程。核心调用链是：

const target = bot.blockAt(bot.entity.position.offset(0, -1, 0)) // 取脚下方块 if (target && bot.canDigBlock(target)) { await bot.dig(target) // 挖掘，等待完成 }

其中bot.entity.position.offset(0, -1, 0)表示把自身坐标沿 Y 轴下移 1 格，bot.canDigBlock用于校验能否挖掘，await bot.dig(target)是异步挖掘操作。示例还展示了bot.waitForChunksToLoad()（等待区块加载完毕）、bot.setControlState('jump', true)（控制跳跃）与bot.placeBlock(referenceBlock, vec3(0, 1, 0))（放置方块）等 API，这些正好对应原文档特性清单中的「物理与移动」「挖放方块」能力。

移动、跳跃与骑乘：jumper

examples/jumper.js 通过聊天命令控制机器人，展示了控制状态与载具 API 的典型用法：

• bot.setControlState('forward', true)/bot.setControlState('back', true)等：分别设置前进、后退、左右平移、疾跑、跳跃等控制状态；bot.clearControlStates()一次清除全部。
• bot.attack(entity, true)：攻击附近的实体（bot.nearestEntity()获取最近的实体）。
• bot.mount(entity)/bot.dismount()：骑乘/离开载具（如矿车）。
• bot.moveVehicle(x, z)：以向量参数操控载具的前进/后退/转向。
• bot.lookAt(position)：让 bot 注视某个坐标（示例中用它实现「死死盯着目标玩家」的效果）。

容器与方块窗口：chest

examples/chest.js 覆盖箱子、末影箱、陷阱箱、熔炉、发射器与附魔台的完整交互：

• bot.findBlock({ matching, maxDistance })：按方块 ID 列表在指定距离内查找方块，这正是「寻找方块仅需毫秒」特性的实现入口。
• bot.openContainer(block)：打开箱子/发射器等容器，返回的窗口对象支持containerItems()、withdraw(item.type, null, amount)（取出）、deposit(...)（存入），以及updateSlot、close事件。
• bot.openFurnace(block)：熔炉窗口支持putInput/putFuel/takeOutput，并可通过furnace.fuel、furnace.progress读取燃料与烧炼进度。
• bot.openEnchantmentTable(block)：附魔台支持putTargetItem、putLapis（放入青金石）、enchant(choice)（选择附魔项）与takeTargetItem（取回成品）。

批量账号登录：multiple_from_file

examples/multiple_from_file.js 读取一个每行格式为username:password的账号文件，为每个账号创建一个 bot，并用setTimeout按interval（默认 500ms）错峰登录，避免短时间内并发连接被服务器拒绝。它利用Promise.allSettled收集成功/失败的登录结果，并统计成功数量。

模块化架构：Mineflayer 的构建基石

原文档明确强调：mineflayer 的大量活跃开发发生在它依赖的一批小型 npm 包中，这一设计理念被作者称为 "The Node Way™"。

"When applications are done well, they are just the really application-specific, brackish residue that can't be so easily abstracted away. All the nice, reusable components sublimate away onto github and npm where everybody can collaborate to advance the commons." — substack《how I write modules》

也就是说，mineflayer 本体只保留「应用特定」的胶水逻辑，而把可复用的底层能力拆分为独立模块。这些模块大部分正是当前仓库 package.json 中声明的dependencies：

此外，从 lib/loader.js 的源码结构看，mineflayer 还把功能拆成约 40 个内置插件（plugin），如blocks、chat、chest、digging、physics、health、inventory、craft、fishing、villager、anvil等，每个插件对应 lib/plugins 目录下的一个文件。createBot在初始化时会先通过pluginLoader加载插件，再合并内置插件与用户通过options.plugins传入的外部插件（lib/loader.js）。这套「核心 + 插件」的架构，正是后续「第三方插件生态」得以繁荣的根基。

调试技巧：开启协议层日志

遇到连接类问题时，可以借助DEBUG环境变量输出协议层的调试日志：

DEBUG="minecraft-protocol" node [...]

Windows 环境下使用set命令：

set DEBUG=minecraft-protocol node your_script.js

设置后，控制台会打印 minecraft-protocol 的收发数据包等详细信息，是排查「连不上服务器」「版本不匹配」「数据包解析失败」类问题最直接的抓手。

第三方插件生态

mineflayer 原生支持插件机制——任何人都可以编写插件，在 mineflayer 之上叠加更高阶的 API。原文档列出了一些较为活跃、实用的第三方插件（均为外部独立项目，链接见原文档）：

原文档还提到更多可关注的项目，包括：基于 canvas 与 socket.io 的浏览器雷达界面（radar）、3D 世界方块查找（blockfinder）、放置/挖掘方块铺路抵达目标（scaffold）、聊天式自动登录（auto-auth）、伤害来源归因分析（Bloodhound）、获取服务器 TPS（tps）、拍摄世界全景照片（panorama）。这些项目均为外部链接，请在原文档 docs/tr/README_TR.md 中查看对应地址。

使用 Mineflayer 构建的开源项目

原文档还列举了一批基于 mineflayer 的真实项目，可为你设计自己的机器人提供参考：

• rbot：建筑类机器人（示例视频包含「建造螺旋楼梯」「模仿建筑结构」等场景）。
• Helperbot：辅助型机器人。
• mineflayer-voxel：结合 voxel.js 可视化 bot 行为。
• Skynet：把 bot 活动上报到在线 API。
• MinecraftChat：Minecraft 网页聊天工具。
• Cheese Bot：基于 node-webkit、带干净界面的插件式 bot。
• Chaoscraft：使用遗传算法的 Minecraft bot。
• minetelegram：基于 mineflayer 与 telegraf 的 Minecraft↔Telegram 桥接。
• mineflayer-builder：在生存模式下按 Minecraft 蓝图（schematic）建造建筑的项目。
• 更多使用 mineflayer 的项目可以通过原文档给出的 GitHub dependents 页面查看。

测试：验证特定版本下的机器人行为

仓库为每个版本都准备了完整的集成测试体系，原文档给出了三条核心测试命令：

运行全部测试

npm test

根据 package.json 的 scripts 定义，npm test实际会先执行pretest中的 lint（standard+standard-markdown代码风格检查），再通过mocha --reporter ./test/common/durationsReporter.js --exit运行测试套件。

测试特定 Minecraft 版本

npm test -- -g <version>

其中<version>需要是一个 Minecraft 版本号，例如1.12、1.15.2。这与 lib/version.js 中testedVersions列出的版本一一对应（当前仓库已覆盖 1.8.8 至 1.21.x 及 26.1）。

测试特定功能

npm test -- -g <test_name>

其中<test_name>是测试用例名，例如bed、useChests、rayTrace。仓库 test/externalTests 目录下就对应着这些测试文件（如bed.js、useChests.js、rayTrace.js、digAndBuild.js、scoreboard.js等），你可以直接阅读它们来了解某个功能在真实服务器上的预期行为——这也是学习 mineflayer API 的极佳素材。

许可证

Mineflayer 使用 MIT 许可证，允许自由使用、修改与再分发。

小结：从npm install mineflayer到createBot一行登录，再到dig、openContainer、mount等实战 API，以及「核心 + 插件」的模块化架构与可版本化的测试体系，本文覆盖了 docs/tr/README_TR.md 的全部要点，并用仓库源码进行了印证。下一步建议通读 docs/api.md 与 docs/tutorial.md，并对照 examples 目录逐个运行示例，亲手打造你的第一个 Minecraft 机器人。

• 游戏开发