Drupal段落专属预处理函数未调用问题求助

• 严格核对命名规则
  必须遵循[主题/模块机器名]_preprocess_paragraph__[段落类型机器名]格式，重点注意是双下划线连接段落类型，不能写成单下划线。同时确认主题机器名和info.yml里的完全一致，Drupal对机器名的大小写、拼写敏感，比如my_theme不能写成mytheme或MyTheme。

• 检查文件位置与注册
  预处理函数必须放在主题的.theme文件（如my_theme.theme）或自定义模块的.module文件中，Drupal 8+已弃用template.php，别放错文件。如果拆分到单独的.inc文件，必须在主题info.yml里通过files字段注册：

  files:
    - my_theme.paragraph_preprocessors.inc
  

  注册后执行drush cr让Drupal加载该文件。

• 验证段落机器名准确性
  进入后台「结构 > 段落类型」，编辑目标段落，查看URL中的机器名（如/admin/structure/paragraphs_type/cta里的cta），不要把段落的显示名称当成机器名。也可以在通用预处理函数里打印实际bundle值确认：

  function my_theme_preprocess_paragraph(&$variables) {
    kint($variables['paragraph']->bundle());
  }
  

• 确保缓存彻底清除
  除了drush cr，可以手动删除sites/default/files/php和sites/default/files/css目录下的缓存文件，避免因权限问题导致drush缓存清除不彻底。执行drush cr -y强制清除，同时检查drush输出是否有报错。

• 检查函数参数与写法
  函数必须以引用方式接收&$variables参数，不能省略&，且不能有返回值：

  function my_theme_preprocess_paragraph__cta(&$variables) {
    // 预处理逻辑示例
    $variables['custom_text'] = 'CTA专属内容';
  }
  

  错误的参数传递或多余的返回值会导致Drupal无法识别该预处理函数。

• 排查覆盖与优先级问题
  如果是子主题，确认父主题没有同名函数覆盖逻辑；也可以通过通用预处理函数查看已注册的同类型函数，排查是否被其他模块/主题覆盖：

  function my_theme_preprocess_paragraph(&$variables) {
    $bundle = $variables['paragraph']->bundle();
    $registered_hooks = \Drupal::moduleHandler()->getImplementations("preprocess_paragraph__$bundle");
    kint($registered_hooks);
  }
  

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