执行mkdocs serve读取codereference.md时触发_ast.ExtSlice报错咨询

这个KeyError: <class '_ast.ExtSlice'>报错来自mkdocstrings的Python代码解析依赖库griffe。_ast.ExtSlice是Python 3.8及更早版本AST里用来表示多维切片（比如NumPy数组常用的arr[1:10, 2:5]逗号分隔切片写法）的节点，你当前安装的griffe版本没有适配这个节点类型，扫描到对应代码时直接触发键不存在的错误。

• 先执行python --version确认运行mkdocs的Python版本，如果是3.8及以下，基本可以确定是版本兼容类问题
• 顺着报错栈的调用链定位：错误触发在handle_attribute逻辑，说明是扫描模块/类属性赋值时出的问题，直接去你要生成文档的目标模块里，找所有写在类定义、模块顶层的多维切片赋值代码，就能定位到触发点
• 执行pip list | grep -E "griffe|mkdocstrings"核对依赖版本，griffe 0.2x之前的旧版本普遍存在这个适配漏洞

按优先级从高到低尝试：

• 升级依赖到最新版：直接执行下面的命令升级相关包，新版本griffe已经修复了ExtSlice节点的解析适配，绝大多数场景升级完直接解决

  pip install --upgrade griffe mkdocstrings mkdocstrings-python
  

• 锁版本场景下临时规避：如果项目依赖锁死不能升级包，找到触发报错的多维切片属性赋值，把它从类/模块顶层挪到__init__方法或者普通函数逻辑里，避开griffe对顶层属性的静态扫描即可
• 升级Python版本：如果项目允许，把构建文档用的Python环境升级到3.9及以上——Python 3.9开始AST层已经移除了独立的ExtSlice节点，统一用普通切片节点表示多维切片，从根源上不会触发这个兼容问题
• 临时绕过问题模块：如果短时间找不到具体触发报错的代码，可以先在mkdocs配置里给mkdocstrings加过滤规则，排除有问题的子模块，先保证文档能正常构建，后续再慢慢定位问题点，配置示例：

  plugins:
    - mkdocstrings:
        handlers:
          python:
            paths: [.]
            selection:
              filters:
                - "!出问题的子模块名"
  

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