自动清理mkdocs缓存的脚本

自动清理 MkDocs 缓存的脚本：原理、实现与最佳实践

---

📖 目录导读

1. 为什么需要自动清理 MkDocs 缓存？
2. MkDocs 缓存机制详解
3. 自动清理脚本的核心设计思路
4. 实战：编写一键清理脚本（Windows/Linux/macOS）
5. 脚本集成到构建流程（CI/CD 示例）
6. 常见问答 FAQ
7. 总结与建议

---

为什么需要自动清理 MkDocs 缓存？

MkDocs 是一个广受欢迎的静态站点生成器，尤其适合项目文档、知识库、API 说明等场景，随着项目迭代，很多开发者会遇到一个烦人问题：修改 Markdown 文件后，站点布局或内容没有同步更新，这通常是由于 MkDocs 的本地缓存机制导致的。

典型痛点：

• 修改了文档后，运行 mkdocs serve 却显示旧内容。
• 主题样式或配置改动后,页面依然呈现旧布局。
• 构建出的 site 文件夹包含残留文件,导致部署体积膨胀。

自动清理脚本的意义：

• 消除陈旧缓存，确保每次构建或预览都是「干净」状态。
• 避免手动删除 site/ 和 .cache/ 文件夹的重复劳动。
• 在 CI/CD 流水线中保证构建环境一致性,防止缓存污染。

---

MkDocs 缓存机制详解

MkDocs 在本地运行时,主要使用两种缓存：

1 构建输出缓存：site/

• 这是 mkdocs build 或 mkdocs serve 生成的最终静态文件目录。
• 如果你修改了文档但未清空此目录，旧文件可能被保留,导致页面混乱。

2 内部元数据缓存：.cache/（或 __pycache__）

• MkDocs 以及其依赖的 Python 插件（如 mkdocs-material、mkdocs-minify-plugin）会创建缓存。
• 这些缓存存储了文章之间的链接关系、导航结构解析结果等。
• 插件版本升级后,旧的缓存可能导致解析错误。

3 其他缓存来源

• 操作系统文件系统缓存：偶尔也会导致旧文件被「记忆」。
• 浏览器缓存：虽然不在脚本控制范围内,但建议在本地测试时开启无痕窗口。

---

自动清理脚本的核心设计思路

一个优秀的清理脚本应当满足：

• 安全：只清理 MkDocs 相关的缓存目录,不影响操作系统或其他项目。
• 可配置：支持指定项目路径、自定义缓存目录名。
• 跨平台：兼容 Windows 命令行、PowerShell、Linux/macOS Shell。
• 可回滚保护：在删除前确认项目存在,避免误删。
• 集成友好：能够被 npm scripts、Makefile、GitHub Actions 等调用。

核心逻辑（伪代码）：

def clean_mkdocs_cache(project_path):
    dirs_to_remove = ['site', '.cache', '__pycache__']
    for dir_name in dirs_to_remove:
        target = os.path.join(project_path, dir_name)
        if os.path.exists(target):
            shutil.rmtree(target)
            print(f"已清理: {target}")

---

实战：编写一键清理脚本

1 Bash 脚本（Linux/macOS）

#!/bin/bash
# clean_mkdocs_cache.sh
# 设置默认路径为当前目录
PROJECT_PATH="${1:-.}"
# 检查目录是否有效
if [ ! -d "$PROJECT_PATH" ]; then
    echo "错误：目录 '$PROJECT_PATH' 不存在。"
    exit 1
fi
# 要清理的目录列表
CACHE_DIRS=("site" ".cache" "__pycache__")
for dir in "${CACHE_DIRS[@]}"; do
    full_path="$PROJECT_PATH/$dir"
    if [ -d "$full_path" ]; then
        echo "正在清理: $full_path"
        rm -rf "$full_path"
    else
        echo "跳过（不存在）: $full_path"
    fi
done
echo "MkDocs 缓存清理完成！"

使用方法：

chmod +x clean_mkdocs_cache.sh
./clean_mkdocs_cache.sh
# 或指定路径
./clean_mkdocs_cache.sh /path/to/your/mkdocs/project

2 PowerShell 脚本（Windows）

# clean_mkdocs_cache.ps1
param(
    [string]$ProjectPath = (Get-Location).Path
)
if (-not (Test-Path $ProjectPath)) {
    Write-Error "目录 '$ProjectPath' 不存在。"
    exit 1
}
$cacheDirs = @("site", ".cache", "__pycache__")
foreach ($dir in $cacheDirs) {
    $fullPath = Join-Path $ProjectPath $dir
    if (Test-Path $fullPath) {
        Write-Host "正在清理: $fullPath"
        Remove-Item -Path $fullPath -Recurse -Force
    } else {
        Write-Host "跳过（不存在）: $fullPath"
    }
}
Write-Host "MkDocs 缓存清理完成！"

使用方法：

.\clean_mkdocs_cache.ps1
# 或指定目录
.\clean_mkdocs_cache.ps1 -ProjectPath "D:\docs"

3 Python 跨平台脚本（推荐）

如果你已安装 Python,可以创建一个通用版本：

#!/usr/bin/env python3
# clean_mkdocs_cache.py
import os, sys, shutil
def clean_cache(project_path='.'):
    """清理 MkDocs 缓存目录"""
    if not os.path.isdir(project_path):
        print(f"错误：'{project_path}' 不是有效目录。")
        sys.exit(1)
    dirs_to_clean = ['site', '.cache', '__pycache__']
    for d in dirs_to_clean:
        target = os.path.join(project_path, d)
        if os.path.isdir(target):
            shutil.rmtree(target)
            print(f"✅ 已清理: {target}")
        else:
            print(f"⏭ 跳过（不存在）: {target}")
if __name__ == '__main__':
    path = sys.argv[1] if len(sys.argv) > 1 else '.'
    clean_cache(path)

使用方法：

python clean_mkdocs_cache.py
python clean_mkdocs_cache.py /Users/你的用户名/你的项目

---

脚本集成到构建流程

1 添加到 mkdocs.yml 的钩子（高级用法）

MkDocs 支持 pre_build 钩子,可以在构建前自动清理：

# docs/hooks/clean_cache.py
import os, shutil
def on_pre_build(config):
    for dir_name in ['site', '.cache', '__pycache__']:
        path = os.path.join(config['docs_dir'], '..', dir_name)
        if os.path.isdir(path):
            shutil.rmtree(path)
            print(f"[Hook] 已清理缓存: {dir_name}")

然后在 mkdocs.yml 中启用：

hooks:
  - docs/hooks/clean_cache.py

2 集成到 GitHub Actions

# .github/workflows/deploy.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install mkdocs mkdocs-material
      - name: Clean cache before build
        run: |
          if [ -d "site" ]; then rm -rf site; fi
          if [ -d ".cache" ]; then rm -rf .cache; fi
      - name: Build site
        run: mkdocs build --strict
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

---

常见问答 FAQ

❓ Q1：清理缓会不会影响正在运行的 mkdocs serve？

A：是的，mkdocs serve 正在运行，清理 site/ 目录会导致服务崩溃或页面找不到。建议先停止服务，再执行清理。

❓ Q2：可以只清理 .cache 而不清理 site/ 吗？

A：可以，但推荐两者都清理。.cache 是导致元数据异常的主因，而 site/ 中的旧文件可能干扰最终预览，如果你只改了一篇文档且想保留其他页面不变，可以只清理 .cache 然后重新 mkdocs serve。

❓ Q3：如何自动化让脚本在每次运行 mkdocs serve 前执行？

A：有两种方法：

• 创建一个 shell 别名：alias mkdocs='clear_cache.sh && mkdocs'
• 使用上文的 on_pre_build 钩子（推荐）,它会在构建前自动触发。

❓ Q4：脚本误删了重要目录怎么办？

A：脚本只删除特定且已知的缓存目录，建议不要修改目录列表，可以先用 echo 命令测试路径是否正确,再执行删除。

❓ Q5：我的项目路径包含空格怎么办？

A：在 Bash 脚本中请使用双引号包裹变量，如 "$PROJECT_PATH"，PowerShell 和 Python 版本已自动处理。

❓ Q6：为什么清理后网站依然显示旧内容？

A：请检查：

1. 浏览器缓存（按 Ctrl+F5 强制刷新）。
2. 是否在清理后重新运行了 mkdocs build 或 mkdocs serve。
3. 配置文件 mkdocs.yml 是否存在语法错误导致未预期行为。
4. 某些插件（如 mkdocs-static-i18n）有独立缓存目录,需单独清理。

---

总结与建议

自动清理 MkDocs 缓存的脚本虽然简单，但能极大地提升开发效率，避免「为什么我的修改不生效？」的困惑,以下是几个最佳实践：

1. 养成习惯：每次提交代码前运行一次清理脚本,确保构建产物是干净的。
2. 与 CI/CD 绑定：在构建步骤前加入清理命令,避免远程构建环境缓存污染。
3. 版本控制：将清理脚本纳入 Git 仓库,方便团队成员使用。
4. 避免过度清理：如果项目使用了 mkdocs-monorepo-plugin 等外部挂载内容,清理时要注意不要删掉外部引用路径。

推荐方案：

• 小型项目或单次使用：直接用 Bash/PowerShell 脚本。
• 团队协作或高级场景：使用 Python 脚本 + MkDocs 钩子,体现实力且可维护。

希望这篇指南能帮助你彻底告别 MkDocs 缓存困扰，如果还有其他问题,欢迎在评论区留言讨论。