管理执行

概述

渲染输入文件列表可能会非常耗时，具体取决于所需的计算量。有一些技术可以帮助你最小化重建一个包含昂贵计算的站点所需的时间。

在处理项目时，你通常一次只迭代一个文档。你可以通过在命令行中指定它来增量渲染单个文件（或单个目录或文件列表）：

终端

quarto render introduction.qmd
quarto render subdir/

尽管你只渲染了项目的一部分，但任何相关的项目处理代码仍然会执行。例如，在书籍项目中，整本书仍然会生成（使用其他章节的先前渲染版本）。

你可以使用 freeze 选项来表示在全局项目渲染期间，计算文档不应重新渲染，或者仅在源文件更改时重新渲染：

execute:
  freeze: true  # 在项目渲染期间永不重新渲染

execute:
  freeze: auto  # 仅在源文件更改时重新渲染

请注意，freeze 控制的是在全局项目渲染期间是否执行。如果你对单个文档或项目子目录进行增量渲染，那么代码总是会被执行。例如：

Terminal

# 渲染单个文档（总是执行代码）
quarto render document.qmd

# 渲染项目子目录（总是执行代码）
quarto render articles

冻结通常在你有大量合作者或许多在较长时间内创建的计算文档时使用。在这两种情况下，当你渲染站点时，完全重新执行每个文档都可能具有挑战性。这可能是因为某些文档有晦涩或特定于环境的要求（例如，需要访问/认证数据源），或者由于依赖项随时间的脆弱性。使用冻结可以确保你始终能够可重复地渲染你的站点。

使用 freeze 执行的文档的计算结果存储在 _freeze 目录中，并在需要时重新使用以完成文档渲染。你应该将 _freeze 的内容提交到版本控制中，以便其他渲染项目的人不需要重新生成你的计算环境即可在他们的环境中渲染。

请注意，当源代码之外的内容发生变化时（例如输入数据），你仍然希望完全重新渲染你的项目。你可以通过删除项目根目录下的 _freeze 文件夹来删除先前冻结的输出。

你还可以将 freeze 与虚拟环境的使用结合起来，将你的项目分成每个都有自己的依赖项的子目录。这允许多个合作者使用一组本地化的依赖项来处理他们负责的文档，但同时仍然能够在不需要所有依赖项的情况下渲染整个项目。

要了解如何创建和使用虚拟环境，请参阅关于虚拟环境的完整文档

以下是使用虚拟环境与冻结的示例工作流程：

在此子目录中工作时，在渲染其文档之前激活虚拟环境。例如：

终端

cd research
source env/bin/activate
quarto render               # 渲染子目录中的所有文件
quarto render document1.qmd  # 渲染单个文件

此子目录渲染不会使用缓存的 freeze 结果，而是将使用目录特定的虚拟环境重新运行所有计算。当然，你也可以在此目录中包含子目录，它们的文档也将使用父虚拟环境进行渲染。

你可以使用 cache 选项来缓存计算结果（使用 knitr 缓存用于 R 文档，以及 Jupyter 缓存用于 Jupyter 文档）：

execute:
  cache: true

请注意，缓存失效是由代码块源代码（或你定义的其他缓存属性）的变化触发的。然而，如果你知道某些其他输入（甚至时间）已经发生了足够的变化，需要更新，你可能需要手动刷新缓存。为此，使用 --cache-refresh 选项渲染单个文件或整个项目：

终端

quarto render mydoc.qmd --cache-refresh # 单个文档
quarto render --cache-refresh           # 整个项目

请注意，当渲染一个 .ipynb 文件时，Quarto 默认不会 执行笔记本中的单元格（假设你在编辑笔记本时已经执行过这些单元格）。如果你想执行这些单元格，可以在渲染时传递 --execute 标志：

Terminal

quarto render notebook.ipynb --execute

你也可以在笔记本的 YAML 前文中指定这种行为：

---
title: "My Notebook"
execute: 
  enabled: true
---

默认情况下，项目中渲染文件的工作目录是文件本身的目录。如果你更喜欢使用主项目目录，可以在配置中添加 execute-dir: project 选项：

project:
  execute-dir: project

请注意，在你的代码中，你始终可以使用 QUARTO_PROJECT_DIR 环境变量确定当前执行的 Quarto 项目的位置。