作用域与命名空间

是什么，为什么存在

作用域（scope） 描述名称在源码中的可见范围， 命名空间（namespace） 保存名称与对象之间的绑定。两者回答不同问题：作用域回答「这里能直接写哪个名称」，命名空间回答「这个名称当前指向哪个对象」。把它们都叫作「变量存放位置」，很容易把查找规则与对象生命周期混为一谈。

Python 中的名称不是装对象的盒子。rate = 0.2 会在当前命名空间中建立名称 rate 到浮点对象的 名称绑定（name binding） ，后续赋值可以让同一名称指向另一个对象。多个名称也可以指向同一个对象，所以名称的作用域与对象是否仍然存活不是一回事。

作用域让模块和函数可以复用常见名称，而不必给每个临时值发明全局唯一的名称。函数调用会获得自己的局部绑定，嵌套函数可以读取词法外层绑定，模块则提供可共享的全局绑定。内置名称是最后一层回退，因此 len 和 ValueError 无需导入即可使用。

你会在函数参数、赋值、导入、循环目标、模式匹配和异常处理器中遇到名称绑定。重构时把一条赋值移进函数、在循环中生成回调，或者把模块常量改成局部配置，都可能改变名称解析。理解作用域后，这些行为可以从源码推导，不需要靠试错猜测。

工作原理

Python 按词法嵌套解析普通名称，也就是查看函数定义在源码中的位置，而不是查看运行时由谁调用它。常用的 LEGB 是一条实用查找路径：Local、Enclosing、Global、Built-in。它适合解释函数中的读取，但类代码块、推导式和注解作用域有额外规则，不能只靠四个字母概括。

查找名称之前，编译器会扫描整个函数代码块，判断哪些名称属于局部、自由或全局名称。函数内任何绑定操作通常都会让目标成为该代码块的局部名称，即使赋值写在名称读取之后，或者位于永远不会执行的分支中。因此，UnboundLocalError 的根因往往不在报错行，而在同一函数的另一条赋值语句。

绑定操作不只有 =。形参、def、class、import、for 的目标、with ... as、except ... as、捕获模式和赋值表达式都会绑定名称；del 虽然执行的是解绑，也会影响编译期分类。属性赋值 order.total = 10 与下标赋值 items[0] = 10 修改对象，不会在当前作用域绑定 order 或 items。

普通读取总是选择当前环境中最近的可见绑定。局部名称可以遮蔽同名外层、全局或内置名称，但不会删除那些外层绑定。离开局部代码块后，外层名称仍保持原来的绑定。

global 与 nonlocal

global name 告诉编译器：当前代码块中对 name 的使用和赋值都指向模块全局命名空间。它不表示「在所有模块中全局」，也不创建跨进程或跨线程的共享存储。若名称尚不存在，后续赋值会在当前函数所属模块中创建它。

nonlocal name 指向最近一个已经绑定该名称的外层函数作用域。它不能指向模块作用域，也不能凭空创建外层绑定；找不到目标时，代码会在编译阶段抛出 SyntaxError。内层函数只读取自由变量时无需声明，只有重新绑定外层名称时才需要 nonlocal。

大多数业务函数更适合接收参数并返回新值，因为调用关系直接暴露了状态流向。global 和 nonlocal 不是禁用功能，但它们应匹配真实的状态所有者。若一个修复扩大了状态的生命周期或共享范围，它通常引入了比原报错更难发现的问题。

特殊边界

类体执行时会创建类命名空间，完成后该命名空间成为类的属性字典。类体中绑定的普通名称不会成为方法的外层函数绑定，所以方法应写 self.rate、type(self).rate 或 Pricing.rate，而不是直接写 rate。类体内的未绑定普通名称会转向全局命名空间查找，这又与函数局部名称的行为不同。

列表、集合和字典推导式不会把迭代变量泄漏到包含它们的作用域。生成器表达式也有自己的执行作用域。它们仍能读取外层可见名称，但在类体内不能把普通类属性当成词法外层变量；Python 3.14 的注解作用域是这一规则的特例。

示例

下面三个示例依次展示 LEGB 读取、编译期分类与命名空间检查。输出来自本地 python3 实际运行；示例只使用 Python 3.12 与目标版本 Python 3.14 共有的语义。

跟随 LEGB 查找名称

内层函数 render() 同时读取四层名称。每个名称都只在一个层级绑定，因此输出能直接显示查找结果。

查找是按名称分别进行的，不是先为函数选择一个统一命名空间。heading 在当前局部作用域找到，department 来自词法外层函数，tax_rate 来自模块，len 最后在内置命名空间找到。若更近的作用域绑定同名名称，更外层的绑定就会被遮蔽。

函数从哪里被调用不会改变这条路径。即使另一个函数先绑定 department = "support" 再调用 render()，render() 仍读取定义它的 print_report() 那次调用中的绑定。Python 使用词法作用域，而不是动态作用域。

对比局部、global 与 nonlocal

broken_price() 故意在读取 discount 后赋值。异常被捕获后程序继续运行，从而把三种重新绑定方式放在一份可执行输出中比较。

discount = 10
calls = 0


def broken_price():
    try:
        print(discount)
    except UnboundLocalError as error:
        print(type(error).__name__)
    discount = 20
    return discount


def record_call():
    global calls
    calls += 1


def make_budget(limit):
    remaining = limit

    def spend(amount):
        nonlocal remaining
        remaining -= amount
        return remaining

    return spend


print("local:", broken_price())
record_call()
print("global:", calls)
spend = make_budget(50)
print("nonlocal:", spend(8), spend(7))

UnboundLocalError
local: 20
global: 1
nonlocal: 42 35

broken_price() 中的赋值让 discount 在整个函数体中成为局部名称，所以更早的 print(discount) 不会回退到全局值 10。异常处理结束后，局部绑定被设为 20。该调用没有改变模块中的 discount。

record_call() 明确更新模块绑定，spend() 则更新某次 make_budget() 调用拥有的绑定。再次调用 make_budget(50) 会得到独立的 remaining。若状态不应跨调用共享，参数与返回值通常比 global 更合适。

读取命名空间视图

globals() 与 locals() 让你检查当前命名空间。真实命名空间包含许多实现和运行环境名称，所以示例只选择确定的键，不直接打印整个字典。

REGION = "eu"


class Shipping:
    unit = "kg"
    visible_names = sorted(
        name for name in locals() if not name.startswith("__")
    )


def summarize(order_id):
    subtotal = 25
    names = locals()
    print("function:", sorted(names))
    print("values:", names["order_id"], names["subtotal"])


print("module:", globals()["REGION"])
print("class:", Shipping.visible_names)
summarize("A-17")

module: eu
class: ['unit']
function: ['order_id', 'subtotal']
values: A-17 25

类体执行 locals() 时，映射会成为交给元类构造器的类命名空间；因此 unit 最终可通过 Shipping.unit 访问。函数中的映射包含当前已绑定的形参与局部名称。模块顶层的 locals() 与 globals() 指向同一个命名空间，但函数优化作用域中的行为不同。

Python 3.14 规定，在函数、生成器和协程等优化作用域中，每次 locals() 返回当前绑定的新字典。修改该字典不会写回真实局部变量，后续局部赋值也不会改动之前取得的字典。把 locals() 当作调试快照可以，把它当作赋值接口不行。

陷阱

在赋值前读取同名全局名称

修复方法： 先确定状态归谁所有。优先把值作为参数传入并返回更新值；确实属于模块或外层函数时，分别使用 global 或 nonlocal，并把声明放在首次使用之前。

用 global 掩盖所有权错误

修复方法： 写出状态的生命周期和共享边界。请求状态用参数、返回值或实例保存；只有进程内模块确实拥有该值时才使用 global，并测试两个调用方交错执行。

遮蔽内置名称

修复方法： 使用 records、order_id 和 total 等领域名称。诊断时检查当前局部与全局绑定；不要靠 builtins.list 长期绕过含糊命名。

把类属性当作方法的外层局部名称

修复方法： 实例策略写成 self.rate，类级策略写成 type(self).rate 或明确类名。这样继承和属性覆盖也能按照接口表达，而不是依赖偶然存在的全局名称。

通过 locals() 修改函数变量

修复方法： 动态字段应放进显式字典、数据类或普通对象。locals() 适合诊断和向明确接受映射的 API 提供数据，不是函数局部变量的写入接口。

把作用域当成对象生命周期

修复方法： 分开追踪「哪个作用域可见这个名称」与「哪些引用让对象保持可达」。文件、锁和事务使用上下文管理器显式释放，不要把正确性押在名称离开作用域后的回收时机上。

延伸阅读

• Python 语言参考：名称与绑定
• Python 语言参考：global 语句
• Python 语言参考：nonlocal 语句
• Python 内置函数：locals()
• Python symtable：访问编译器符号表
• Python 编程常见问题：UnboundLocalError