在 Python 中，变量作用域解析是在编译阶段静态执行，而不是在执行阶段动态进行。当 CPython 编译器遇到一个函数定义时，它会遍历抽象语法树，构建一个符号表，将每个名称分类为局部、全局或闭包变量。如果编译器在函数体内的任何地方检测到绑定操作，例如赋值、增强赋值或导入，它会将该名称标记为局部变量，作用于整个作用域。这种设计使虚拟机能够使用优化的 LOAD_FAST 字节码指令，这些指令操作于固定大小的数组，而不是执行较慢的哈希表查找。这种优化是 Python 函数调用性能的基础，但引入了严格的绑定要求。
当一个名称被分类为局部时，编译器会为该名称的所有读取操作生成 LOAD_FAST 字节码指令。运行时，LOAD_FAST 会尝试从帧的局部变量数组的相应索引中检索对象引用。如果该槽位包含一个空指针，表示尚未分配值，则运行时会抛出 UnboundLocalError。即使存在同名的全局变量，也会发生这种情况，因为编译器故意避免发出 LOAD_GLOBAL。该错误明确指出了这一静态作用域决策，使其与 NameError 区分开来。
要解决这个问题，您必须通过声明 global <variable_name> 明确告知编译器该名称指的是全局命名空间。该声明会导致编译器切换到 LOAD_GLOBAL 和 STORE_GLOBAL 字节码指令，它们会在模块的全局字典中动态查找名称。或者，重新构造代码以确保所有局部变量在函数顶部进行初始化，而不是在任何条件逻辑之前被读取。对于嵌套作用域，nonlocal 关键字迫使编译器使用 LOAD_DEREF 来访问闭包单元。这些声明会在编译时改变编译器的绑定决策，防止未绑定的局部变量场景。
threshold = 100 def analyze(data): # 编译器看到下面的 "threshold = ..."，将其标记为局部 if data > threshold: # 抛出 UnboundLocalError return "high" threshold = 50 # 赋值使其成为局部 # 使用 'global' 的解决方案 def analyze_fixed(data): global threshold if data > threshold: # LOAD_GLOBAL 成功 return "high" threshold = 50 # 更新全局变量
一个数据工程团队正在使用 Apache Airflow 构建 ETL 管道。他们在模块级定义了默认配置字典 CONFIG = {"batch_size": 1000}，以便轻松调整处理参数。主要转换函数 process_batch() 最初检查 if len(records) > CONFIG["batch_size"]: 以确定是否需要拆分。后来在函数的特定条件下，代码试图通过 CONFIG = {"batch_size": 500} 来优化内存，从而减少批处理大小。这个模式不小心引发了作用域冲突。
当管道执行时，它在函数的第一行崩溃了，出现 UnboundLocalError： local variable 'CONFIG' referenced before assignment。函数末尾的赋值语句导致 Python 编译器将 CONFIG 视为整个函数体的局部变量。因此，在开始时的比较操作使用 LOAD_FAST 访问了未初始化的局部变量槽。这一失败在关键的生产运行期间中断了数据管道，因为函数无法开始执行。
团队首先考虑将局部重新赋值重命名为 local_config，为减少的批量处理创建一个新字典。这将完全避免阴影问题，并保持全局配置不可变。然而，这种方法需要重构下游代码，这些代码期望名称 CONFIG 反映当前限制。如果开发人员在后续逻辑中忘记使用新的变量名，这将引入潜在的不一致性。追踪同一概念的两个变量名的认知负担使得这个解决方案不那么有吸引力。
另一个选项是在函数的开始处添加 global CONFIG，强制编译器将所有引用视为全局查找。虽然这可以防止错误，但团队拒绝了这个选项，因为在批处理过程中修改全局状态是一个危险的反模式。它防止函数重入，并显著增加单元测试的复杂性。此外，如果代码在多个线程中并行化，还会产生竞争条件。对模块级状态的副作用被认为对生产数据管道是不可接受的。
第三个解决方案是使用 CONFIG["batch_size"] = 500 在原地变更现有字典，而不是重新赋值变量名称。由于这个操作并没有为名称 CONFIG 创建新绑定，因此编译器仍然将其视为全局引用。这避免了 UnboundLocalError，同时允许配置更新在后续调用中持续存在。这被认为是最好的即时修复，尽管团队计划稍后将配置重构为类实例。变更方法保留了现有的 API，同时解决了即时崩溃的问题。
他们实施了第三个解决方案，将重新赋值更改为变更 CONFIG["batch_size"] = 500。管道顺利执行，没有错误，并且配置更改正确应用于后续批次。后来，他们重构了代码，使用注入到函数中的 Pydantic 设置对象。这完全消除了对模块级全局变量的依赖，使函数变得纯粹和可测试。该事件促使对所有 Airflow 操作员进行代码审查，以消除类似的阴影模式。
为什么在函数内部 del 一个变量，随后尝试读取它会引发 UnboundLocalError，而不是回退到全局作用域？
当您在局部变量上执行 del x 时，它会从帧的 f_locals 中删除引用，但不会改变 x 作为局部的静态分类。编译器仍然为后续读取生成 LOAD_FAST。当解释器执行 LOAD_FAST 时，它发现槽为空并引发 UnboundLocalError，而不是回退到全局。这证实了作用域决策在运行时是不可变的。要在删除后访问全局 x，您必须在编译时声明 global x。
默认参数表达式如何避免 UnboundLocalError 陷阱，这揭示了它们的评估时机？
默认参数在函数定义在外部作用域内执行时被计算一次，而不是在函数的局部作用域内。如果您写 def f(val=CONFIG["key"]):， Python 在定义时使用 LOAD_GLOBAL 来解析 CONFIG。即使函数体随后赋值给 CONFIG，使其成为局部，默认值已经被安全捕获。这表明默认值在定义时使用全局作用域，这与函数体的局部执行分开。因此，默认值避免了 UnboundLocalError，如果相同的访问在函数体内发生在赋值之前，将发生该错误。
为什么在类体中永远不会出现 UnboundLocalError，是什么字节码差异使其成为可能？
类体使用 LOAD_NAME 而不是 LOAD_FAST 进行变量访问。LOAD_NAME 在类字典中执行动态查找，然后是全局字典，再然后是内置字典。它不使用预分配的固定槽，因此从不会遇到“未绑定局部”状态。如果在类体中在赋值之前引用一个名称，LOAD_NAME 会继续在全局作用域查找。这种基于字典的方法牺牲了函数局部的速度，换来了在类构造期间所需的灵活性。