💭 常见问题

这里收集了 My Docs 使用过程中常见的问题和解决方案。

安装配置问题

Q: 安装依赖时出现权限错误

A: 使用虚拟环境或添加 --user 参数：

# 使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -r requirements.txt

# 或使用用户安装
pip install --user -r requirements.txt

Q: mkdocs serve 命令找不到

A: 确保正确安装 MkDocs：

# 检查安装
pip list | grep mkdocs

# 重新安装
pip install mkdocs-material

Q: 主题样式不显示

A: 检查主题配置和网络连接：

# mkdocs.yml
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections

内容编写问题

Q: Markdown 文件中的图片不显示

A: 确保图片路径正确，建议使用相对路径：

<!-- 正确 -->
![描述](images/example.png)

<!-- 错误 -->
![描述](/absolute/path/to/image.png)

Q: 代码块语法高亮不工作

A: 检查语言标识和扩展配置：

```python
# Python 代码
def hello():
    print("Hello World")
```

```javascript
// JavaScript 代码
console.log("Hello World");
```

Q: 数学公式渲染异常

A: 启用数学公式扩展：

# mkdocs.yml
markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

构建部署问题

Q: 构建时出现编码错误

A: 确保文件使用 UTF-8 编码：

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

# 转换编码（如果需要）
iconv -f GBK -t UTF-8 input.md > output.md

Q: GitHub Pages 部署失败

A: 检查配置和权限：

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

Q: Vercel 部署后页面空白

A: 检查构建输出和路由配置：

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

功能使用问题

Q: 搜索功能不工作

A: 确保启用搜索插件：

# mkdocs.yml
plugins:
  - search

Q: 导航菜单不显示

A: 检查导航配置和文件路径：

nav:
  - 首页: index.md
  - 指南: 
    - 安装: guide/installation.md
    - 使用: guide/usage.md

Q: 自定义 CSS 不生效

A: 检查 CSS 文件路径和配置：

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

性能优化问题

Q: 页面加载速度慢

A: 优化图片和资源： - 压缩图片大小 - 使用 WebP 格式 - 启用 CDN 缓存

Q: 构建时间过长

A: 使用增量构建和缓存：

# 清理缓存后重新构建
mkdocs build --clean

# 使用增量构建（如果支持）
mkdocs build --dirty

浏览器兼容性问题

Q: 在某些浏览器中样式异常

A: 检查浏览器兼容性： - 确保使用现代浏览器（Chrome 90+, Firefox 88+, Safari 14+） - 检查控制台错误信息 - 测试响应式布局

Q: 移动端显示问题

A: 优化移动端体验：

/* 响应式设计 */
@media (max-width: 768px) {
  .md-content {
    padding: 1rem;
  }
}

版本控制问题

Q: Git 提交时忽略构建文件

A: 配置 .gitignore：

# .gitignore
site/
.cache/

Q: 多人协作时配置冲突

A: 使用环境变量和模板：

# mkdocs.yml
site_name: ${SITE_NAME:-默认名称}
site_url: ${SITE_URL:-https://example.com}

扩展功能问题

Q: 自定义插件不工作

A: 检查插件配置和依赖：

# 插件开发模板
from mkdocs.plugins import BasePlugin

class MyPlugin(BasePlugin):
    def on_page_markdown(self, markdown, page, config, files):
        return markdown

Q: API 文档生成失败

A: 检查代码注释格式：

def example_function(param1, param2):
    """
    函数说明

    Args:
        param1: 参数1说明
        param2: 参数2说明

    Returns:
        返回值说明
    """
    return param1 + param2

安全相关问题

Q: 如何防止 XSS 攻击

A: 配置内容安全策略：

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; script-src 'self' 'unsafe-inline'">

Q: 如何保护敏感信息

A: 使用环境变量和配置文件：

# 使用环境变量
export API_KEY=your-secret-key

---

如果问题仍未解决，请查看 故障排除 或提交 Issue。