PyCharm误将变量标记为‘未解析引用’错误，代码执行正常

DevOps 小满

2026-6-14

PyCharm未解析引用提示

使用PyCharm 2022.3.3社区版时，上述图片中的代码出现“未解析引用”错误提示：函数func_test1中的变量a似乎被对象obj的变量a遮蔽，但函数func_test2中的anythingexcepta无此问题。实际运行Python 3.9脚本时一切正常，输出结果5、12、22符合预期。

问题与解答

1. 该错误为何出现？是否属于变量遮蔽问题？（尽管脚本运行正常）

这是PyCharm静态分析时误判的变量遮蔽场景。Python运行时会遵循LEGB作用域查找规则：内层函数func_inner1里的a会先找局部作用域（只有obj），再找外层func_test1的闭包作用域（参数a），最后才是全局/内置作用域。但PyCharm的静态分析器看到obj.a后，会误以为后续的a是想引用obj的属性，而非外层闭包变量，因此抛出错误提示——但实际运行时Python的作用域逻辑是正确的，所以脚本能正常执行。

2. 为何错误出现在func_test1中，而非func_test2？

因为func_test1的外层参数名是a，和内层代码里obj.a的属性名完全一致。PyCharm的分析器会优先把这种同名情况判定为试图引用对象属性；而func_test2的外层参数名anythingexcepta和obj.a的属性名a完全不同，分析器能明确区分两个标识符，所以不会误判。

3. PyCharm的此行为是否为预期设计？若是，原因是什么？

这属于PyCharm静态分析的预期设计（或者说局限性）。静态分析无法完全模拟Python运行时的动态作用域查找逻辑，为了提前提示可能的变量误用（比如开发者想写obj.a += obj.a却漏写obj.），分析器会对“对象属性名与外层作用域变量名同名”的场景做保守判断，优先标记为潜在错误。虽然会出现误判，但能帮大多数开发者提前发现真正的变量引用问题。

4. 除重命名变量外，是否有办法消除该错误提示？

有几种可行方法：

明确声明闭包作用域：在func_inner1里用nonlocal声明变量，让PyCharm明确识别这是外层闭包的a：
```
def func_test1(a):
    def func_inner1(obj):
        nonlocal a
        obj.a += a
    return func_inner1
```
添加忽略注释：在报错的a行添加注释，告诉PyCharm忽略该检查：
```
obj.a += a  # noqa
```
或者用更针对性的注释：
```
# noinspection PyUnresolvedReferences
obj.a += a
```
调整检查级别：打开PyCharm的Settings/Preferences → Editor → Inspections → Python → Unresolved reference，降低该检查的级别，或者配置特定场景的例外规则。

测试脚本代码

class testClass:
    def __init__(self, a):
        self.a = a

def func_test1(a):
    def func_inner1(obj):
        obj.a += a
    return func_inner1

def func_test2(anythingexcepta):
    def func_inner2(obj):
        obj.a += anythingexcepta
    return func_inner2


obj = testClass(5)

func_1 = func_test1(7)
func_2 = func_test2(10)

print(obj.a)
func_1(obj)
print(obj.a)
func_2(obj)
print(obj.a)

内容的提问来源于stack exchange，提问作者Franky