MKDocs-material明暗模式切换图标消失，如何恢复显示？

• 清除缓存

  • 浏览器端：按下Ctrl+F5（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新页面，避免浏览器缓存旧资源导致修改不生效
  • 本地构建缓存：删除项目根目录下的site文件夹，再依次执行mkdocs build和mkdocs serve，清除MKDocs的构建缓存

• 检查配置文件正确性
  确保mkdocs.yml里的主题调色板配置只保留light和dark方案，格式如下：

  theme:
    name: material
    palette:
      - scheme: default
        toggle:
          icon: material/weather-sunny
          name: 切换到深色模式
      - scheme: slate
        toggle:
          icon: material/weather-night
          name: 切换到浅色模式
  

  检查是否存在拼写错误，比如toggle字段是否完整，图标路径是否正确

• 升级依赖版本
  执行以下命令检查当前版本：

  pip list | grep mkdocs
  pip list | grep mkdocs-material
  

  如果版本较旧，可能存在已知bug，执行升级命令：

  pip install --upgrade mkdocs mkdocs-material
  

• 排查配置冲突
  暂时注释掉主题配置里的其他自定义项（比如自定义CSS、JS、其他主题参数），只保留最基础的调色板和切换配置，启动服务验证图标是否恢复，再逐步加回其他配置定位冲突点

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