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）的解析行为，显著提升构建速度与稳定性。
