Python字典遍历中修改键触发RuntimeError：底层原因与四种安全方案

脚本专家

在Python开发中，字典是最常用的数据结构之一。但在遍历字典的同时修改键（例如重命名键、添加新键或删除键），会触发一个典型的RuntimeError："dictionary changed size during iteration"。这个错误并非Python不可理喻，而是哈希表内部机制的安全保护。

一、错误触发场景
以下四种操作都会报出RuntimeError：

2. d = {"a": 1, "b": 2, "c": 3}
3. # 场景1：for key in d 直接删除
4. for key in d:
5.     if key == "b":
6.         del d[key]
7. # 场景2：for key in d.keys() 删除
8. for key in d.keys():
9.     if key == "b":
10.         del d[key]
11. # 场景3：遍历时新增键
12. for key in list(d.keys()):
13.     d[f"{key}_new"] = d[key]
14. # 场景4：先增后删（修改键名）
15. for key in d.keys():
16.     new_key = f"new_{key}"
17.     d[new_key] = d.pop(key)

复制代码

唯一安全的是修改已有键的值（不改变键集）：

2. for key in d:
3.     d[key] = d[key] * 2  # 安全，不改变表结构

复制代码

二、底层原因：哈希表与迭代器失效
Python字典底层是一张哈希表（散列表）。每个键通过哈希函数映射到槽位。当槽位不够时，字典会扩容（rehash），将原有元素重新放置到新表。迭代器持有的是旧表的指针，一旦字典大小在迭代过程中变化（增删键），迭代器可能指向错误的槽位（空洞或越界）。因此Python设计者直接选择了“检测到大小变化就抛异常”，避免更隐晦的数据错误。

三、四种安全解决方案及对比

方案1：复制键列表
将当前所有键复制为一个独立列表，迭代这个列表而不是字典本身。

2. orders = {
3.     "A001": {"status": "paid", "amount": 299},
4.     "A002": {"status": "unpaid", "amount": 150},
5.     "A003": {"status": "paid", "amount": 399},
6. }
7. for key in list(orders.keys()):
8.     if orders[key]["status"] == "paid":
9.         new_key = f"PAID_{key}"
10.         orders[new_key] = orders.pop(key)
11. print(orders)

复制代码

优点：简单直观，代码可读性好。
缺点：对于数百万键的大字典，复制列表会消耗额外内存和创建时间。

方案2：创建新字典
不修改原字典，而是构造一个符合要求的新字典。

2. new_orders = {}
3. for key, value in orders.items():
4.     if value["status"] == "paid":
5.         new_key = f"PAID_{key}"
6.     else:
7.         new_key = key
8.     new_orders[new_key] = value
9. orders = new_orders
10. print(orders)

复制代码

优点：原字典不变，适合函数式风格，适合后续只读场景。
缺点：同样需要额外内存，如果字典极大可能会有性能压力。

方案3：字典推导式（适合过滤场景）
直接生成新字典，适合删除不符合条件的键。

2. d = {"a": 1, "b": 2, "c": 3, "d": 4}
3. d = {key: value for key, value in d.items() if value >= 5}
4. print(d)

复制代码

优点：语法简洁，表达力强。
缺点：不适合需要修改键名的场景（可以结合条件表达式变通）。

方案4：先收集要修改的键，统一处理
遍历前用列表收集所有需要修改的旧键，再在循环外统一进行添加/删除。

2. keys_to_modify = [key for key, value in orders.items() if value["status"] == "paid"]
3. for old_key in keys_to_modify:
4.     new_key = f"PAID_{old_key}"
5.     orders[new_key] = orders.pop(old_key)

复制代码

本质也是复制了键列表，但逻辑分离，适合复杂规则。

四、实战：过滤字典中值<5的键
错误写法（会报错）：

2. d = {"a": 1, "b": 2, "c": 3, "d": 4}
3. for key in d:
4.     if d[key] < 5:
5.         del d[key]  # RuntimeError

复制代码

正确写法（方案2的变种）：

2. d = {key: value for key, value in d.items() if value >= 5}

复制代码

或使用复制键列表：

2. for key in list(d.keys()):
3.     if d[key] < 5:
4.         del d[key]

复制代码

五、避坑：不要在遍历时使用popitem()
有人试图用while d: key, value = d.popitem() 来避免错误，但popitem()弹出顺序是后进先出（LIFO），无法控制处理顺序，容易导致业务逻辑错误。

六、总结与最佳实践
操作安全性对照表：
- 修改键的值（不增删键）：安全
- 修改可变值的内容（如列表append）：安全
- 删除键：不安全
- 新增键：不安全
- 修改键名（先删后增）：不安全
- 复制键列表后遍历修改：安全
- 创建新字典后赋值：安全
- 字典推导式创建新字典：安全
- 用while+popitem：安全但顺序不可控

推荐优先级：
1. 能用字典推导式（过滤）或新建字典（重命名）时，优先使用，代码简洁。
2. 需要原址修改且内存受限时，复制键列表list(d.keys())是最稳妥的方案。
3. 永远不要在遍历原字典时直接增删键，即使看起来大小不变（如pop配合add），底层仍会被视为大小变化。

记住：迭代器迭代的是字典当前的“视图”，视图改变则迭代器失效。将“修改键”的操作与“遍历”分离开，就能避免这个线上常见的坑。

热心网友6

感谢楼主这么系统地梳理了字典遍历中修改键的坑！之前我只知道复制键列表这一种方式，没想到底层是哈希表迭代器失效的问题。你总结的“操作安全性对照表”很清晰，尤其是区分了“修改键的值安全”和“修改键名不安全”，这个细节之前确实容易忽略。方案2（创建新字典）和方案4（先收集再处理）在实际工程中我可能更常用，逻辑分离后代码维护起来也更舒服。另外避坑部分提到popitem()的LIFO顺序问题也很关键，确实有人会踩这个坑。收藏了，以后给新人培训可以直接引用你这篇！

热心网友6

好文！把哈希表底层机制和迭代器失效讲得很清楚，之前一直只记“不能边遍历边改”，现在终于明白为啥了。方案2创建新字典的那段代码，如果value是可变对象（比如列表），新老字典其实是共享引用的，改value内容会相互影响，建议补充个深拷贝提示。另外实战部分那个过滤值小于5的例子，最后一行 `del d` 是不是笔误？应该是 `del d` 吧？总体非常实用，收藏了。

热心网友6

感谢楼主这么详细的分享，把字典遍历时修改键的坑点、底层原理和四种方案都讲透了。我之前踩过好几次这个RuntimeError，每次都是硬记“不要边遍历边删”，但看了你的哈希表迭代器失效的解释，才真正明白为什么Python要这样设计。四种方案的对比也很实用，特别是方案2创建新字典，适合需要重命名键的场景，而字典推导式在过滤时确实最简洁。还有个细节想确认下：方案1中list(orders.keys())复制的是键的视图，对大字典内存占用大概是什么量级？如果键本身是长字符串，复制列表会不会比复制值更耗内存？再次感谢！