指南 / 故障排除

数据包加载不了？文件夹结构和三个必须一致的名字

一个没有出现在 /datapack list 里的数据包，问题出在路径上，而不是代码上。这里是确切的目录树、命名空间规则，以及那些被改名的文件夹，旧的 functions 文件夹现在改成了单数形式 function，这是常被忽略的改名之一。

2026-07-03

/datapack list 什么都不显示，或者把数据包显示为已禁用。几乎总是 JSON 没问题，而文件夹错了。

目录树

world/datapacks/my_pack/
├── pack.mcmeta
└── data/
    ├── my_namespace/
    │   ├── function/         one .mcfunction per file
    │   ├── recipe/
    │   ├── loot_table/
    │   ├── advancement/
    │   └── predicate/
    └── minecraft/
        └── tags/
            └── function/
                └── load.json

有三个名字必须对齐，而其中一个并不明显：

1. 数据包根目录下的 pack.mcmeta —— 与 data/ 并列，而不是放在它里面。
2. data/<namespace>/ —— 你的命名空间，小写，不含空格。它会成为 my_namespace:my_function 中的前缀。
3. 分类文件夹的名字，它们改过名，也是常见的罪魁祸首。

文件夹已改名为单数

这一点坑了很多数据包和很多教程：

使用复数名字的数据包会加载——它会出现在 /datapack list 中——但什么都不做，这是这一组里最令人困惑的失败模式。tags/ 保持复数，但它里面的文件夹和其他所有文件夹一样变成了单数——tags/functions/ 现在是 tags/function/。是的，这很不一致。

自动运行某些东西

两个特殊标签：

data/minecraft/tags/function/load.json   → runs once on load/reload
data/minecraft/tags/function/tick.json   → runs every tick

注意是 data/minecraft/，而不是你自己的命名空间——标签属于 Minecraft，它指向的函数属于你：

{ "values": ["my_namespace:setup"] }

按顺序排查

1. /datapack list —— 如果数据包根本没有被列出，说明 pack.mcmeta 缺失、格式错误，或者深了一层。
2. 列出了但已禁用 —— /datapack enable "file/my_pack"。注意 file/ 前缀和引号。
3. 列出了且已启用但毫无作用 —— 文件夹名用了复数，或者加载标签写在了你自己的命名空间里，而不是 minecraft。
4. /reload 并阅读日志（logs/latest.log，或启动器输出）。有语法错误的函数会在这里被丢弃，并显示 "Failed to load function …"；聊天栏只会说重载完成了。

压缩还是不压缩

两种都可以。压缩意味着 pack.mcmeta 位于 zip 根目录，与资源包完全相同。开发时用文件夹形式更方便，因为 /reload 无需重新压缩就能识别改动。

服务器中的放置位置

在服务器上，路径是 <world>/datapacks/，其中 <world> 是 server.properties 中 level-name 的值——而不是服务器根目录。把数据包丢进服务器文件夹是服务器端最常见的错误。

用当前的文件夹名和一个有效的 pack.mcmeta 组装一个数据包，然后用 Datapack Studio 下载一个可以直接放入的数据包——并把你的加载标签放在 data/minecraft/tags/function/ 中，如上所述。

数据包工作室 →