项目配置文件

概述

项目配置文件使您能够根据不同场景调整项目的选项、环境和内容。例如：

您可能希望在生产服务器上运行时具有不同的执行行为。例如，您可能希望在本地渲染时使用 freeze 或 cache，但在 CI 服务器上运行时始终执行所有代码。
您可能希望根据配置文件提供不同的数据库或 Web 服务访问凭证。
您可能希望从相同的源代码创建不同版本的书（例如，基本版和高级版）。

当激活项目配置文件时，会发生以下情况：

以下是一个 _quarto.yml 文件的示例，该文件由 _quarto-production.yml 中定义的 production 配置扩展。当激活时，production 配置文件会覆盖默认的渲染执行行为（禁用 freeze 的使用）：

_quarto.yml

project:
  type: website
  
execute: 
  freeze: true

_quarto-production.yml

execute:
  freeze: false

当 production 配置文件处于活动状态时，其配置将合并到默认项目配置中（在这种情况下，导致禁用冻结的计算结果）。

以下是使用 when-profile 属性仅在 advanced 配置文件处于活动状态时包含内容的示例：

::: {.content-visible when-profile="advanced"}
此内容仅在高级版本中显示。
:::

下一节介绍如何激活配置文件，然后后续部分将更深入地介绍配置文件的各种功能。

可以通过使用 QUARTO_PROFILE 环境变量或 --profile 命令行参数来激活一个或多个命名配置文件。

以下是使用 QUARTO_PROFILE 环境变量激活配置文件的示例：

Terminal

export QUARTO_PROFILE=production
quarto render

以下是通过在 Quarto 命令行上传递 --profile 参数来激活配置文件的示例：

Terminal

quarto render --profile production

使用 --profile 命令行参数完全替换环境中定义的任何 QUARTO_PROFILE。

请注意，可以同时激活多个配置文件。例如，以下示例同时激活 production 和 advanced 配置文件：

Terminal

quarto render --profile production,advanced

通过添加包含配置文件名称的附加项目文件来定义配置文件特定的配置（例如，advanced 配置文件的 _quarto-advanced.yml）。例如，以下示例根据当前活动的配置文件自定义 title 和 output-dir：

_quarto.yml

project:
  title: "My Website"
  type: website

_quarto-advanced.yml

project:
  title: "My Website (Advanced)"
  output-dir: _site-advanced

配置文件中不解析 metadata-files

不要在配置文件配置中使用 metadata-files，而是将元数据文件的内容直接复制到配置文件配置文件中。

需要注意的是，可以同时激活多个配置文件。因此，以下示例使您能够根据 advanced 和 production 配置文件的变化配置：

_quarto.yml

project:
  title: "My Website"
  type: website
  
execute:
  freeze: true

_quarto-advanced.yml

project:
  title: "My Website (Advanced)"
  output-dir: _site-advanced

_quarto-production.yml

execute:
  freeze: false

如果您同时指定 advanced 和 production 配置文件，则每个配置文件都将被应用：

Terminal

# 环境中的多个配置文件
export QUARTO_PROFILE=advanced,production
quarto render

# 命令行上的多个配置文件
quarto render --profile advanced,production

您还可以指定仅在特定配置文件处于活动状态时包含项目中的内容。您可以使用 .content-visible 类和 when-profile 属性来实现这一点。例如，以下示例定义了一个仅在 advanced 配置文件处于活动状态时包含的 div：

::: {.content-visible when-profile="advanced"}
此内容仅在高级版本中显示。
:::

你也可以使用 unless-profile 属性从给定的配置文件中排除内容。这里我们仅在配置文件不是 advanced 时包含内容：

::: {.content-visible unless-profile="advanced"}
此内容将在所有版本中显示，除了高级版本。
:::

使用 .content-hidden 重写上述内容可能更清晰：

::: {.content-hidden when-profile="advanced"}
此内容将在高级配置文件中隐藏
:::

通常情况下，一组配置文件名称形成一个互斥的组，并且你希望确保至少有一个配置文件始终处于活动状态。例如，这里我们为 basic 和 advanced 配置文件定义了不同的章节列表，并添加了一个 group 条目，表明它们形成一个组：

_quarto.yml

project:
  type: book
  
book:
  title: "我的书"
  author: "诺拉·琼斯"

profile:
  group: 
    - [basic, advanced]

_quarto-basic.yml

book:
  chapters:
    - intro.qmd
    - using.qmd
    - summary.qmd

_quarto-advanced.yml

book:
  chapters:
    - intro.qmd
    - using.qmd
    - advanced.qmd
    - summary.qmd

你会注意到，book 的基本选项不包括章节列表（因为我们依赖配置文件来提供不同的列表）。这意味着要成功渲染项目，你总是需要定义一个配置文件——这可能特别不方便，尤其是在本地创作和预览时。

通过指定一个 group，我们表明必须定义其中一个配置文件，并且当没有其他配置文件时，应使用列表中的第一个作为默认配置文件。

在创作使用配置文件的 Quarto 项目时，你可能希望更改默认渲染的配置文件，以尝试项目的不同变体。

虽然你当然可以通过在 shell 中定义环境变量来实现这一点，但在使用 VS Code 和 RStudio 中的集成渲染和预览功能时，这并不特别方便。

要定义一个默认配置文件，当没有显式的 QUARTO_PROFILE 或 --profile CLI 参数时使用，请在 profile 键中添加一个 default 选项。例如，这里我们指示如果未指定其他配置文件，则应使用 development 作为活动配置文件：

_quarto.yml

profile:
  default: development