Python 可变默认参数陷阱：一次踩坑与彻底修复

> 分类：Bug 排查 | 语言：Python | 严重程度：🔴高

![Bug复现流程图](https://mrdoc.wangziheng.vip/media/202605/2026-05-18_134446_9979230.060037870670211935.png)

## Bug 现象

当你定义一个函数，使用可变对象（`list`、`dict`、`set`）作为默认参数时，多次调用之间会出现**数据"串味"**的诡异现象：

```python
def append_to(elem, lst=[]):
    lst.append(elem)
    return lst

print(append_to(1))  # [1]     ✅ 看起来正常
print(append_to(2))  # [1, 2]  ❌ 为什么有 1？
print(append_to(3))  # [1, 2, 3] ❌ 数据在"长大"！
```

第一次调用返回 `[1]`，第二次没传旧数据却返回 `[1, 2]`，第三次变成 `[1, 2, 3]`——你没传旧数据，但旧数据自己"长出来了"。

这不是语法错误，不会报错，不会抛异常，但它会让你的程序在不知不觉中产生**隐蔽的逻辑 Bug**，排查极为困难。

![错误堆栈可视化](https://mrdoc.wangziheng.vip/media/202605/2026-05-18_134447_4740840.7205597781011275.png)

## 复现步骤

1. 定义一个使用 `lst=[]` 作为默认参数的函数
2. 第一次调用 `append_to(1)`，返回 `[1]`，符合预期
3. 第二次调用 `append_to(2)`，返回 `[1, 2]`，出现上一次的数据
4. 第三次调用 `append_to(3)`，返回 `[1, 2, 3]`，数据持续累积
5. 检查函数默认值：`append_to.__defaults__` → `([1, 2, 3],)`，确认是同一个列表对象

## 根因分析

**核心原因：Python 默认参数值在函数定义时（Definition Time）求值，而非运行时（Call Time）。**

当你写下 `def func(lst=[])` 时：

1. Python 解释器在**编译函数定义时**，就创建了 `[]` 这个列表对象
2. 这个列表对象被绑定到函数的 `__defaults__` 属性上
3. 每次调用函数且**未传该参数**时，`lst` 都指向**同一个列表对象**
4. 任何对 `lst` 的修改（`append`、`extend`、`pop`）都会**持久化**到这个共享对象

可以验证：

```python
def f(lst=[]):
    lst.append(1)
    return lst

print(f.__defaults__)  # ([],)
f()
print(f.__defaults__)  # ([1],)  — 默认值被修改了！
f()
print(f.__defaults__)  # ([1, 1],)  — 持续累积
```

**不只是 `list`，所有可变对象都有这个问题：**

- `dict`：`def f(cache={})` → 多次调用共享同一个字典
- `set`：`def f(items=set())` → 多次调用共享同一个集合
- `deque`：`def f(history=deque())` → 多次调用共享同一个双端队列
- 自定义类实例：`def f(config=MyConfig())` → 多次调用共享同一个实例

![修复对比图](https://mrdoc.wangziheng.vip/media/202605/2026-05-18_134447_9590030.4661343832958146.png)

## 修复方案

### 修复前（Bug 代码）

```python
def append_to(elem, lst=[]):  # ❌ 可变默认值
    lst.append(elem)
    return lst
```

### 修复后（正确代码）

```python
def append_to(elem, lst=None):  # ✅ 用 None 占位
    if lst is None:
        lst = []  # 每次调用创建新列表
    lst.append(elem)
    return lst
```

**修复后的行为：**

```python
print(append_to(1))  # [1] ✅
print(append_to(2))  # [2] ✅  每次都是全新列表
print(append_to(3))  # [3] ✅
```

### dataclass / Pydantic 中的修复

```python
# ❌ dataclass 错误写法
from dataclasses import dataclass

@dataclass
class Config:
    items: list = []  # ValueError: mutable default!

# ✅ dataclass 正确写法
from dataclasses import dataclass, field

@dataclass
class Config:
    items: list = field(default_factory=list)
```

```python
# ❌ Pydantic 错误写法
from pydantic import BaseModel

class Model(BaseModel):
    tags: list = []  # 可能被静默复用

# ✅ Pydantic 正确写法
from pydantic import BaseModel, Field

class Model(BaseModel):
    tags: list = Field(default_factory=list)
```

### 关键细节

- `is None` 必须用 `is`，不能写 `== None`（语义和性能都不对）
- 如果函数需要支持传入空列表（如 `func(5, [])`），`if lst is None` 逻辑依然安全，不会误判
- 若默认值需是 `dict` 或 `set`，同样适用 `None + 初始化` 模式

![预防检查清单](https://mrdoc.wangziheng.vip/media/202605/2026-05-18_134448_4689580.5077665307446108.png)

## 预防措施

1. **永远不要用可变对象当默认参数** — `[]`、`dict()`、`set()` 一律改用 `None`
2. **函数体内初始化** — `if x is None: x = []`
3. **dataclass 用 `field(default_factory=...)`** — 不要直接赋值可变对象
4. **Pydantic 用 `Field(default_factory=...)`** — 同理
5. **开启静态检查** — pylint `W0102`、flake8 `B006` 规则会自动检测
6. **不要用 `lst=[] or []` 技巧** — `[]` 仍然会被提前计算，陷阱照旧
7. **代码审查重点检查** — 函数定义中的默认参数是高危区域
8. **PyCharm 警告不要忽略** — "Default argument value is mutable" 是真实风险提示

## 扩展阅读

- [Python 官方 FAQ: Why are default values shared between objects?](https://docs.python.org/3/faq/programming.html#why-are-default-values-shared-between-objects)
- [Flake8 B006 规则说明](https://flake8-bugbear.readthedocs.io/en/latest/plugin.html#B006)
- [Digg 公司因可变默认参数导致内存泄漏的真实案例](https://stackoverflow.com/questions/1132941/least-astonishment-and-the-mutable-default-argument)
- [Python Tricks: Mutable Default Arguments](https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments)