/data 命令

/data 命令

图片处理：未转载源站游戏图像；具体物品、实体、效果或界面说明以中文文字保留。

来源：Commands/data，英文修订 ID：3826018。

允许读取、合并、修改和移除方块实体、实体或命令存储的 NBT 数据。仅 Java 版可用，所需权限等级为 2。不要与 /datapack 混淆。

原文更新提示：Java 版 26.3 Snapshot 10 为 /data 新增了 compute 来源，但本页语法与参数尚未同步更新；以下忠实保留来源已有内容。

语法

/data 有四种指令：get、merge、modify、remove。每种指令引用的目标／来源可以是 block <targetPos>、entity <target> 或 storage <target>。

get

读取目标方块或实体的全部 NBT，或其指定部分，以语法高亮显示给执行者；指定 <scale> 时按该倍率缩放输出数值。

data get (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]

merge

将指定 <nbt> 数据合并到目标方块或实体的 NBT。

data merge (block <targetPos>|entity <target>|storage <target>) <nbt>

modify

data modify (block <targetPos>|entity <target>|storage <target>) <targetPath> ...
  ... append from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
  ... append string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
  ... append value <value>
  ... insert <index> from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
  ... insert <index> string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
  ... insert <index> value <value>
  ... merge from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
  ... merge string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
  ... merge value <value>
  ... prepend from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
  ... prepend string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
  ... prepend value <value>
  ... set from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
  ... set string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
  ... set value <value>
  • append：把源数据或直接指定的值加到目标列表／数组末尾。
  • insert <index>：作为索引 <index> 的元素插入，高索引元素向后移动一位。
  • merge：把源数据或直接指定的值合并到目标对象。
  • prepend：加到目标列表／数组开头。
  • set：把 <targetPath> 指定的标签设为源数据或直接指定的值。

remove

移除目标方块或实体的 <path> 处 NBT 数据，不能移除玩家的 NBT。

data remove (block <targetPos>|entity <target>|storage <target>) <path>

其他语法形式

简化树：

/data
… get <TARGET> [<path>] [<scale>]
… merge <TARGET> <nbt>
… modify <TARGET> <targetPath> <MODIFICATION>
… from <SOURCE> [<sourcePath>]
… string <SOURCE> [<sourcePath>] [<start>] [<end>]
… value <value>
… remove <TARGET> <path>
<TARGET> = (block <targetPos> | entity <target> | storage <target>)
<MODIFICATION> = (append|insert <index>|merge|prepend|set)
<SOURCE> = (block <sourcePos> | entity <source> | storage <source>)

紧凑树：

/data
… get (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]
… merge (block <targetPos>|entity <target>|storage <target>) <nbt>
… modify (block <targetPos>|entity <target>|storage <target>) <targetPath> (append|insert <index>|merge|prepend|set)
… from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
… string (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>] [<start>] [<end>]
… value <value>
… remove (block <targetPos>|entity <target>|storage <target>) <path>

完整展开形式：

data get block <targetPos> [<path>] [<scale>]
data get entity <target> [<path>] [<scale>]
data get storage <target> [<path>] [<scale>]
data merge block <targetPos> <nbt>
data merge entity <target> <nbt>
data merge storage <target> <nbt>
data modify block <targetPos> <targetPath> append from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> append from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> append from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> append string block <sourcePos> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> append string entity <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> append string storage <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> append value <value>
data modify block <targetPos> <targetPath> insert <index> from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> string block <sourcePos> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> insert <index> string entity <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> insert <index> string storage <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> insert <index> value <value>
data modify block <targetPos> <targetPath> merge from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> merge from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> merge from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> merge string block <sourcePos> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> merge string entity <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> merge string storage <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> merge value <value>
data modify block <targetPos> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> prepend from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> prepend from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> prepend string block <sourcePos> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> prepend string entity <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> prepend string storage <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> prepend value <value>
data modify block <targetPos> <targetPath> set from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> set from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> set from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> set string block <sourcePos> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> set string entity <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> set string storage <source> <sourcePath> <start> <end>
data modify block <targetPos> <targetPath> set value <value>
data modify entity <target> <targetPath> append from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> append from entity <source> <sourcePath>
data modify entity <target> <targetPath> append from storage <source> <sourcePath>
data modify entity <target> <targetPath> append string block <sourcePos> <sourcePath> <start> <end>
data modify entity <target> <targetPath> append string entity <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> append string storage <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> append value <value>
data modify entity <target> <targetPath> insert <index> from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> insert <index> from entity <source> <sourcePath>
data modify entity <target> <targetPath> insert <index> from storage <source> <sourcePath>
data modify entity <target> <targetPath> insert <index> string block <sourcePos> <sourcePath> <start> <end>
data modify entity <target> <targetPath> insert <index> string entity <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> insert <index> string storage <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> insert <index> value <value>
data modify entity <target> <targetPath> merge from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> merge from entity <source> <sourcePath>
data modify entity <target> <targetPath> merge from storage <source> <sourcePath>
data modify entity <target> <targetPath> merge string block <sourcePos> <sourcePath> <start> <end>
data modify entity <target> <targetPath> merge string entity <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> merge string storage <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> merge value <value>
data modify entity <target> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> prepend from entity <source> <sourcePath>
data modify entity <target> <targetPath> prepend from storage <source> <sourcePath>
data modify entity <target> <targetPath> prepend string block <sourcePos> <sourcePath> <start> <end>
data modify entity <target> <targetPath> prepend string entity <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> prepend string storage <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> prepend value <value>
data modify entity <target> <targetPath> set from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> set from entity <source> <sourcePath>
data modify entity <target> <targetPath> set from storage <source> <sourcePath>
data modify entity <target> <targetPath> set string block <sourcePos> <sourcePath> <start> <end>
data modify entity <target> <targetPath> set string entity <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> set string storage <source> <sourcePath> <start> <end>
data modify entity <target> <targetPath> set value <value>
data modify storage <target> <targetPath> append from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> append from entity <source> <sourcePath>
data modify storage <target> <targetPath> append from storage <source> <sourcePath>
data modify storage <target> <targetPath> append string block <sourcePos> <sourcePath> <start> <end>
data modify storage <target> <targetPath> append string entity <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> append string storage <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> append value <value>
data modify storage <target> <targetPath> insert <index> from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> insert <index> from entity <source> <sourcePath>
data modify storage <target> <targetPath> insert <index> from storage <source> <sourcePath>
data modify storage <target> <targetPath> insert <index> string block <sourcePos> <sourcePath> <start> <end>
data modify storage <target> <targetPath> insert <index> string entity <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> insert <index> string storage <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> insert <index> value <value>
data modify storage <target> <targetPath> merge from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> merge from entity <source> <sourcePath>
data modify storage <target> <targetPath> merge from storage <source> <sourcePath>
data modify storage <target> <targetPath> merge string block <sourcePos> <sourcePath> <start> <end>
data modify storage <target> <targetPath> merge string entity <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> merge string storage <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> merge value <value>
data modify storage <target> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> prepend from entity <source> <sourcePath>
data modify storage <target> <targetPath> prepend from storage <source> <sourcePath>
data modify storage <target> <targetPath> prepend string block <sourcePos> <sourcePath> <start> <end>
data modify storage <target> <targetPath> prepend string entity <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> prepend string storage <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> prepend value <value>
data modify storage <target> <targetPath> set from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> set from entity <source> <sourcePath>
data modify storage <target> <targetPath> set from storage <source> <sourcePath>
data modify storage <target> <targetPath> set string block <sourcePos> <sourcePath> <start> <end>
data modify storage <target> <targetPath> set string entity <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> set string storage <source> <sourcePath> <start> <end>
data modify storage <target> <targetPath> set value <value>
data remove block <targetPos> <path>
data remove entity <target> <path>
data remove storage <target> <path>

原文完整展开形式把部分在主树中可选的来源路径与字符串索引写成必需参数；这里按来源保留。

参数

参数 类型与说明
<targetPos> block_pos，要操作其 NBT 的目标方块实体位置
entity <target> 中的 <target> entity，要操作其 NBT 的单个实体，可用玩家名称、目标选择器或 UUID；以名称指定的玩家必须在线
storage <target> 中的 <target> resource_location，要操作的命令存储资源位置
<path> nbt_path，要读取或移除的 NBT 路径
<scale> double，命令输出值的缩放倍率
<nbt> nbt_compound_tag，要合并的 SNBT 复合标签
<targetPath> nbt_path，要修改的目标 NBT 路径
<index> integer，列表内的元素索引，必须为 32 位整数
<sourcePos> block_pos，提供源 NBT 的方块实体位置
entity <source> 中的 <source> entity，供 modify 读取 NBT 的单个实体，可用玩家名称、目标选择器或 UUID
storage <source> 中的 <source> resource_location，供 modify 使用的命令存储
<sourcePath> nbt_path，供 modify 使用的源 NBT 路径
<start> integer，字符串子串中包含的第一个字符索引；负值表示从字符串末尾计数
<end> integer，字符串子串末尾第一个不包含的字符索引；负值表示从末尾计数
<value> nbt_tag，用于修改目标 NBT 的值，使用 SNBT 格式

方块坐标由 X、Y、Z 三个整数，或波浪号／插入符坐标组成。NBT 路径使用 NBT 路径格式。

结果

命令不完整或任一参数指定错误时无法解析。以下情况失败：

  • <targetPos> 未加载、位于世界之外，或该位置不是方块实体。
  • entity <target> 未解析为单个实体，以名称指定的玩家必须在线。
  • get 得到多个标签。
  • get ... <path> 的路径没有标签。
  • get ... <path> <scale> 得到的不是数值标签。
  • merge、remove、modify 没有改变任何内容，或尝试编辑玩家数据。
  • remove 或 modify ... set 的路径选中了根复合标签。
  • modify ... (from|string) block 的源位置未加载、位于世界之外，或不是方块实体。
  • modify ... (from|string) entity 的源目标未解析为单个实体，以名称指定的玩家必须在线。
  • modify ... (from|string) ... <sourcePath> 的源路径没有标签。
  • modify ... string 的任一源标签既非字符串，也非可转为字符串的数值标签；<start> 或 <end> 超出任一源字符串的有效索引；或任一源字符串中 <start> 在 <end> 之后。
  • modify ... append、insert、prepend 的任一目标标签不是列表／数组，或所有源标签对所有目标列表／数组都不具有合适类型。
  • insert <index> 的索引对所有目标列表／数组均无效。
  • modify ... merge 的任一目标标签或任一源标签不是复合标签。

其他情况成功。

输出

失败时成功次数、success、result 均为 0。成功时成功次数和 success 均为 1，result 如下：

命令／取得的标签 result
data get ...，不带路径 1
data get ... <path>，数值 取得的值向下取整
同上，列表或数组 元素数量
同上，字符串 字符串长度
同上，复合标签 该复合标签直接子标签的数量
data get ... <path> <scale> 值乘以 <scale> 后向下取整
data merge ... 或 data remove ... 1
data modify ... append/insert/prepend ... 实际加入新元素的列表／数组数量
data modify ... set ... 成功修改的目标标签数量
data modify ... merge ... 成功修改的目标复合标签数量

来源给出的向下取整实现如下；带倍率时第一行改为 double n = (double)value * scale;。另见 MC-259032。

double n = (double)value;
int output = n < (int)n ? (int)n - 1 :(int)n;

示例

查看玩家手持物品的 NBT：

/data get entity @s SelectedItem

读取当前玩家的饱和度：

/data get entity @s foodSaturationLevel

使 10 格内最近的掉落物不能被玩家拾取：

/data modify entity @n[type=item,distance=..10] PickupDelay set value -1s

读取随机一个掉落物的 Y 坐标：

/data get entity @e[type=item,limit=1,sort=random] Pos[1]

读取最近玩家快捷栏第一个槽位的物品 ID：

/data get entity @p Inventory[{Slot:0b}].id

把 (1,64,1) 处箱子的第一件物品改成钻石块，保留全部 NBT 数据：

/data modify block 1 64 1 Items[0].id set value "minecraft:diamond_block"

使最近僵尸死亡时副手物品掉落概率为 80%，主手永不掉落：

/data merge entity @n[type=zombie] {drop_chances:{mainhand:0f,offhand:0.8f}}

使最近僵尸副手物品掉落概率为 80%，不影响主手概率：

/data modify entity @n[type=zombie] drop_chances.offhand set value 0.8f

列表、数组与字符串长度

/data get 的返回值为所引用字符串、列表或数组的长度，因此可以读取这些长度，必要时用 /execute store 存储返回值。

列表示例，先存入：

/data merge storage wiki:example {List:[2,5,8,9,6,10]}

再运行以下命令，返回列表长度 6：

/data get storage wiki:example List

字符串示例，先存入：

/data merge storage wiki:example {String:"Example string with a character count of 43"}

再运行以下命令，返回字符串长度 43：

/data get storage wiki:example String

字符串属于命令测试数据，为保持字符数量与输出一致，英文原值未翻译。

参考资料

  • MC-259032。
  • 原文历史部分另引用了已修复问题 MC-260602：字符串索引无效时应正常报告命令失败。

本文为 Minecraft Wiki 对应英文条目的中文翻译与改编，已按要求省略变更历史。原作者与贡献者见来源页及其历史；除另有说明外，按 CC BY-NC-SA 3.0 非商业、署名、相同方式共享。