pyright 如何设置才能严格检查未使用的 import_网络技术

发布时间 - 2026-01-24 00:00:00 点击率：次

Pyright 默认不检查未使用 import，需在配置中显式设置 reportUnusedImport = "error" 才报错；其判断受类型注解、TYPE_CHECKING、__all__ 等影响，建议配合 typeCheckingMode = "strict" 提升准确性。

Pyright 本身不把 unused-import 当作类型检查问题，它专注类型安全，而非代码风格或死代码。所以即使你开了 reportUnusedImport，默认配置下也不会报错——它只是“报告”，且默认级别是 none。

需要在 pyrightconfig.json 或 pyproject.toml 中显式开启并提升严重等级：

{
  "reportUnusedImport": "error"
}

或者用 TOML（推荐，更易维护）：

[tool.pyright]
reportUnusedImport = "error"

注意："error" 会让 CI 或编辑器直接标红；若只想警告，可用 "warning"；"none" 就是关闭。

以下情况会导致 reportUnusedImport “失效”，不是配置没生效，而是 Pyright 认为 import 是潜在使用的：

from x import y 中的 y 被注释引用（如 # type: y 或 -> y:），会被视为“被类型提示使用”
import 出现在 if False: 或 if TYPE_CHECKING: 块里，Pyright 默认会分析这些分支
模块级 import 被 __all__ 显式导出，Pyright 认为它可能被外部导入使用
VS Code 的 Pylance 插件版本太旧，或启用了 "python.analysis.typeCheckingMode": "basic"（会禁用部分检查）

单独开 reportUnusedImport 可能漏检，建议配合严格类型模式：

[tool.pyright]
typeCheckingMode = "strict"
reportUnusedImport = "error"
# 可选：避免因 __all__ 导致误判
reportPrivateUsage = "none"

Strict 模式会强制分析所有 import

上下文，包括 TYPE_CHECKING 分支和类型注解中的引用，让未使用判断更准确。但要注意：strict 会同时激活一堆其他检查（如 reportUntypedFunctionDecorator），可能需要一并处理。

真正难的是区分“真没用”和“只在类型系统里有用”——比如 from typing import TYPE_CHECKING 本身从不运行，但它是合法且必要的。Pyright 不会把它标为 unused，这是对的；但如果你手动写了个 import json 却一行都没用到，那它就会立刻报错。