Drupal 10 Bootstrap子主题无法覆盖links--contextual.html.twig模板

1. 检查子主题.info.yml配置 #

打开web/themes/custom/my_bootstrap_subtheme/my_bootstrap_subtheme.info.yml，确认以下配置正确：

name: My Bootstrap Subtheme
type: theme
description: Custom subtheme based on Bootstrap
core_version_requirement: ^10
base theme: bootstrap
libraries:
  - my_bootstrap_subtheme/global-styling
regions:
  header: Header
  primary_menu: 'Primary menu'
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer

确保没有错误的配置项干扰模板查找逻辑。

2. 修正模板文件路径层级 #

Bootstrap主题的links.html.twig位于themes/contrib/bootstrap/templates/system/，子主题需要保持相同的子目录结构——把links--contextual.html.twig放在web/themes/custom/my_bootstrap_subtheme/templates/system/下，而非templates根目录。Drupal模板查找会匹配路径层级，缺失子目录会导致无法识别。

3. 确认模板建议优先级 #

开启Twig调试后，查看页面源代码中的模板注释，示例如下：

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'links' -->
<!-- FILE NAME SUGGESTIONS:
 * links--contextual.html.twig
 * links.html.twig
-->
<!-- BEGIN OUTPUT from 'themes/contrib/bootstrap/templates/system/links.html.twig' -->

重点确认links--contextual.html.twig是否在建议列表最上方，以及实际输出路径是否指向你的子主题。如果没显示子主题模板，说明Drupal未找到该文件。

4. 彻底清除缓存 #

在Ddev容器内执行全缓存清除命令，比后台清除更彻底：

ddev exec drush cr

也可以手动删除Twig缓存文件：

ddev exec rm -rf web/sites/default/files/php/twig

5. 手动提升模板建议优先级 #

在my_bootstrap_subtheme.theme文件中添加以下代码，强制提升contextual链接模板的优先级：

/**
 * Implements hook_theme_suggestions_links_alter().
 */
function my_bootstrap_subtheme_theme_suggestions_links_alter(array &$suggestions, array $variables) {
  if (isset($variables['attributes']['class']) && in_array('contextual-links', $variables['attributes']['class'])) {
    array_unshift($suggestions, 'links__contextual');
  }
}

添加后执行缓存清除。

6. 修正文件权限（Ubuntu/Ddev环境） #

确保子主题文件权限符合Drupal要求：

ddev exec chown -R www-data:www-data web/themes/custom/my_bootstrap_subtheme
ddev exec chmod -R 755 web/themes/custom/my_bootstrap_subtheme
ddev exec chmod 644 web/themes/custom/my_bootstrap_subtheme/templates/system/links--contextual.html.twig

7. 测试基础覆盖有效性 #

先尝试直接覆盖links.html.twig（不带contextual后缀），将文件放在web/themes/custom/my_bootstrap_subtheme/templates/system/links.html.twig，修改内容后清除缓存。如果这个基础覆盖生效，说明是contextual后缀的匹配问题；如果仍不生效，回到第一步检查子主题配置。

内容的提问来源于stack exchange，提问作者jeeva