这个错误： ``` UnboundLocalError: local variable 'xxx' referenced before assignment ``` 是 Python 中**非常经典且容易困惑的运行时错误**，它**不是语法错误（SyntaxError）**，而是在函数执行过程中、当代码**试图读取一个局部变量，但该变量在当前作用域中尚未被赋值**时抛出的。 --- ### ✅ 一句话本质原因： > **Python 在编译函数时，只要在函数体内对某个变量名执行了赋值操作（`=`），就会将该变量标记为“局部变量”；此后，函数内所有对该变量的读取（即使出现在赋值语句之前）都会被当作访问局部变量——而此时它还未被赋值，于是报 `UnboundLocalError`。** ⚠️ 关键点：**判定“是否为局部变量”的依据是“函数体内是否有赋值”，而不是“赋值语句是否实际执行”。** --- ### 🔍 经典复现示例（必看） ```python x = "global" def foo(): print(x) # ❌ UnboundLocalError! x = "local" # ← 这一行的存在，让整个函数中所有 `x` 都被视为局部变量！ foo() ``` #### ❓ 为什么 `print(x)` 报错？明明上面有全局 `x = "global"`？ 因为 Python **在编译 `foo()` 函数时扫描到 `x = "local"`**，就决定： ✅ `x` 是 `foo` 的**局部变量**（local scope）； ❌ 因此 `print(x)` 就是在**读取一个尚未初始化的局部变量** → `UnboundLocalError`。 > 🧠 类比：Python 的作用域解析是“静态分析 + 运行时检查”，不是按行顺序动态决定作用域。 --- ### ✅ 正确修复方式（按场景分类） #### ✅ 场景 1：你本意是读取全局变量（不修改它） → 使用 `global` 声明（仅当你**确实需要在函数内修改全局变量**时才用） 或更推荐：**避免修改全局，用参数传入** ```python x = "global" def foo(): print(x) # ✅ 现在可以！因为没在函数内给 x 赋值 → 自动向上查找 global foo() # 输出: global ``` ✅ 安全原则：**只要函数内不出现 `x = ...`，Python 就不会把它当局部变量。** --- #### ✅ 场景 2：你确实想在函数内修改全局变量 → 显式声明 `global x` ```python x = "global" def foo(): global x # ✅ 声明：我要操作全局 x print(x) # ✅ OK：读取全局 x x = "modified" # ✅ OK：修改全局 x foo() print(x) # "modified" ``` ⚠️ 注意：`global` 必须在**首次使用该变量前声明**（通常放在函数开头）。 --- #### ✅ 场景 3：你想读取外层嵌套作用域（nonlocal 变量，如闭包） → 使用 `nonlocal x` ```python def outer(): x = "enclosing" def inner(): nonlocal x print(x) # ✅ OK x = "changed" inner() print(x) # "changed" outer() ``` > ✅ `nonlocal` 用于嵌套函数中修改**外层函数的局部变量**（非 global）。 --- #### ✅ 场景 4：你只是想“先判断再赋值”，但逻辑导致提前读取 常见于条件分支中未覆盖所有路径： ```python def calc(flag): if flag: result = 42 return result # ❌ UnboundLocalError if flag is False! calc(False) # → error! ``` #### ✅ 修复：确保所有路径都初始化变量（推荐） ```python def calc(flag): result = None # ✅ 显式初始化（或设默认值） if flag: result = 42 return result ``` 或更 Pythonic（用 `else` 或默认返回）： ```python def calc(flag): if flag: return 42 return 0 # 或 raise ValueError("flag must be True") ``` --- ### 🚫 常见误区（错误修复） | 错误写法 | 为什么错 | |----------|-----------| | `print(x); x = "local"`（无 `global`） | 编译期已定 `x` 为局部 → `print` 访问未赋值局部变量 | | `if False: x = 1; print(x)` | 即使 `x = 1` 永不执行，只要存在赋值语句，`x` 就是局部变量 | | `from __future__ import annotations` 后能解决？ | ❌ 无关。这是类型注解的 future，不影响作用域规则 | --- ### 🔎 如何快速诊断？ 1. **看报错行**：找到 `UnboundLocalError` 提示的变量名和行号； 2. **搜索整个函数体**：有没有对该变量的 `=` 赋值（哪怕在 `if/for/try` 里）？ 3. **确认意图**： - 想读全局？→ 删除函数内所有对该变量的赋值，或加 `global`; - 想读外层局部？→ 加 `nonlocal`; - 想局部使用？→ 确保**所有执行路径都初始化它**（如开头 `x = None`）。 --- ### ✅ 附：完整可运行验证代码 ```python # ✅ 示例1：无赋值 → 读 global g = "I'm global" def f1(): print(g) # OK f1() # I'm global # ❌ 示例2：有赋值 → UnboundLocalError def f2(): print(g) # ← 报错！ g = "local" # ← 这行导致 g 成为局部变量 # f2() # UnboundLocalError # ✅ 示例3：显式 global def f3(): global g print(g) # OK g = "modified in f3" f3() print(g) # modified in f3 # ✅ 示例4：条件未覆盖 def f4(x): if x > 0: y = x * 2 return y # ❌ 若 x <= 0，y 未定义 # f4(0) # UnboundLocalError # ✅ 修复 def f4_fixed(x): y = 0 # 初始化 if x > 0: y = x * 2 return y print(f4_fixed(0)) # 0 ``` ---