Jupyter Book 默认会递归遍历项目目录下所有文件，包括虚拟环境（如 uv 生成的 .venv），导致构建缓慢甚至失败；正确做法是将 exclude_patterns 置于 _config.yml 顶层，而非 execute 下，即可高效排除指定路径。

jupyter book 默认会递归遍历项目目录下所有文件，包括虚拟环境（如 `uv` 生成的 `.venv`），导致构建缓慢甚至失败；正确做法是将 `exclude_patterns` 置于 `_config.yml` 顶层，而非 `execute` 下，即可高效排除指定路径。

Jupyter Book 的 exclude_patterns 配置项用于全局忽略特定路径或文件模式，必须定义在 _config.yml 文件的根层级（top-level），而非嵌套在 execute、sphinx 或其他子配置下。若错误地将其放在 execute: 下（如原问题中所示），Jupyter Book 将完全忽略该设置，导致 .venv/ 目录仍被扫描。

✅ 正确配置方式如下（保存为项目根目录下的 _config.yml）：

# _config.yml
exclude_patterns:
  - ".venv"
  - "_build"
  - "Thumbs.db"
  # 可添加其他需排除的路径，支持 glob 模式（如 "**/__pycache__"）

⚠️ 注意事项：

• 路径匹配基于 相对于项目根目录 的路径，.venv 表示根目录下的 .venv/ 文件夹；
• 不需要末尾斜杠（.venv/ 与 .venv 效果一致），但推荐使用 .venv 保持简洁；
• exclude_patterns 不支持 ** 通配符递归排除子目录（如 .venv/** 并非必需，.venv 已隐含排除其全部内容）；
• 修改后务必重新运行 jupyter-book build . —— 无需清理缓存，Jupyter Book 会在构建前自动跳过匹配路径。

? 补充建议：
为提升可维护性，可一并排除常见干扰项：

exclude_patterns:
  - ".venv"
  - "_build"
  - ".ipynb_checkpoints"
  - "**/__pycache__"
  - "**/*.pyc"

该配置适用于所有 Jupyter Book 版本（≥0.13），且兼容 uv、venv、conda 等各类环境管理工具生成的隔离目录。正确设置后，构建日志中将不再出现对 .venv/ 内部文件（如第三方包中的 .md 或 .ipynb）的解析行为，显著提升构建速度与稳定性。