VSCode中spacy的Doc、Span、Token类型提示未知导入符号如何解决

问题根因 #

该报错属于静态类型检查的误报：部分版本的spaCy未在spacy.tokens模块的公开导出声明中包含Doc、Span、Token三个类型，运行时Python允许导入这类非显式导出的符号，因此你的代码可以正常执行，但Pylance做静态分析时找不到对应符号的声明，就会抛出「未知导入符号」的提示。

可用解决方法 #

• 方案一：通用兼容写法（无需修改依赖版本，推荐）
  调整导入方式为静态检查专用的TYPE_CHECKING块，搭配延迟类型标注即可，修改后代码如下：

  from typing import TYPE_CHECKING
  import spacy
  from spacy.language import Language
  
  # 仅静态类型检查时执行该段导入，运行时不执行
  if TYPE_CHECKING:
      from spacy.tokens import Doc, Span, Token
  
  nlp = spacy.load("en_core_web_sm")
  # 类型标注加引号标记为延迟求值，静态检查时会匹配到对应类型
  doc: "Doc" = nlp("some stuff")
  

• 方案二：升级spaCy版本
  3.7及以上版本的spaCy已经补全了类型导出声明，直接执行升级命令后重启VSCode即可：

  pip install -U spacy
  

• 方案三：关闭对应报错提示（不推荐）
  如果你不想调整代码或依赖，也可以在.vscode/settings.json中添加配置，关闭Pylance的缺失导入报错：

  {
    "python.languageServer": "Pylance",
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.diagnosticSeverityOverrides": {
        "reportMissingImports": "none"
    }
  }
  

  该方案会屏蔽所有缺失导入的报错，无法识别真实的导入错误，仅建议临时使用。

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