同一版本PyMuPDF/fitz属性名不一致问题排查求助

你遇到的问题核心是同一版本的PyMuPDF在不同导入场景下，Page对象的文本提取方法命名不一致——有时是新规范的get_text()，有时是旧的getText()。以下是具体的排查方向：

• 确认模块实例的一致性
  在两种场景下分别执行以下代码，对比输出结果：

  import fitz
  print(fitz.__file__)  # 查看模块的实际文件路径
  print(id(fitz))       # 查看模块对象的唯一标识
  

  如果路径或id不同，说明系统中存在多个PyMuPDF实例（比如虚拟环境和全局安装冲突、不同版本残留），即使版本号显示一致，实际加载的模块文件也不一样。

• 分析from fitz import fitz的导入逻辑
  PyMuPDF的包结构中，顶级fitz是一个包，内部还包含同名的fitz模块。直接import fitz和from fitz import fitz导入的是不同对象。在两种场景下执行：

  print(type(fitz))
  print(id(fitz.Page))
  

  如果fitz.Page的id不同，说明两种场景下使用的是不同的Page类定义，自然会导致方法命名差异。

• 检查废弃名称的兼容机制
  PyMuPDF通过动态属性注入实现旧名称的兼容支持。可以在两种场景下执行以下代码，查看方法的存在性和来源：

  import inspect
  print(hasattr(fitz.Page, 'get_text'), hasattr(fitz.Page, 'getText'))
  # 尝试查看方法的定义来源（如果源码可访问）
  if hasattr(fitz.Page, 'get_text'):
      print(inspect.getsource(fitz.Page.get_text))
  if hasattr(fitz.Page, 'getText'):
      print(inspect.getsource(fitz.Page.getText))
  

  另外，检查是否存在控制兼容名称的全局开关（比如fitz.TOOLS.set_alt_names()），确认两种场景下该开关的状态是否一致。

• 排查模块加载顺序与缓存
  在两种场景下打印已加载的模块列表，查看是否有额外的相关模块：

  import sys
  print([k for k in sys.modules if 'fitz' in k])
  

  同时检查脚本的导入顺序——如果某个场景下第三方库或其他代码提前加载了fitz模块，可能会影响后续的类定义。

• 临时方案优化（可选）
  如果你想替代try-except的写法，可以提前绑定正确的方法，减少异常捕获的开销：

  def extract_page_text(page):
      text_method = getattr(page, 'get_text', getattr(page, 'getText', None))
      if not text_method:
          raise AttributeError("Page对象不存在get_text或getText方法")
      return text_method()
  

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