调试已编译的 Twig 模板

02/10/2025, by Ivan

Twig 通常的工作方式

默认情况下，Twig 主题引擎会将模板编译成 PHP 代码，并将编译后的代码缓存在内存中。编译后的代码并不适合开发，因为 Twig 模板的修改不会立即在 Drupal 网站中生效。

在 Twig 完成某些标记的渲染后，Render API 还会增加一层缓存。它会将 Twig 生成的标记缓存起来，使得后续页面请求中 Twig 根本不会参与渲染，因此 Twig 的调试参数最终会被忽略。

虽然可以通过 Drupal 的缓存清理界面清空缓存，但在开发时，更简单的方式是修改 Drupal 配置，使 Twig 和 Render API 完全不进行缓存。

配置 Twig 和 Render API 以进行调试

Twig 和 Render API 各自有独立的调试设置：

1. Twig 引擎提供了调试选项、自动重新加载（重新编译）模板、以及将编译模板缓存到文件系统的功能。这些可在站点的 services.yml 文件中配置。
2. Render API 的缓存可以在站点的 settings.php 文件中配置。

下面我们将详细介绍这两部分。

1. 配置 Twig 调试

你可以使用 Drupal Console 来开启调试；也可以手动修改。

使用 Drupal Console 启用调试

首先安装 Drupal Console，然后运行：

drupal site:mode dev

请注意，这会修改多个设置，其中包括在 sites/default/services.yml 中启用以下配置：

twig.config: { debug: true }

你应该会看到类似如下的结果：

output_3

手动启用调试

1. 找到站点的 services.yml 文件，通常位于 sites/default/services.yml
2. 如果 services.yml 不存在，可以复制 default.services.yml 并重命名为 services.yml
3. 编辑 services.yml 文件，启用以下调试选项之一或多个：
- Twig 调试选项
- Twig 自动重新加载
- Twig 缓存
4. 清理缓存。

在 services.yml 中找到 twig.config 参数并修改。例如：

parameters:
  twig.config:
    debug: true

Twig 调试选项

注意：不要在生产环境启用！ 以下三个参数仅在开发环境中使用。

- debug（默认：false）

当设置 debug: true 时：

每个 Twig 模板的输出会被 HTML 注释包裹，包含模板文件名建议等调试信息。
调试标记可能会导致自动化测试失败（因为测试依赖于渲染后的 HTML），因此在运行自动化测试时，应将 twig_debug 设为 FALSE。
可以在 Twig 模板中使用 dump() 输出变量信息。
修改模板代码后会自动重新编译（参见 auto_reload）。

- auto_reload（默认：null，依赖 debug 设置）

当设置 auto_reload: true 时：

每当 Twig 模板源代码被修改时，会自动重新编译。
如果未设置 twig_auto_reload，则它会根据 twig_debug 的值自动决定。

- cache（默认：true，但受 debug 设置影响）

当设置 cache: false 时：

通常不建议禁用 Twig 缓存。如果开启了调试（或 auto_reload），Twig 缓存不会阻碍开发。禁用缓存会导致开发更慢，因为每次模板都会被重新编译。
默认情况下，Twig 模板会被编译并缓存到文件系统（如 sites/default/files/php/twig），禁用缓存会阻止这个行为，导致无法轻松查看或调试编译后的 PHP 文件。

2. 配置 Render API 缓存以进行调试

Drupal 8 默认会对区块和实体的渲染结果进行缓存，以加快页面加载速度。这意味着 Twig 模板的修改不会立即生效。通过设置 Render API 使用空缓存，可以禁用该行为。

要禁用渲染缓存，可以添加以下配置：

在 settings.php 中（不要在生产环境启用）
或在 settings.local.php 中（需先在 settings.php 中取消注释相关配置）。

示例：

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

这些配置可能已经存在于你的 settings.php 文件中，只是被注释掉了；如果是这样，只需取消注释即可（记得之后再注释回去）。

完成！

在配置好 Twig 和 Render API 后，清空缓存：可以使用 Drush，或进入「配置 > 性能」页面点击「清空所有缓存」。

刷新页面后，你应该能在源代码中看到 Twig 调试信息，并且 Twig 模板的更新会立即在页面中生效。

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验