🔍 故障排除指南

详细的问题诊断和解决方案，帮助您快速解决 My Docs 使用过程中的各种问题。

诊断流程

1. 基础检查

# 检查 Python 版本
python --version

# 检查 MkDocs 安装
mkdocs --version

# 检查项目结构
tree -L 2 docs/

2. 环境验证

# 检查依赖安装
pip list | grep mkdocs

# 检查虚拟环境
which python
which mkdocs

3. 配置验证

# 验证配置文件
mkdocs --config-file mkdocs.yml build --verbose

# 检查语法
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

常见错误及解决方案

配置错误

错误: `Config value: 'nav'. Error: Required configuration not provided.`

原因: 导航配置缺失或格式错误解决:

# mkdocs.yml
nav:
  - 首页: index.md
  - 指南: guide/index.md

错误: `Config value: 'theme'. Error: The "material" theme is not installed`

原因: Material 主题未安装解决:

pip install mkdocs-material

构建错误

错误: `File not found: docs/index.md`

原因: 文件路径错误或文件不存在解决:

# 创建缺失的文件
mkdir -p docs
touch docs/index.md

# 或修改配置指向正确路径
docs_dir: src  # 如果文档在 src 目录

错误: `UnicodeDecodeError`

原因: 文件编码问题解决:

# 检查文件编码
file -i docs/*.md

# 转换编码
iconv -f GBK -t UTF-8 input.md > output.md

部署错误

错误: GitHub Pages 404

原因: 构建输出路径错误解决:

# mkdocs.yml
site_dir: site
site_url: https://username.github.io/repo-name

错误: Vercel 部署失败

原因: 构建配置错误解决:

// vercel.json
{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/site/$1"
    }
  ]
}

性能问题诊断

构建速度慢

# 分析构建时间
time mkdocs build

# 启用详细日志
mkdocs build --verbose

# 清理缓存
mkdocs build --clean

页面加载慢

诊断步骤: 1. 检查网络请求 2. 分析资源大小 3. 优化图片和静态资源

优化方案:

# mkdocs.yml
extra_css:
  - styles/optimized.css

extra_javascript:
  - js/optimized.js

功能异常诊断

搜索功能不工作

检查清单: - [ ] 搜索插件已启用 - [ ] 构建包含搜索索引 - [ ] 浏览器控制台无错误

调试命令:

# 检查搜索索引
ls site/search/

# 验证插件配置
mkdocs build --verbose | grep search

导航菜单异常

诊断步骤: 1. 检查导航配置语法 2. 验证文件路径存在 3. 查看构建日志

配置示例:

nav:
  - 首页: index.md
  - 用户指南:
    - 安装: guide/installation.md
    - 使用: guide/usage.md
  - API 参考: api/index.md

浏览器兼容性问题

现代浏览器支持

支持的浏览器: - Chrome 90+ - Firefox 88+ - Safari 14+ - Edge 90+

降级方案

/* 兼容性处理 */
.md-container {
  display: flex;
  display: -webkit-flex;
}

/* 特性检测 */
@supports (display: grid) {
  .md-grid {
    display: grid;
  }
}

网络和CDN问题

CDN 缓存问题

解决方案:

# 强制刷新缓存
curl -X PURGE https://your-domain.com/asset.css

# 版本化资源
asset.css?v=1.0.0

资源加载失败

诊断工具:

// 控制台检查
console.log('资源加载状态:', performance.getEntriesByType('resource'));

日志和调试

启用详细日志

# MkDocs 详细日志
mkdocs serve --verbose

# 构建详细日志
mkdocs build --verbose

# 仅验证配置
mkdocs --config-file mkdocs.yml build --dry-run

浏览器开发者工具

常用命令:

// 检查控制台错误
console.error('错误信息');

// 网络请求监控
// 打开 Network 标签页

// 性能分析
performance.mark('start');
// ... 操作 ...
performance.mark('end');

自动化诊断脚本

环境检查脚本

#!/usr/bin/env python3
import sys
import subprocess
import yaml

def check_environment():
    """检查运行环境"""
    checks = [
        ("Python版本", ["python", "--version"]),
        ("MkDocs安装", ["mkdocs", "--version"]),
        ("配置文件", lambda: yaml.safe_load(open('mkdocs.yml'))),
    ]

    for name, check in checks:
        try:
            if callable(check):
                result = check()
            else:
                result = subprocess.run(check, capture_output=True, text=True)
            print(f"✅ {name}: 正常")
        except Exception as e:
            print(f"❌ {name}: 错误 - {e}")

if __name__ == "__main__":
    check_environment()

构建验证脚本

#!/bin/bash
# build-check.sh

echo "开始构建验证..."

# 清理构建
rm -rf site/

# 执行构建
if mkdocs build; then
    echo "✅ 构建成功"

    # 检查关键文件
    if [ -f "site/index.html" ]; then
        echo "✅ 首页文件存在"
    else
        echo "❌ 首页文件缺失"
    fi

    # 检查搜索功能
    if [ -f "site/search/search_index.json" ]; then
        echo "✅ 搜索索引存在"
    else
        echo "❌ 搜索索引缺失"
    fi
else
    echo "❌ 构建失败"
    exit 1
fi

紧急恢复方案

快速回滚

# 回滚到上一个可用版本
git checkout HEAD~1

# 重新部署
mkdocs build
mkdocs gh-deploy

备用部署方案

# 使用简单HTTP服务器临时部署
cd site
python -m http.server 8000

# 或使用 nginx
docker run -v $(pwd)/site:/usr/share/nginx/html -p 80:80 nginx

获取帮助

自助诊断

查看本文档的常见问题部分
检查项目 Issue 列表
搜索相关错误信息

社区支持

GitHub Issues
官方文档
社区论坛

专业支持

如需专业技术支持，请联系开发团队。

最后更新: 2024年1月