Python KeyError: 0 原因与修复：字典、Pandas 避坑指南

一看到python KeyError: 0这个报错，很多人的第一反应是：我明明访问的是第 0 个元素，怎么就报“键不存在”了？其实这里的 0 在多数情况下并不是下标，而是一个字典里不存在的键。这个异常几乎每个 Python 开发者都遇到过，它不复杂，但背后的坑特别多，尤其是刚从其他语言转过来、或者刚开始用 pandas 的同学，经常被它卡住半天。这篇文章就从我的实战经验出发，把KeyError: 0的来龙去脉、高频触发场景、定位方法和修复方案一次讲透，顺便给你一套减少这类异常的日常习惯，适合所有写 Python 的朋友参考。

1. 先搞清楚 KeyError: 0 到底在说什么

1.1 字典按“键”访问，没有就会翻车

字典是 Python 里最常用的数据结构之一，它存的是“键值对”。你访问一个字典时，Python 会拿着你给的键去查找对应的值，如果这个键压根不存在，就会抛出KeyError，后面跟的 0 就是那个缺失的键。

看个最直接的例子：

d = {} print(d[0])

运行结果：

KeyError: 0

这个d是空字典，里面没有键0，所以d[0]直接抛异常。你可能会说“这有什么好讲的，空字典当然报错”。但实际项目里，字典往往不是一开始就空的，而是经过各种函数、循环、条件判断之后，某个原本应该存在的键在某条分支下没有被写入，最后访问时就炸了。这种“看似应该存在、实际却缺失”的情况，才是KeyError: 0真正让人头疼的地方。

1.2 为什么偏偏是 0 这个键最容易出事

0 这个键出现频率高，主要因为三方面：第一，很多数据源里，第一条记录、第一个分组、第一类的编号都习惯用 0 表示，于是代码里动不动就写xxx[0]；第二，0在 Python 里又是列表和元组的下标起点，写的人潜意识里把0当成“第一个”，于是混用了字典键和序列下标；第三，JSON 数据解析后常常是嵌套字典，外层字典的键是业务编号（比如 0、1、2），一旦忘记处理缺失分支，就会在data[0]上翻车。

说白了，0 这个键承载了太多“歧义”。它在字典里是个普通的键，在列表里是第一个位置，在 pandas 的 DataFrame 里又可能被当作列名或者行号。理解这一点，比单纯记住“报错就加 get”重要得多。

2. 最容易踩中 KeyError: 0 的三个真实场景

2.1 场景一：解析接口返回的嵌套字典

我经常看到这样的代码，尤其是接第三方接口的时候：

response = { "data": { "list": {} } } first_item = response["data"]["list"][0]

这里list是一个空字典，[0]就会直接抛KeyError: 0。注意，如果list是空列表，那么[0]抛的是IndexError: list index out of range；但这里是字典，所以抛的是KeyError: 0。

这类问题的根源在于：你假设了返回的数据结构里一定存在键0，但实际接口在无数据或者异常情况下，可能返回空对象、空列表，甚至某个中间字段直接丢失。更隐蔽的是，有的接口返回的list是个列表，里面每个元素是字典，你要取的是response["data"]["list"][0]["name"]，如果list列表是空的，报的是IndexError；如果列表里第一个字典没有name键，报的又是KeyError: 'name'。所以遇到KeyError: 0，先分清你操作的到底是不是字典。

2.2 场景二：Pandas 取数时索引方式搞混

Pandas 是另一个KeyError: 0的重灾区。很多人刚接触 DataFrame 时，天然地以为df[0]能取第一行或者第一列，但 pandas 的df[0]表示的是“取列名为 0 的列”，注意这是列名，不是位置。

import pandas as pd df = pd.DataFrame({ "name": ["张三", "李四"], "score": [90, 85] }) df[0] # KeyError: 0

因为列名是"name"和"score"，根本没有0，所以报KeyError: 0。如果某天你读入的 CSV 或者 Excel 表里恰好有一列名叫0（列名是字符串 “0” 的情况更常见，见下文第 5 节），df[0]和df["0"]的行为又不一样。这一点特别容易让初学者懵。

真正想取第一行，应该用df.loc[0]（按行标签取）或者df.iloc[0]（按位置取）。想取第一列，应该用df.iloc[:, 0]，或者直接df[df.columns[0]]。大家可以记一个口诀：loc是“标签索引”，你给的不是第几个，而是“名字”；iloc是“位置索引”，你给的才是“第几个”。

2.3 场景三：动态构造字典时初始化漏掉了某些键

写数据处理脚本时，我们经常用循环去“攒”一个字典，例如按分类统计数量：

groups = {} for item in items: category = item["category"] groups[category].append(item) # KeyError: 0

如果某个item的category是0，而groups里还没有键0，那么groups[0].append(item)就会抛KeyError: 0。正确的思路是先用setdefault或者collections.defaultdict给每个键先准备一个空列表，再去 append。

这类问题在代码里往往不是一眼能看出来的，因为报错时你看到的只是第 N 行触发了异常，但真正的原因是前面某个循环分支没有执行到初始化逻辑。所以排查时不要只盯着报错那行，还要回头看看这个字典是怎么“长大”的。

3. 三步定位 KeyError: 0，不再瞎猜

3.1 第一步：把出错行和完整堆栈读明白

很多人看到异常后，第一反应是：啊，报错了，然后直接去代码里找[0]。其实最快的办法是先把堆栈从头到尾读一遍。比如下面这个报错：

Traceback (most recent call last): File "test.py", line 12, in <module> process(data) File "test.py", line 8, in process value = row["scores"][0] KeyError: 0

它告诉你：row["scores"][0]出错了，出错时row["scores"]是一个字典，且这个字典缺少键0。如果你只看KeyError: 0五个字，可能还会怀疑是不是row的问题，但堆栈已经明确告诉你是row["scores"]这个字典没有0。所以第一步永远是“先看堆栈，别猜”。

3.2 第二步：在报错之前把数据结构“验明正身”

确定出错位置后，在报错那行之前加一行print或者用调试器，把正在访问的对象打印出来。比如：

print(type(row["scores"]), row["scores"]) value = row["scores"][0]

如果打印出来是{'key': 'x'}，那你立刻明白，这个字典的键是"key"不是0。如果打印出来是[]，那这里应该报IndexError而不是KeyError。很多KeyError: 0其实是对数据结构类型判断失误造成的，打印一下type()，很多疑问就没了。

如果你调试的是 pandas，可以用df.columns和df.index查看是不是真的没有 0 这个标签。这一步不需要什么高深技巧，就是“眼见为实”。

3.3 第三步：倒查数据源头，搞清 0 去哪了

如果打印出来发现字典里确实没有键 0，就要顺着数据流往上找：这个字典是谁构建的？0 在哪个环节被过滤掉了？是拼接字符串时把0变成了"0"？还是某个条件分支漏了？是默认参数给成了空字典？还是异步返回前被别的地方改动了？

比如我处理过一次非常隐蔽的问题：一个函数用空字典作为默认值参数：

def process(data={}): data[0] = data.get(0, 0) + 1

Python 的默认参数只在函数定义时创建一次，多个调用共享同一个字典，前一次的键 0 可能会被清掉，或者被别的地方污染，最终导致KeyError: 0。这种问题不追溯到函数定义很难发现。所以遇到反复出现的KeyError: 0，一定要养成“从数据源头去看”的习惯，而不是盲目地 try-except 一把梭。

4. 五种修复方案，覆盖 90% 以上的场景

4.1 方案一：dict.get() 加默认值，最省事

如果你只是想让程序不崩溃，并且有个合理的缺省值，dict.get()是最快的修复方式：

value = d.get(0, None)

get方法在键不存在时不会抛异常，而是返回你指定的默认值。如果没指定默认值，它返回None。这是最“治标”的方法，但也是很多情况下最合适的方法——例如接口返回缺字段时，我们本来就应该给一个默认值，而不是让程序中断。

有一点要提醒：get只解决“取”的场景，如果你是“先取后改”，比如d[0].append(x)，那get就无能为力了，因为d.get(0, [])返回的是一个新列表，append 之后不会写回原字典。这种情况下应该用下面的setdefault或者defaultdict。

4.2 方案二：setdefault 和 defaultdict，构建时兜底

如果你需要确保访问一个不存在的键时自动创建默认值，用dict.setdefault()：

d = {} d.setdefault(0, []).append("hello") print(d) # {0: ['hello']}

setdefault(0, [])的意思是：如果有键 0，返回它的值；如果没有，先把键 0 的值设为空列表[]，再返回这个空列表。这样后续的append就能直接用了。

更优雅的写法是使用collections.defaultdict：

from collections import defaultdict groups = defaultdict(list) groups[0].append("item")

defaultdict(list)会在访问不存在的键时自动调用list()作为新值，然后返回它。这样groups[0]永远不会报KeyError: 0。类似的还有defaultdict(int)、defaultdict(set)，分别适合计数场景和去重场景。我个人在写统计类代码时，defaultdict几乎成了标配，因为它不仅消灭了异常，还能让代码更短、更清晰。

4.3 方案三：用 in 先判断，逻辑更直观

有些场景下，键是否存在本身就决定了业务逻辑，这时候用in做判断比用get更符合直觉：

if 0 in d: process(d[0]) else: handle_missing()

这种写法尤其适合“只有键存在时才需要做某些事，不存在时走另一套逻辑”的情况。如果你的分支很多，多次用到d[0]，可以先判断一次，再在后续代码里放心使用：

if 0 not in d: d[0] = [] value = d[0]

注意，先in后访问在单线程场景下没问题，但如果涉及多线程并发修改字典，仍然可能出现“判断时存在，访问时被删”的竞态。那种场景建议用锁，或者干脆使用带默认值的结构。

4.4 方案四：Pandas 索引选对 API，别再让 0 背锅

如果是 pandas 导致的KeyError: 0，核心修复思路是搞清楚你到底想按位置取还是按标签取。

按标签取行，用loc：

df.loc[0] # 取 index 为 0 的那一行

按位置取行，用iloc：

df.iloc[0] # 取第一行，无论 index 叫什么

按标签取列，可以写在loc的第二个位置：

df.loc[:, "score"] # 取列名为 score 的所有行

按位置取列，用iloc：

df.iloc[:, 0] # 取第一列

如果确实存在一个列名为0的列，注意它的类型。CSV 导入后，列名默认都是字符串，所以列名其实就是"0"，这时候访问df[0]会报KeyError: 0，而df["0"]才正确。这是字符串"0"和整数0的区别，下一节专门讲。总之，先用df.columns确认列名长什么样，再决定用哪种方式取数。

4.5 方案五：从源头统一键类型，杜绝隐性缺失

KeyError: 0有一个特别阴险的变种：字典里其实有0，但是是以字符串"0"存在的。比如数据处理管道中，你从 CSV 里读到的 ID 是字符串，从数据库里查出来的 ID 却是整数，两边一拼就出问题了。

data = {"0": "张三"} print(data[0]) # KeyError: 0 print(data["0"]) # 张三

修复思路是：在建字典之前，就把所有键统一成同一种类型。最简单的方法是在写入时强制转换：

key = int(raw_key) data[key] = value

或者统一转成字符串：

key = str(raw_key) data[key] = value

具体用哪种，要看下游逻辑。我自己的习惯是：如果键是业务编号，全部转成字符串，因为字符串不会把"01"和"1"搞混；如果键是纯粹的整数序号，全部转成int，然后统一用int访问。只要全流程保持一种类型，KeyError: 0和KeyError: '0'这种“错位”问题就会少很多。

5. 一张表分清 KeyError: 0 的孪生兄弟们

5.1 常见误报对比：KeyError: 0 vs IndexError: 0

很多新手分不清这两个异常，甚至看到KeyError: 0会以为“索引 0 越界”。实际上，KeyError是字典或类似映射结构在键缺失时抛出的，IndexError是序列（列表、元组）在索引越界时抛出的。

看到没，同一个[0]，在不同的容器里含义完全不一样。我见过不少人为了解决KeyError: 0加了 try-except，结果把IndexError也一并吞掉，掩盖了真正的 bug。正确做法是：先判断对象的类型，再决定怎么访问。

5.2 常见误报对比：KeyError: 0 vs KeyError: '0'

这个对比更能体现 Python 的“严格类型”。字典的键可以是任意不可变对象，整数0和字符串"0"是两个完全不同的键。下面这段代码：

d = {"0": 100} print(d[0]) # KeyError: 0 print(d["0"]) # 100

报错信息里KeyError: 0清晰地告诉你，缺失的是整数 0，而不是字符串 "0"。如果你在界面上看到KeyError: '0'，那说明你访问的字符串键不存在。两者经常因为“数字是从哪来的”而产生错位：从 JSON 解析出来的键，如果是数字字面量，会被解析成整数；如果是字符串数字，就会是字符串。从数据库取出的行，键名通常都是字符串。从一个 API 的不同接口拿到的数据，键类型甚至可能不一致。

排查这类错位，最直接的方式是在报错之前打印一下d.keys()：你会看到dict_keys(['0'])或者dict_keys([0])，一眼就知道该用哪个。

6. 一次完整的排查实录：从报错到修复

6.1 模拟问题：统计学生成绩时触雷

假设我有这样一个数据处理任务：从 CSV 里读取学生 ID 和成绩，按学生 ID 分组，最后计算每个学生的总分。某天运行脚本时，突然在total_scores[0]这一行报了KeyError: 0。

代码如下（简化版）：

import csv from collections import defaultdict scores_by_student = {} with open("scores.csv", encoding="utf-8") as f: reader = csv.reader(f) for row in reader: student_id = row[0] score = int(row[1]) scores_by_student[student_id].append(score) # 这里没初始化

报错信息指向的是最后一行scores_by_student[student_id].append(score)，KeyError: 0。但我明明是在写数据，为什么说键 0 不存在？问题在于第一个学生的student_id是"0"，而scores_by_student还是空字典，没有"0"这个键，所以append时直接报错，异常信息里的 0 是键"0"的“简化显示”——等等，严格来说这里应该是KeyError: '0'，带引号的。如果 CSV 里第一列是0（数字格式），csv.reader读出来是字符串"0"，所以报错是KeyError: '0'。但如果我们从 Excel 或别的库读出来，第一列被转换成了整数 0，就会报KeyError: 0。这里恰好演示了两种报错信息之别。

为了贴近主题KeyError: 0，我们假设数据读取层已经做了一次int()转换，把student_id变成了整数 0，于是报错信息是KeyError: 0。问题的本质都一样：向字典里追加新键的值时，没有先初始化。

6.2 顺着堆栈层层剥开

遇到这个异常，我没有急着加 try-except，而是先打印了scores_by_student和student_id：

print("student_id:", student_id, type(student_id)) print("scores_by_student:", scores_by_student)

结果输出：

student_id: 0 <class 'int'> scores_by_student: {}

看到空字典就明白了：这确实是第一次写入，而代码没有初始化。scores_by_student[0]当然会报KeyError: 0。根源是“写入前没建默认键”，解决方案很简单，把scores_by_student改成defaultdict(list)，或者用setdefault。

6.3 修复与回归测试

我把字典声明改为：

scores_by_student = defaultdict(list)

然后重跑，脚本正常通过了。最后我还补了一条校验：确保最后统计总分时，学生 ID 存在，不然可能访问一个不存在的学生。回归测试也很简单，分别用只有一行数据、有多行数据、ID 是 0、ID 是字符串 "0" 的四种情况跑一遍，确认KeyError: 0/KeyError: '0'都不会再出现。

这个案例虽然简单，却是KeyError: 0最典型的“非读取场景”——写入时因为没有默认键而抛错。很多人在写入字典时意识不到“访问不存在键”不仅会出现在赋值右侧，也可能出现在左侧的链式操作里。记住：d[new_key].method()这种写法，本质上是先读后写，键不存在时就会异常。

7. 把 KeyError: 0 扼杀在襁褓里：日常防坑三板斧

7.1 给字典配上“默认值工厂”

不用再写if key not in d: d[key] = []这种啰嗦代码了，defaultdict就是你的默认值工厂。计数用defaultdict(int)，分组用defaultdict(list)，去重用defaultdict(set)。刚开始可能觉得多了一个导入麻烦，但用习惯后会非常省心。

需要注意的是，defaultdict只在“访问不存在的键”时自动创建默认值，并不会主动为“遍历”或者“批量操作”生成一堆键。同时，如果你用d[0] += 1，它也不会报错，因为defaultdict(int)会先返回 0，再加 1，然后写回。这个特性在统计场景里就是“降维打击”。

7.2 写代码时多打印一次 keys()

排查KeyError: 0最痛的地方是“我根本不知道这个字典里到底有什么键”。所以我在调试阶段有个习惯：在访问字典之前，临时加一行print(list(d.keys())[:10])，看看前几个键长什么样。虽然这行代码到最后会被删掉，但它能帮我快速确认类型和内容。

如果是在 pandas 里，我会打印df.columns.tolist()和df.index[:5]。这两个操作非常便宜，却能在 10 秒内排除掉 80% 的“找错键/找错轴”问题。很多人犯的错误是：df[0]报错后，改为df[0:1]试图取行，结果取到一个 1 行 0 列的 DataFrame，后面又是一堆连锁问题。这都属于没先确认轴标签。

7.3 用单元测试卡住边界数据

KeyError: 0这种异常通常只在特定数据下才触发：数据为空、数据键类型变化、数据缺失某个分组。如果每次都是上线后才发现，那说明测试数据过于“完美”。我建议针对字典访问写几个边界用例：

• 空字典访问0键；
• 字典中存在字符串键"0"，但访问的是整数0；
• defaultdict访问不存在的键后，确认默认值类型正确；
• pandas 场景下，列名不是数字时访问df[0]应当报错或按预期走分支。

把这些用例写进 pytest，能避免很多回归。尤其是当你对底层数据结构做过一次改动（比如从 list 改成 dict，从 int 键改成 str 键）之后，跑一遍测试会让隐患立刻现形。

最后再分享一个我个人的实战体会：看到KeyError: 0，不要条件反射地加 try-except 吞掉它。先花两分钟打印 keys、确认类型、追溯数据源，往往能彻底解决；而 try-except 往往只是把异常推迟到了更后面的逻辑里，到时候数据不对更难查。养成“用默认结构 + 先验证再访问”的习惯，这类异常真的会少很多。