array_is_list 连续键怎么配置或排查

我在把 PHP 查询结果交给 JSON 接口时，最容易误判的一件事是：数组里明明只有几项，为什么 array_is_list() 还是返回 false？答案通常不在“配置”，而在键的形状。PHP 8.1 起，这个函数只认按迭代顺序排列的整数键 0, 1, 2 ... count($array)-1；空数组也算列表。

直接遍历校验数组的键是否符合从0开始、步进为1的连续整数规则，比逐个打印调试效率更高，调整对应的数组赋值逻辑就能匹配`array_is_list`的判定要求。

先把“连续键”定义清楚

下面这组样例很适合先排除猜测。[10, 20]、显式写成 [0 => 10, 1 => 20]，以及空数组都返回 true；从 1 开始、跳过 1、或者把整数键和字符串键混在一起，则返回 false。值是否重复、是否为字符串、是否为对象，都不影响这个函数对键的判断。

 [10, 20],
    'empty' => [],
    'starts-at-one' => [1 => 'a', 2 => 'b'],
    'has-hole' => [0 => 'a', 2 => 'c'],
    'out-of-order' => [1 => 'b', 0 => 'a'],
    'mixed-key' => [0 => 'a', 'name' => 'x'],
];

foreach ($cases as $name => $items) {
    // 生产代码中可把 name 和结果写入调试日志，保留现场。
    printf("%s: %s\n", $name, array_is_list($items) ? 'list' : 'map');
}
?>

因此，标题里的“配置”不能理解为改 php.ini。你能配置的是上游数据生成方式；array_is_list() 本身没有参数可以放宽“从 0 开始、不能断档、顺序必须一致”这三个条件。

返回 false 时沿着键的来源排查

我通常先看 array_keys()，再看 var_export()，不要只盯着元素数量。数量为 2 并不代表键就是 0,1。最常见的现场是删除了中间元素，或者过滤函数保留了原键。

排查清单可以压缩成四问：是否调用过 unset()；是否使用了会保留键的 array_filter()；是否手动指定了从 1 开始或跳号的键；是否在排序、合并或反序列化后改变了迭代顺序。若数组本来是键值映射，返回 false 反而是正确结果，不要为了让检查通过而强行重排。

需要列表时用 array_values() 修复形状

当接口契约明确要求 JSON 数组、或者后续代码要用 for ($i = 0; $i 按位置读取时，才重新索引。array_values() 会按当前迭代顺序取出所有值，并生成从 0 开始的新键。

这里有一个容易忽视的取舍：重新索引会创建一个新数组，较大的数据集需要留意额外内存；而对关联数组调用它会丢失键名。修复动作应靠近数据契约边界，并在代码评审中写清“为什么这里必须是列表”。

低版本兼容和上线前检查

array_is_list() 的官方函数签名从 PHP 8.1 开始可用。需要支持更低版本时，可以使用一次遍历的兼容实现，并保留严格比较；不要用“值数组等于 array_values 后的数组”代替，因为特殊值和空数组会带来边界差异。

 $_value) {
            // 使用 !== 同时检查整数类型和精确的键值。
            if ($key !== $expectedKey++) {
                return false;
            }
        }
        return true;
    }
}
?>

上线前我会把检查放在三个位置：输入解码后确认外部数据是否符合列表契约；过滤、删除或合并后确认键是否需要重排；序列化前确认最终形状。另一个边界是参数类型：原生函数接收的不是数组时会触发 TypeError，所以外层若接收混合输入，应先用 is_array() 分支处理。

常见问题

为什么 array_is_list([1 => 'a', 2 => 'b']) 是 false？

因为列表必须从键 0 开始；即使键连续，从 1 开始也不满足定义。

array_filter() 后一定要 array_values() 吗？

不一定。只有下游按位置读取或要求 JSON 数组时才需要；关联数组应保留原键。

能不能通过 php.ini 配置让它接受缺口键？

不能。它是固定语义的判断函数；要接受缺口，应该修改数据生成逻辑或先明确地重新索引。