如果你写过一阵子 Python大概率在某个深夜被同一个报错折磨过def update(): count 1跑起来直接甩给你一句UnboundLocalError: local variable count referenced before assignment明明count在外面定义得好好的函数里只是给它加一怎么就“local variable referenced before assignment”了那一刻你可能会骂 Python 不讲道理。我当年第一次撞上这个错是在写一个简单的请求计数器时。查了半小时资料才搞清楚 Python 对“全局变量”有一套自己的脾气。后来带过不少新同事发现几乎每个人都会在这个问题上踩一轮坑只是深浅不同。所以今天干脆把 Python 全局变量这件事从头到尾拆开讲一遍从语言规则到工程实践从简单的global声明到多文件协作、线程安全、代码组织一次说透。这篇东西适合刚入门 Python、被global折腾过的新手也适合写过一阵子但总觉得全局变量用着别扭、想搞明白“到底该怎么管全局状态”的开发者。我尽量不堆术语用大白话加能直接跑的代码把原理和实操都讲清楚。1. 先搞懂 Python 的变量查找规则LEGB在聊global这个关键字之前必须先理解 Python 是怎么决定“你写的这个变量名到底指向谁”的。Python 在运行一个函数时查找变量的顺序是固定的Local当前函数内部Enclosing外层嵌套函数也就是闭包的外层Global模块级别的全局命名空间Built-inPython 内置的命名空间比如len、print、max这就是著名的 LEGB 规则。函数内部读取一个变量时Python 按照 L→E→G→B 的顺序去找找到哪个算哪个。但是注意赋值和读取的处理方式不一样。这就是前面那个count 1报错的根源。Python 编译器在编译函数体的时候如果发现某个名字出现在赋值语句的左侧它就会直接把这个名字标记为“本地变量”哪怕你在函数外面已经定义过同名变量。也就是说函数里一旦写了count 1count在 Python 眼里就是一个“局部的、还没被赋值的名字”运行时自然就报“referenced before assignment”了。这个设计初看很反直觉但仔细想想是合理的它不是故意为难你而是为了避免你写出一个不小心就改到全局变量的函数。JavaScript 当年就有这个毛病随便写个变量名可能就把全局的覆盖了调试起来痛不欲生。Python 选择了一种更保守的策略——你不显式声明“我要修改全局变量”我就默认你在创建局部变量。明确了这一点下面所有关于global的讨论就顺理成章了。2. global 声明修改变量的正确姿势2.1 什么时候必须写 global规则只有一条你想在函数内部重新绑定一个模块级变量的名字就必须用global声明。重新绑定指的是让这个名字指向一个新对象。包括但不限于操作是否属于重新绑定是否需要 globalcount count 1是需要count 1是需要config {...}是需要data.append(x)否原地修改对象不需要data[0] 100否原地修改对象不需要del data[0]否原地修改对象不需要记住这一条你就不会再犯“改了列表为什么没生效”这种错误。global声明的作用是告诉 Python 编译器这个名字不要当作局部变量请直接绑定到模块全局命名空间。举个例子count 0 def reset(): global count count 0 def increment(): global count count 1 increment() increment() print(count) # 2 reset() print(count) # 0不加globalincrement里的count就是一个全新的局部变量跟外面的count半毛钱关系没有。加了之后它操作的就是模块全局命名空间里的那一个。2.2 为什么 Python 非要你写 global这个问题经常有人问既然global这么麻烦为什么不直接让函数里的赋值默认改全局变量答案前面提过——安全性。如果函数内部赋值默认修改全局那么一段很长的代码里某个嵌套函数内部不小心写了个跟全局同名的变量就可能无声无息地污染整个程序的运行状态。这种 bug 一旦出现排查成本极高。而 Python 的规则是你想改全局就得显式声明“我知道我在改全局我负责”。这种“显式优于隐式”的设计哲学贯穿了 Python 的方方面面。我自己是认同这个设计的。写久了你会发现代码里需要真正修改全局变量的场景其实是少数。大部分时候我们只是需要读取全局变量的值或者把一个对象传进函数里修改其中一个字段——这不涉及重新绑定所以不需要global。2.3 别把 global 写错了位置global声明必须出现在函数内部、对该变量进行任何使用之前。一个常见错误是把它写在函数外面或者写在已经使用过该变量之后x 1 def foo(): print(x) # 此时已经确定 x 是全局读 global x # SyntaxError: name x is used prior to global declaration更典型的一种写法是放在函数内变量使用之后x 1 def foo(): global x x 10这个没问题因为声明在使用之前。要强调的是global的生效范围是整个函数体不是只影响声明点之后的代码。你一旦写了global x函数内部所有对x的引用都会被当作全局变量来处理。2.4 多变量声明与 globals() 的隐蔽用法global可以在一行声明多个变量def setup(): global host, port, timeout host localhost port 8080 timeout 30另外还有一个不大常用但偶尔派得上用场的函数——globals()。它返回一个字典展示当前模块的全局命名空间。你可以通过这个字典动态读取甚至修改全局变量def set_var(name, value): globals()[name] value这种写法适合做动态配置注入、插件系统之类的场景但我个人不推荐在业务代码里频繁用。原因很简单字符串形式的变量名不具备静态代码的可读性出错了 IDE 也查不到只能在运行时暴雷。偶尔用在调试脚本上还好日常业务代码尽量别这么写。3. 不可变对象、可变对象与共享状态的迷雾3.1 为什么 append 不需要 global重新赋值却需要前面表格里已经列了关键区别。这里展开讲一下底层原理。Python 里的一切都是对象变量名只是指向对象的一个标签。当你执行data.append(x)时你是在“调用data指向的那个列表对象的方法”这个列表对象在内存里是唯一的一份你通过.append修改的是这个对象内部的内容。标签本身没有变还是指向同一个对象所以不需要global。但是当你执行data []时你是让data这个标签重新指向了一个新的空列表。在函数内部这个重新绑定的动作默认被解释为“创建一个局部变量”所以如果你想让外部的data也指向新列表就必须global data。这个道理其实跟“传递引用”和“传递值”的讨论很接近。Python 的函数参数传递就是“传对象引用”对可变对象来说函数内原地修改会反映到外部对象上一旦重新赋值就切断了跟原对象的联系。3.2 典型案例函数内清空列表有一次同事拿了一段代码来问为什么函数里调用了data.clear()外面数据居然变了。因为clear()是原地清空直接修改列表对象内部结构不需要global。但如果你想“把这个变量重置为空列表”那就有区别了data [1, 2, 3] def reset_to_empty(): # 错误这会创建局部变量 data [] def reset_to_empty_correct(): global data data []后者才符合预期。前者运行后外面的data依然是[1, 2, 3]。同样的道理适用于 dict 的update、pop、popitem以及 set 的add、discard、remove。背后就一句话原地改对象内容不需要 global换新对象需要。3.3 函数内给可变对象赋值字典键另一个常用操作是往全局字典里写入键值cache {} def set_cache(key, value): cache[key] value # 不需要 global这里没有重新绑定cache这个名字只是原地修改字典内部的内容所以也不需要global。但是def reset_cache(): global cache cache {} # 想让外部变量也指向全新字典必须 global这两者的区别一定要记牢因为排查 bug 的时候80% 的“全局变量改了没生效”都出在这个点上。3.4 从函数返回新对象再赋值给全局变量还有一种很自然的写法我自己也常犯config {} def load_config(path): new_config {} # 假设这里从文件读数据填进 new_config global config config new_configglobal config写在赋值语句之前确保config在全局命名空间里被重新绑定。需要注意global声明放的位置——它可以在new_config读完之后写只要在config赋值之前就行。放在函数最顶部更清晰我是建议养成都写在函数开头的习惯。4. 多文件协作全局变量在模块之间的正确用法4.1 from import 和 import 的陷阱写小脚本的时候全局变量都堆在一个文件里倒也没什么问题。但一进入多模块的项目情况就复杂了。假设有一个配置文件config.py# config.py setting default另一个业务模块worker.py想要修改这个配置# worker.py from config import setting def update(): setting changed这段代码跑起来你会发现在config.py里setting还是default——因为update()里修改的只是worker.py这个模块自己的局部变量跟config.py里那份全局变量毫无关系。那用import config呢# worker.py import config def update(): config.setting changed这才是正确姿势。因为你拿到的config是模块对象本身通过config.setting changed修改的是那个模块对象上的属性也就是真正全局命名空间里的那个变量。很多人被from ... import ...坑过之后才明白from config import setting的本质是把config.setting的当前值拷贝一份绑定到当前命名空间的setting上之后两边就再也没有联系了。而import config拿到的是模块对象本身通过属性访问的方式操作始终指向同一个底层对象。4.2 推荐的模块级全局变量组织方式多文件项目里我建议把所有可变全局状态集中到一个地方管理最省心的做法是搞一个state.py# state.py _current_user None _request_id 0 _settings {} def get_current_user(): return _current_user def set_current_user(user): global _current_user _current_user user def next_request_id(): global _request_id _request_id 1 return _request_id别的模块统一通过state.set_current_user(...)、state.get_current_user()来访问。好处是一、全局状态只在state.py一个文件里修改出问题知道往哪找二、可以在 setter 里加日志、校验将来排查方便三、代码可读性高state.set_current_user(user)一眼就能看出这是在改全局状态。你可能觉得这绕了一大圈跟直接用全局变量有什么区别区别在于直接裸用全局变量项目里任何一个文件想改就改最后你查“这个变量是在哪变成这样的”会查到吐收口到state.py之后所有修改路径都收在几个函数里配合日志或断点很快就能定位。4.3 导入顺序与初始化时机的坑模块级别的全局变量是在 import 该模块时执行并初始化的。这带来一个隐蔽问题如果你在模块顶层做了耗时操作比如读取数据库、请求远端配置那么任何import这个模块的代码都会被阻塞。我之前见过一个项目config.py顶层直接加载了一份大的路由表结果一个只用到其中两个常量的工具脚本不得不白白等好几秒。后来把加载逻辑放进load()函数由需要的模块显式调用问题才解决。原则是模块顶层只放常量定义和轻量初始化重活交给函数。5. 进阶取舍什么时候不该用全局变量5.1 全局变量的代价全局变量最大的优势是省事随处可读不用传参。但代价也很明确隐式耦合任何函数都可能悄悄依赖某个全局状态改动一个值会影响所有读取它的地方但代码里看不出这种依赖关系。难以测试测试时想构造不同前置条件只能反复改全局值容易污染其他测试用例。线程不安全多线程环境下多个线程同时读写同一个全局变量如果没有锁轻则竞态条件重则数据错乱。可读性差你想知道某个变量当前的值得梳理整个项目的赋值路径脑力消耗极大。5.2 替代方案一把状态封进类实例这是我最常用的替代手法。与其用全局变量不如定义一个类把状态挂在实例上class AppState: def __init__(self): self.user None self.request_id 0 def next_request_id(self): self.request_id 1 return self.request_id # 在启动入口创建唯一实例 app_state AppState()然后你可以在任何需要的地方把这个实例传进来或者在模块里保存这个实例的引用。测试时你只需要创建一个全新的AppState()实例就能隔离测试数据。这比起全局变量的“改来改去”干净太多了。5.3 替代方案二闭包与 nonlocal对于同一个函数内需要保存状态的场景用闭包比全局变量更优雅def create_counter(): count 0 def increment(): nonlocal count count 1 return count return increment c1 create_counter() c2 create_counter() print(c1()) # 1 print(c1()) # 2 print(c2()) # 1nonlocal跟global的区别在于nonlocal处理的是嵌套函数作用域Enclosing里的变量而不是模块全局。这个方案最直观的好处是计数器实例是独立的——c1和c2互不影响。如果用全局计数器你就得手动管理多个计数器变量麻烦得很。这对应了 LEGB 里的 E值得掌握。5.4 替代方案三依赖注入还有一种更彻底的办法把状态作为函数参数显式传下去。一开始可能会觉得繁琐但好处是函数的依赖一目了然测试时直接传假数据不需要关心全局被改成了什么样。def handle_request(req, state): user state.user # ...依赖注入不是 Python 特有的概念但在 Python 这种动态语言里尤其好用因为没有类型系统的束缚你随时可以替换实现。5.5 全局变量合理的应用场景话又说回来全局变量也不是洪水猛兽。以下场景用全局变量是完全合理的程序级配置比如日志级别、字体大小、主题设置读多写少。常量集合比如颜色表、状态码映射这些本质上不是状态是常量。缓存容器配合前面讲的“原地修改”作为程序运行期的共享缓存。全局唯一的数据库连接池、日志器实例。关键在于状态变化频率低、修改路径少。如果你发现一个全局变量在项目里被几十处修改那就该考虑重构了。6. 多线程与异步全局变量怎么“炸”的6.1 典型竞态场景Python 有 GIL 不假但 GIL 并不能保证你在业务层面的“读改写”操作是原子性的。看这个例子counter 0 def increase(): global counter for _ in range(100000): counter 1开两个线程同时跑increase()最后counter大概率不是 200000而是 199997、199998 之类的数。原因是counter 1在字节码层面是“读取旧值、加一、写回新值”三步线程可能在“读取”和“写回”之间被切换导致两个线程同时基于旧值计算结果互相覆盖。这个坑在并发场景下尤其明显。解决办法也很常规import threading lock threading.Lock() def increase(): global counter, lock for _ in range(100000): with lock: counter 1记住GIL 不等于“所有操作都线程安全”。涉及全局变量的复合操作还是要靠锁。6.2 异步环境contextvars 的登场Python 3.7 引入的contextvars是另一种全局状态管理工具。它特别适合异步并发场景比如 Web 框架中保存“当前请求的用户身份”。用法很直观import contextvars current_user contextvars.ContextVar(current_user) # 在请求入口设置 current_user.set(user) # 在任意协程里读取 user current_user.get()跟全局变量的区别在于ContextVar的值是跟上下文绑定的。每个异步任务可以带着自己的“上下文”互不干扰。同样的代码用全局变量存 users 列表两个并发请求就会互相覆盖用ContextVar不同请求各拿各的值完美隔离。如果你写过 Web 后端应该已经接触过这类机制的封装典型的如某些框架的请求上下文对象。它是全局变量在高并发异步世界里的一个重要升级替代品。6.3 进程级全局 vs 线程级全局还有一个要注意的层次问题多进程下每个进程都有一份独立的全局变量A 进程改了B 进程看不到。这是很多做多进程服务的同学会踩的坑——以为自己改了全局配置就能让所有 worker 生效结果只有当前进程收到了。进程间共享状态正确的思路是用中间存储比如数据库、消息队列、共享内存。不要指望 Python 全局变量跨进程同步。这个认知能省下不少深夜排查时间。7. 常见问题速查与避坑清单最后整理一张问题速查表都是我见别人踩过或者自己踩过的典型情况现象根本原因解决办法函数内赋值报 UnboundLocalError赋值语句让 Python 把名字当作局部变量加global声明append生效了重新 []没生效原地操作无需 global重新绑定需要重新赋值时加globalfrom config import x修改后原模块没变from import拷贝的是引用改为import config用config.x ...多线程跑计数器结果不对不是原子操作加锁或改用线程安全数据结构多进程改全局变量不生效每个进程独享一份全局命名空间改用外部存储模块顶层加载过慢顶层执行了重逻辑包裹进函数需要时显式调用测试用例间互相污染测试里互相改全局值改用类实例或依赖注入另外还有几个补充建议不要用global去声明一个只在函数内部使用的变量。我看到过有人为了省事随手把函数内的临时变量也global了这会造成意外的全局污染。调试时想确认某个名字是不是全局变量可以打印globals()看看有没有它。用pdb调试时p variable可能会显示“局部变量未定义”这时候你就应该想到是不是忘记global了。函数命名上可以做点文章专门负责修改全局状态的函数名字里带上set_或update_前缀这样读代码的时候能一眼看出“这里有副作用”。我个人在实际项目里的习惯是把全局变量的使用收敛到三个地方常量集永远只读不改。配置模块启动时加载运行期极少修改。状态模块只有state.py里的函数能改其他模块只读。然后再加一条线程安全纪律任何跨线程共享的可变全局状态都配锁。做到这几点Python 的全局变量就不会再给你半夜制造惊喜。最后再分享一个小技巧如果你正在用global管理的状态开始变多不妨停下来思考一下能不能把它塞进一个实例对象里用self.xxx访问。很多时候这一步重构做完代码的清晰度会提升不止一个档次。全局变量本身没有错错的是滥用。理解了它的边界你就能在合适的场合用它该绕开的时候果断绕开。