Python pyright 的严格模式配置

开启pyright严格模式后应先将”reportany”: “warning”、禁用typeignore，再优先补全函数参数/返回值、类属性、模块变量类型，配合typeddict或类型守卫处理字典访问，确保配置路径与python版本一致。

pyright 严格模式开启后报一堆 Any 错误，怎么快速收敛？

pyright 默认不启用严格检查，一旦在 pyrightconfig.json 里设 "typeCheckingMode": "strict"，它会立刻对未标注类型、动态属性访问、隐式 Any 推导等“睁一只眼闭一只眼”的地方亮红灯。这不是配置错了，是它开始认真了。

• 先关掉最干扰的 "enableTypeIgnoreComments": false（默认为 true），否则 # type: ignore 会悄悄绕过检查，掩盖真正该修的问题
• 把 "reportAny": "Error" 改成 "reportAny": "warning"，避免刚开严格模式就被 Any 淹没，先聚焦真正危险的漏标（比如函数返回值、关键参数）
• 对第三方库缺失类型提示的情况，用 typings 目录 + extraPaths 引入 stubs，或临时加 # pyright: reportUnknownVariableType=false 在对应 import 行上方（仅限过渡）

哪些函数/变量必须补类型，否则严格模式下几乎必报错？

pyright 在 strict 模式下对「可推导性」要求极高，不是所有地方都靠猜。以下几类不显式标注，基本逃不过 reportUnknownVariableType 或 reportUnknownArgumentType：

• 函数参数和返回值：哪怕只标一个 -> None，也能让 pyright 对函数体内部变量推导更稳
• 类属性（尤其是实例属性）：self.name: str 必须在 <strong>init</strong> 或使用 <strong>annotations</strong> 显式声明，否则 self.name 访问直接报 reportGeneralTypeIssues
• 模块级变量：如 CONFIG = {...}，推荐写成 CONFIG: dict[str, Any] = {...}，否则整个模块下游引用全变 Any
• 字典键值操作：data["user_id"] 这种，若 data 是 dict 无泛型，pyright 会拒绝推导——要么用 TypedDict，要么加 assert isinstance(data, dict) 配合类型守卫

pyrightconfig.json 里这几个关键字段的实际影响差异

配置项之间有依赖关系，改一个可能触发连锁反应。几个高频调整项的真实作用：

• "typeCheckingMode": "strict" 是总开关，但它本身不控制具体规则；实际行为由下面的 report* 项决定
• "reportUnusedExpression": "none" 和 "reportUnusedVariable": "none" 建议保留为 "none"，否则字符串字面量、装饰器调用这类合法但“无副作用”的表达式也会被当错误
• "include": ["src/*<em>/</em>"] 比 "exclude": ["node_modules", "<strong>pycache</strong>"] 更可靠——pyright 对 exclude 的路径匹配有时会漏，尤其在 monorepo 中嵌套 Python 包时
• "pythonVersion": "3.11" 必须和项目真实运行版本一致，否则像 Self 类型、带括号的生成器注解等新语法会被当成错误

VS Code 里 pyright 提示正常，但命令行 pyright 扫描结果不同？

根本原因是 VS Code 的 pyright 插件默认读取工作区根目录下的 pyrightconfig.json，而命令行执行 pyright 时，它从当前 shell 路径开始向上找配置文件——如果在子目录下运行，很可能加载了错误的 config，甚至没加载到任何配置（退回到 basic 模式）。

立即学习“Python免费学习笔记（深入）”；

• 运行前先确认位置：pwd 和 pyright --version 输出是否含 Config file path
• 统一用 pyright --project /path/to/your/pyrightconfig.json 指定配置，排除路径歧义
• 如果项目用 Poetry 或 venv，确保命令行激活的是同一环境，否则 pyright 可能用系统 Python 解析类型存根，导致 reportMissingImports 误报

类型标注不是为了取悦工具，而是让 pyright 在你改错逻辑前就拦住最典型的拼写、协议错用、生命周期越界。越晚加，修复成本越高——特别是当 Any 已经顺着调用链污染了十几个函数签名之后。