Python IndexError — 列表索引越界

症状

遇到“Python IndexError — 列表索引越界”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• Python 抛出 “IndexError: list index out of range”
• 错误仅在列表为空或短于预期时出现
• 假定首个元素存在的代码在空 API 响应上失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

print(len(items), repr(items))

得知真实长度即可判断哪个索引非法，以及来源是否返回空。

步骤 2

grep -n "range(len\|\[i\]\|\[0\]" app.py

审查索引表达式与区间；range(len(x)) 安全，<= len(x) 不安全。

常见诱因（按出现频率排序）：

• 集合为空却访问第 0 个元素
• 循环使用 <= len 而非 < len，产生差一错误
• split/解析产生的元素少于代码假定

根因

Python 列表从 0 开始索引，并在访问时校验索引。当索引为超出长度的负数，或大于等于 len(list) 时，即抛 IndexError。

修复

访问首元素前先判断非空，直接迭代而非按索引，使用 range(len(x))（非 <=），并优先用切片或 enumerate 以保证安全。

注意：用占位元素静默补齐列表会掩盖真正的空响应；应显式记录空的情况。

items = []
# print(items[0])   # IndexError: list index out of range

first = items[0] if items else None
for i in range(len(items)):    # safe: 0..len-1
    process(items[i])

# prefer direct iteration
for item in items:
    process(item)

验证

分别用空列表与单元素输入重跑，二者均应无 IndexError；为空的用例补充测试。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。