如果你玩《我的世界》Java版，多少会听说过Mod，比如Forge、Fabric。但你未必留意过，从1.13版本开始，原版游戏里就内置了一套非常灵活的“官方改版机制”——数据包（Data Pack）。它的定位很有意思：不装任何第三方加载器、不改游戏本体文件，只用几个JSON文件和一行行命令，就能往游戏里加新内容、改旧逻辑。这条路线比学Java写Mod要轻得多，也比单一命令方块更像一个正经工程。
我最初接触数据包，是因为在服务器里当腐竹，想给玩家加一点“死后不掉落背包”的规则。当时第一反应是去找插件，后来发现纯原版靠数据包就能做到，而且整个包不过几个文本文件，改起来极其方便。从那以后，我陆续用数据包做过挖矿奖励、自定义合成配方、RPG职业系统，甚至给朋友做过一个“挖到钻石全服播报”的小功能，整个过程几乎不碰Java代码。
这篇教程就围绕“第一个数据包”来写。你可以从中搞清楚数据包的目录结构、pack.mcmeta怎么写、函数（function）和标签（tag）怎么配合、如何加载调试，再跟着一个“挖矿有惊喜”的小例子，亲手跑通一个能用的数据包。适合完全没接触过数据包、但会基本游戏命令的玩家，也适合想在服务器里快速实现自定义玩法、又不想折腾插件的服主参考。
1. 数据包能干什么？先搞清楚它和Mod的边界
很多人一听到“数据包”，第一反应是“这是不是一种Mod？”。严格来说不是。数据包是Mojang官方设计的扩展机制，它的核心思路不是修改游戏代码，而是用数据驱动游戏内容。也就是说，你通过JSON文件告诉游戏“某个战利品表该怎么生成”“某个进度该怎么触发”“某个方块属于哪一类”，游戏就会按照你的数据去执行。
1.1 官方原生的轻量玩法扩展机制
数据包从1.13快照17w43a开始加入游戏，随后逐步接管了越来越多的原版内容。到今天，它已经能覆盖的东西包括：
- 函数（function）：批量执行命令的脚本文件，可以按tick循环调用，也可以由进度、命令等触发。
- 标签（tag）：给物品、方块、实体类型等归类，方便统一引用。
- 战利品表（loot table）：控制方块挖掘掉落、实体击杀掉落、箱子结构生成。
- 配方（recipe）：自定义合成表、烧炼配方。
- 进度（advancement）：不仅是成就系统，还是很好用的事件触发器，可以当作“回调函数”用。
- 维度、世界生成、结构等更底层的内容，也可以通过数据包覆盖。
这意味着，你不需要懂Java语法，只需要掌握JSON格式和游戏命令，就能实现很多以前必须靠Mod才能完成的功能。当然，数据包也有边界，比如它不能新增基础的游戏机制、不能改变渲染，复杂逻辑到了后面会显得比较绕。但作为原生的“官方Mod接口”，它的稳定性和兼容性非常出色。
1.2 三个高频玩法场景：从服务器小功能到单机RPG
我实际用数据包做过的功能里，有三个场景我觉得特别典型，适合新手理解它的能力边界。
第一个是服务器规则类功能。比如“玩家死亡不掉落”“不能对特定方块使用打火石”“统计挖矿数量并触发全服公告”，这类功能用数据包做非常顺手。你不需要装插件，不需要权限插件，只要把函数挂到tick标签里，再配几个记分板条件就行。
第二个是玩法增强类功能。比如我给服务器做过一个“挖掘有惊喜”的包，玩家每挖20个石头就会额外掉落一颗钻石，并且头顶飘出提示文字。把这个需求拆开来看，就是“记分板统计挖掘次数”加“每N次触发奖励函数”，整个过程没有一条命令是复杂的。
第三个是单机RPG化。比如自定义一件武器的属性、做一个“右键触发技能”的效果，甚至用进度系统串联一段任务线。数据包虽然不能改变物品的渲染，但可以通过附魔、隐藏属性、自定义NBT做到很多“看起来像Mod”的效果。这类玩法对格式要求比较高，但恰恰是数据包进阶最有趣的方向。
2. 开工前准备：游戏版本、Java环境与数据包目录骨架
数据包最劝退新手的地方，其实是“文件放哪、文件里写什么、怎么让游戏认出来”这三件事。但只要把目录结构这个基础打牢，后续一万个功能都是在这个骨架上长肉的。
2.1 选对版本和启动器
先说我个人的建议：数据包开发尽量用较新的Java版版本，至少1.18以上。太老的版本里很多功能不完整，而1.20.2之后又发生过函数标签路径的调整，如果从旧教程复制代码，很容易踩到“路径变了”这种坑。
启动器方面，官方启动器当然可以，但国内玩家常用的HMCL、PCL2这类第三方启动器也很方便，它们对多版本管理、Mod/数据包安装的体验都做得很好。如果你是从零开始，请先确认自己的游戏能正常启动，并且能在版本列表里看到准确的版本号。这一步很关键，因为后面的pack_format版本号必须和游戏版本严格对应。
顺带一提，Java环境直接用启动器自动选择的版本就行。实际上玩Minecraft Java版本身就需要Java运行时，HMCL等启动器一般会帮你自动配置，不用太纠结JAVA_HOME这类环境变量问题。如果你有报错提示找不到Java，那才需要去单独配置环境变量。
2.2 数据包的目录结构：规则比命名更重要
数据包本质上是一个文件夹，或者一个压缩后的zip包，内部结构有严格约定。下面这个骨架是最小可运行版本，你新建一个文件夹，比如叫MyFirstPack，然后按这个结构创建：
MyFirstPack/ ├── pack.mcmeta └── data/ ├── minecraft/ │ └── tags/ │ └── function/ │ ├── load.json │ └── tick.json └── demo/ └── functions/ ├── load.mcfunction ├── tick.mcfunction └── reward.mcfunction简单解释一下规则：
pack.mcmeta必须位于包根目录，它是整个数据包的“身份证”。data/下按命名空间（namespace）组织内容。minecraft命名空间通常用来覆盖原版内容，比如注册函数标签；demo这种自定义命名空间用来放自己的函数、进度、战利品表等，避免和原版冲突。functions/文件夹下放.mcfunction文件，每个文件里是一串命令。- 1.20.2及以上版本，函数标签的路径是
data/<命名空间>/tags/function/；如果用的是1.19及之前的版本，需要改成data/<命名空间>/tags/functions/，注意是复数。
我踩过最惨的一次坑，就是把tags/function写成了tags/functions，在1.20.2版本里死活加载不上。后来才发现，这个路径在版本更新中悄悄改过，并非一直是复数。所以遇到“包没生效”的问题，第一件事就是检查版本和标签路径是否匹配。
2.3 pack.mcmeta 配置与版本号对照
pack.mcmeta是一个JSON文件，最小写法是这样的：
{ "pack": { "pack_format": 15, "description": "我的第一个数据包" } }pack_format必须写对，否则游戏会提示“数据包不兼容”，也就是加载失败。这里给你一份常用的版本对照表，直接按自己玩的游戏版本查：
| 游戏版本 | pack_format |
|---|---|
| 1.13 - 1.14.4 | 4 |
| 1.15 - 1.16.1 | 5 - 6 |
| 1.16.2 - 1.16.5 | 6 |
| 1.17.x | 7 |
| 1.18.x | 8 |
| 1.19 - 1.19.2 | 9 |
| 1.19.3 | 12 |
| 1.19.4 | 13 |
| 1.20 - 1.20.1 | 15 |
| 1.20.2 | 18 |
| 1.20.3 - 1.20.4 | 26 |
| 1.20.5 - 1.20.6 | 41 |
| 1.21 | 48 |
我一般习惯在多版本开发时，先在最常用的主版本里建一个包，把pack_format调好，再复制出去改。因为版本不对的包，进游戏后完全不会出现在可加载列表里，排查起来很头大。description会在游戏内置的数据包列表里显示，可以用来写版本信息或者说明，中文完全没问题。
3. 上手实操：一个10分钟跑通的“挖矿奖励”数据包
理论说再多，不如亲手跑一个。下面我带你做一个非常简单的数据包：玩家每挖掘10个石头，自动获得1颗钻石，并在聊天栏收到提示。这个例子包含了记分板、函数、标签三个核心概念，学会了它，你就掌握了数据包80%的日常操作套路。
3.1 功能拆解：记分板统计、tick检测、函数奖励
这个功能的实现思路可以拆成三块：
- 记分板统计：创建一个记分板，记录每个玩家挖掘石头方块的数量。
- 循环检测：每1秒（20游戏刻）检测一次所有玩家的挖石计数，如果达到10，就执行奖励。
- 奖励函数：给符合条件的玩家发放钻石，并把计数清零，避免重复发。
为什么要每20刻检测一次？因为如果每个tick都执行奖励判断，服务器负载会白白增加。实际项目中，我习惯把不紧急的逻辑都放到tick函数里“每N刻跑一次”，比如用execute if score配合schedule或者直接在函数里写“每20刻执行”。不过这里为了演示最简单，直接用tick标签让函数每秒跑一次也可以，只要函数本身写得足够轻量就行。
3.2 编写函数文件与标签注册
首先创建记分板。在data/demo/functions/load.mcfunction里写：
scoreboard objectives remove mineStone scoreboard objectives add mineStone minecraft.mined:minecraft.stone这里minecraft.mined:minecraft.stone是记分板判据，表示“玩家挖掘石头方块的次数”。在开发阶段，我建议先remove再add，这样每次/reload时重复执行也不会报错。不过要注意，如果玩家计数已经累计到一半，这次remove会清零，所以正式使用时最好只在首次加载时执行一次，或者用更优雅的“如果目标不存在就创建”逻辑，但那个比较复杂，新手先用remove+add这套方案最稳妥。
接着写循环检测函数。在data/demo/functions/tick.mcfunction里写：
execute as @a[scores={mineStone=10..}] run function demo:reward这一行的意思很直白：对所有“挖掘石头计数大于等于10”的玩家，以该玩家身份执行demo:reward函数。scores={mineStone=10..}是记分板分数选择的写法，10..表示10以上的所有数值。
然后写奖励函数。在data/demo/functions/reward.mcfunction里写：
give @s diamond 1 scoreboard players set @s mineStone 0 tellraw @s [{"text":"挖掘奖励！钻石+1","color":"yellow"}]第一行给当前玩家1个钻石，第二行把挖掘计数清零，第三行在聊天栏输出一条黄色提示。注意这里的@s不再是“自己”，因为上一行execute as已经把执行者切换成了被选中的玩家，所以在函数里@s指向的就是那个玩家。
函数都写好了，还需要告诉游戏哪个函数是加载时执行、哪个函数是每tick执行。这就需要用到标签注册。在data/minecraft/tags/function/load.json里写：
{ "values": ["demo:load"] }在data/minecraft/tags/function/tick.json里写：
{ "values": ["demo:tick"] }load标签里的函数，会在数据包加载时自动运行一次；tick标签里的函数，会每1/20秒循环运行一次。命名空间和路径的对应关系是：demo:load对应data/demo/functions/load.mcfunction，不能写错。
3.3 加载进存档：从reload到调试思路
现在把整个MyFirstPack文件夹，放入存档目录的datapacks文件夹里。
存档路径一般是：.minecraft/saves/<你的世界名字>/datapacks/。如果你不知道世界文件夹在哪，可以在游戏里按Esc，点“打开世界文件夹”，再进datapacks目录。没有就新建一个。
启动游戏进入世界后，执行：
/reload如果没有报错，再执行：
/datapack list你应该能在“可用数据包”里看到MyFirstPack。此时随便挖10个石头，聊天栏应该会弹出提示，背包里也会多出钻石。
整个调试过程，我强烈建议你不要把游戏窗口最小化。数据包不像编程有控制台，最直接的反馈就是游戏日志和聊天栏的报错。如果你发现没生效，第一件事切回主菜单再进一次世界，同时看启动器日志有没有“Failed to load pack”之类的关键字。很多加载问题在日志里写得比游戏内详细得多。
4. 翻车实录：数据包不生效的常见原因和排查方法
如果说数据包有什么“劝退点”，那一定是“我明明按教程写好了，为什么没生效”。从我自己的经验看，90%的问题都出在几个特别低级但特别隐蔽的地方。下面我把踩过的坑整理出来，你会少走很多弯路。
4.1 数据包根本没被识别
“游戏里看不到我的数据包”，这是最常见的情况。按优先级排查：
pack_format版本不对。游戏不会直接告诉你“版本不兼容”，只会安安稳稳地把包忽略掉。- 压缩成zip时多包了一层文件夹。很多人把文件夹右键压缩后，zip内部结构变成了“外层文件夹/pack.mcmeta”，这是错的。打包zip时应该让
pack.mcmeta直接位于zip根目录。 - 目录命名问题。
data目录、命名空间目录、functions目录的大小写、单复数都要严格匹配，特别是function和functions这个坑。 - 文件夹放错了位置。一定要放进
存档/datapacks/，不是.minecraft下随便某个地方。
我建议新手先别打包zip，直接用文件夹方式放在datapacks目录里。文件夹方式的优先级和zip一样，但调试时改动内容后直接/reload即可，不需要反复重新打包。
4.2 函数写了却不执行
数据包能被识别，但函数不执行，这通常是标签或命令的问题。
- 标签路径错误。1.20.2+要写成
data/minecraft/tags/function/load.json，旧版本要写成data/minecraft/tags/functions/load.json。如果写错了，游戏不会报错，只是压根不加载这个标签。 - 函数路径与命名空间不匹配。比如标签里写
demo:load，但文件放在data/minecraft/functions/load.mcfunction，那游戏会找不到函数。 - 命令本身有语法错误。游戏会在执行时于聊天栏给红色报错信息。比如旧版本里
tellraw的JSON写法和新版就有差异，尽量参考你游戏版本对应的语法。
我的排查习惯是：先写一个“空降测试函数”，比如新建一个test.mcfunction，里面只写一行say test，然后在游戏里手动执行/function demo:test。如果这个能跑通，说明函数加载路径没问题，问题出在标签或命令逻辑上。
4.3 编码、JSON语法和编辑器选择
数据表文件本质是文本，编码问题很容易被忽视。如果你的JSON或mcfunction里出现了中文乱码，检查编辑器是否把文件保存为了UTF-8编码，BOM头也最好去掉。Windows自带的记事本在某些情况下会存成带BOM的UTF-8，游戏解析JSON时可能会出问题。
编辑器方面，认准VS Code，再装一个“Datapack Helper Plus”插件，它能自动补全函数名、标签路径、记分板判据，还能在JSON里提示语法错误。没有这个插件的时候，我写错一个逗号往往要对着屏幕找十分钟，有了之后这类低级错误基本不会发生了。在线临时改文件的话，也可以找个JSON校验网站先跑一遍格式。
我把典型的排查问题整理成下面这个速查表，方便你遇到问题时对照：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 数据包不出现在列表中 | pack_format版本不匹配 | 查版本对照表，改pack.mcmeta |
| 数据包提示不兼容 | 压缩结构错误 | 确保pack.mcmeta在zip根目录 |
| 函数手动执行正常，自动不执行 | 标签路径写错 | 检查tags/function还是tags/functions |
| 函数执行报错 | 命令或JSON语法错误 | 看游戏聊天栏红色提示，逐行修正 |
| 中文乱码 | 文件编码不是UTF-8 | 用UTF-8无BOM重新保存 |
| 奖励重复发放 | 计数未清零 | 奖励函数里加scoreboard players set |
5. 下一步进阶：标签、战利品表、进度和配方
学完上面这个迷你功能，你已经掌握了数据包最常见的运行模式：函数加标签加记分板。但数据包的世界远不止函数，接下来这四个模块是每个进阶数据包玩家都会频繁用到的东西，我先帮你搭个框架。
5.1 标签系统：给方块和物品分类
标签（tag）的作用，用一句话说就是“给一类东西起个共同名字”。除了load和tick这种函数标签，你还可以自定义方块标签、物品标签、实体类型标签等。
比如我想让某种自定义玩法只对“矿石”生效，可以先在data/demo/tags/blocks/my_ores.json里写上：
{ "values": [ "minecraft:coal_ore", "minecraft:iron_ore", "minecraft:gold_ore", "minecraft:diamond_ore" ] }然后在命令里用#demo:my_ores引用这个标签，比如execute if block ~ ~-1 ~ #demo:my_ores run ...。这样以后想加一种矿石，只需要往标签里加一行，不用改动逻辑函数。这个思路和编程里的常量列表、枚举很相似。
5.2 战利品表：一句话改全游戏掉落
战利品表是数据包另一个极其强大的部分。举个实际场景：你想让所有僵尸被玩家击杀后，额外掉落一把钻石剑。不用改任何Java代码，只需要在data/minecraft/loot_tables/entities/zombie.json里往pools数组中加一个掉落项。
{ "pools": [ { "rolls": 1, "entries": [ { "type": "minecraft:item", "name": "minecraft:diamond_sword" } ], "conditions": [ { "condition": "minecraft:killed_by_player" } ] } ] }这个JSON的意思是：僵尸死亡时，如果击杀者是玩家，则必定抽取一次物品，抽到钻石剑。你还可以用random_chance条件、set_count函数来控制概率和数量。第一次看懂这个结构后，你会觉得“嗯，原来掉落物是这样靠数据拼出来的”。
5.3 进度系统：把事件变成触发器
进度在很多人眼里只是“成就”，但在数据包里，它简直是一个事件总线。每个进度都可以配置rewards，在进度达成时执行函数、给予物品、播放音效、或者运行一段命令。
比如我想做一个“玩家第一次获得钻石时，全服广播”的效果。可以先创建一个进度data/demo/advancements/first_diamond.json，监听物品获取事件，然后在rewards.function里指向一个广播函数。这个思路非常适合做任务线、成就奖励、事件触发，在服务器小游戏里也特别常用。
不过进度系统有一个细节要记住：如果你不想让这个进度显示在“成就”界面里，可以把display字段整个省略，这样它就是一个纯粹的“后台触发器”，玩家完全感知不到。
5.4 配方：自定义合成不用等Mod
最后说配方。自定义合成表的JSON结构最简单，比如给“钻石块”增加一个用九个铁锭合成的配方：
{ "type": "minecraft:crafting_shaped", "pattern": [ "###", "###", "###" ], "key": { "#": { "item": "minecraft:iron_ingot" } }, "result": { "item": "minecraft:diamond_block" } }放在data/demo/recipes/diamond_from_iron.json里，然后/reload，打开工作台就能看到新配方。在你的数据包里，配方文件之间不要互相覆盖，自己自定义的配方尽量放在自定义命名空间里。只有当你确实想修改原版配方时，才需要用minecraft命名空间去覆盖对应文件。
我个人在实际操作中的体会是，数据包最迷人的地方不在某一个具体功能，而是“函数、标签、进度、战利品表、配方”这些模块可以互相咬合。比如用进度监听事件，用函数执行逻辑，用标签管理对象，用战利品表控制产出，最后再用配方把整个循环闭合起来。一个小玩法往往就是这样拼出来的。
第一期先讲到这里。这个系列后面我会继续拆一些更复杂的数据包实例，比如自定义右键技能、用进度做多阶段任务、给武器做专属特效、以及如何把包从单机搬进服务器并做好权限控制。你有兴趣的话，可以先从今天这个“挖掘有惊喜”的包开始改，试着把奖励换成铁锭、把计数改成20次，或者增加一个“挖到钻石全服播报”的进度触发。改过一遍，你就真正上手了。
