当前位置：首页 > 文章列表 > 文章 > php教程 > PHP json_encode 列表键不连续时为什么输出对象

PHP json_encode 列表键不连续时为什么输出对象

来源：17golang原创 2026-11-14 05:33:43 0浏览收藏

json_encode() 把 PHP 数组输出成 JSON 对象，通常不是编码器“随机改变了类型”，而是因为数组的整数键已经不是从 0 开始连续排列。PHP 官方对列表的定义是：键必须正好是 0 到 count($array) - 1；只要中间缺一个键、从别的数字开始，或混入字符串键，编码结果就会显式保留键，表现为 JSON 对象。

官方文档：https://www.php.net/manual/en/function.json-encode.php

因此，接口设计先要决定“客户端需要一个有顺序的列表，还是一个带业务键的映射”。需要列表时，在编码前用 array_values() 重排；需要保留键时，保留对象形状，并在接口契约中写清楚。PHP 8.1 及更高版本还可以用 array_is_list() 把这个判断写成显式条件。

PHP 数组键连续性决定 json_encode 输出 JSON 数组或对象的结构说明图 — 图1：PHP 数组键序列与 JSON 形状的静态说明图，不是运行截图。

先把 PHP 数组看成有序映射

PHP 的 array 本质上是有序映射，不是只能使用 0、1、2 下标的纯向量。它可以同时容纳整数键和字符串键，所以“看起来像列表”并不等于“编码时一定是 JSON 数组”。json_encode() 需要根据键形状决定是否能够省略键名。

PHP 数组键	列表判断	典型 JSON 形状	接口含义
`0, 1, 2`	是	`["A","B","C"]`	有顺序的集合
`1, 2, 3`	否	`{"1":"A","2":"B","3":"C"}`	键从 1 开始的映射
`0, 2, 3`	否	`{"0":"A","2":"B","3":"C"}`	保留缺口信息
`0, "name"`	否	`{"0":"A","name":"B"}`	混合键映射

这里的判断和元素数量无关。三个元素也可能是对象，关键是键是否严格等于 range(0, count($array) - 1)。这也是为什么不能只看 count() 或只看输出里有几个值来推断 JSON 类型。

用过滤后的键观察 json_encode 的变化

最常见的触发点是过滤。array_filter() 默认保留原数组键，这对 PHP 内部继续定位元素很有用，但如果结果直接作为接口列表输出，就可能留下一个缺口。

 101, 'enabled' => true],
    ['id' => 102, 'enabled' => false],
    ['id' => 103, 'enabled' => true],
];

// 过滤会保留原键，因此第二条被移除后，键会变成 0、2。
$enabledUsers = array_filter(
    $users,
    static function (array $user): bool {
        return $user['enabled'];
    }
);

// 这里输出的是对象形状，因为键不是 0、1 的连续序列。
echo json_encode($enabledUsers, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
// 结果形状类似：{"0":{"id":101,"enabled":true},"2":{"id":103,"enabled":true}}
?>

这不是 json_encode() 把列表“误判”了。对编码器来说，键 0、2 不能安全地压缩成两个无键值，否则客户端无法知道原来的索引缺口。因此它保留键名，输出 JSON 对象。

按接口契约选择重排还是保留键

修复前先确认接口语义。若客户端只需要按顺序遍历启用用户，键 0、2 没有业务价值，应该显式重排；若键本身表示数据库位置、外部编号或稀疏索引，就不应该为了得到方括号而丢掉它。

PHP array_filter 保留键后用 array_values 恢复 JSON 列表的流程说明图 — 图2：过滤、重排与接口 JSON 输出决策的结构说明图，不是运行截图。

调用方需求	处理方式	最终形状
前端只渲染一组按顺序排列的记录	`array_values($items)`	JSON 数组
客户端需要按 ID 直接取记录	保留整数或字符串键	JSON 对象
兼容 PHP 8.1 以上的多种输入	先调用 `array_is_list()` 决策	由契约决定
空数组也必须表达为对象	显式传入空对象或约定转换	`{}`

 $user['enabled']
);

// 列表接口不需要保留原索引，所以在边界处重新编号。
$payload = [
    'items' => array_values($enabledUsers),
];

// JSON_THROW_ON_ERROR 让编码失败进入异常流程，而不是静默得到 false。
echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
?>

重排应该发生在接口边界，而不是无条件地在领域层调用。领域层可能仍然需要原键做关联、差异比较或审计；序列化层才决定这些键是否属于对外契约。把职责放在边界上，既不会破坏内部索引，也能让客户端得到稳定形状。

在编码前用 array_is_list 做决策

PHP 8.1 引入的 array_is_list() 直接回答“这个数组是否由 0 到 count-1 的连续键组成”。它比手写 array_keys()、range() 和数量比较更清楚，也把空数组的规则固定为列表。

 'first', 12 => 'second']);
?>

这个函数的两个分支编码选项相同，分支的价值在于把决策点写出来：若产品契约不允许非列表数据进入某个字段，可以在第二个分支抛出业务异常；若对象映射是合法结果，则保留键并记录接口约定。不要把 JSON_FORCE_OBJECT 当成通用修复，它会把所有非关联数组也强制成对象，并且改变调用方看到的形状。

发布接口前检查空数组和错误处理

空数组是另一个容易被忽略的边界。默认情况下，空 PHP 数组编码为 []；如果业务协议要求空对象 {}，应在协议层明确转换为空对象，而不是让客户端猜测。对于非空数组，也要区分“为了列表而重排”和“为了掩盖错误而重排”。

JSON_THROW_ON_ERROR 可以把编码失败转成 JsonException；否则 json_encode() 失败时返回 false，如果调用方直接写入响应，错误可能变成空内容或不符合协议的布尔值。键形状和编码错误是两类问题，应该分别处理。

列表契约：过滤、去重或排序后，接口字段仍需要方括号，就在边界处调用 array_values()。
映射契约：键代表 ID、位置或状态时保留键，并把对象形状写进接口文档。
版本契约：PHP 8.1 以上可用 array_is_list()；旧版本要用等价的键比较逻辑。
空值契约：单独约定空数组是 [] 还是 {}，不要靠 JSON_FORCE_OBJECT 一刀切。
错误契约：对外输出前使用 JSON_THROW_ON_ERROR，让编码失败进入可观测的异常流程。

结论：先决定键的语义，再决定 JSON 形状

json_encode() 输出对象的根因，是数组键不是从 0 开始的连续列表键。array_filter() 默认保留原键，所以列表经过过滤后常常需要 array_values() 才能恢复 JSON 数组；如果原键包含业务含义，则应保留对象形状。PHP 8.1 以上用 array_is_list() 显式判断，再配合接口契约选择编码方式，结果会比“看到对象就强制转数组”更可靠。