插件系统先想明白一件事
Drupal 的插件系统干的事情不复杂:按约定发现类、读注解、实例化、交给业务代码调用。区块、字段、视图、图片效果本质都是这一套。
真正要动手前建议先回答三个问题:插件靠什么被发现(注解还是 attributes)、需要哪些依赖、插件定义要不要缓存。这三个问题想清楚了,后面代码基本不会返工。
版本之间这块机制没有根本变化。Drupal 9 到 10、10 到 11 的插件升级问题,九成不在"插件"概念本身,而在旧注解、废弃 API 和主题钩子的清理上。
自定义插件:一个内容处理器的完整链路
目录大致这样放:
custom_module/
├── custom_module.services.yml
├── src/
│ ├── Annotation/CustomContentProcessor.php
│ ├── Plugin/
│ │ ├── CustomContentProcessorBase.php
│ │ ├── CustomContentProcessorInterface.php
│ │ ├── CustomContentProcessorManager.php
│ │ └── ProductSpecProcessor.phpcustom_module.services.yml 里注册管理器。注意 class 必须真实存在并继承 DefaultPluginManager,而且不要出现把 plugin.manager.custom_content_processor 自身作为 arguments 注入的写法,那是循环依赖:
services:
plugin.manager.custom_content_processor:
class: Drupal\custom_module\Plugin\CustomContentProcessorManager
parent: default_plugin_manager管理器构造函数要和父类签名对齐(Drupal 11 额外支持 attribute 声明,这里按 9/10/11 通用写法):
<?php
namespace Drupal\custom_module\Plugin;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;
final class CustomContentProcessorManager extends DefaultPluginManager {
public function __construct(
\Traversable $namespaces,
CacheBackendInterface $cache_backend,
ModuleHandlerInterface $module_handler,
) {
parent::__construct(
'Plugin/CustomContentProcessor',
$namespaces,
$module_handler,
CustomContentProcessorInterface::class,
'Drupal\custom_module\Annotation\CustomContentProcessor'
);
$this->alterInfo('custom_content_processor_info');
$this->setCacheBackend($cache_backend, 'custom_content_processor_plugins');
}
}具体插件用注解标识:
/**
* @CustomContentProcessor(
* id = "product_spec",
* label = @Translation("产品规格处理器")
* )
*/
class ProductSpecProcessor extends CustomContentProcessorBase {
// 实现接口里的 processContent()。
}这套链路里我踩过的坑基本就这几个,列出来是因为每一条都真实浪费过时间:
- 注解类
Annotation\CustomContentProcessor没写,插件发现直接为空; - 命名空间、目录、注解类名三者有一处对不上,也是静默失败;
- 改了注解之后忘了
drush cr,以为代码没生效; - 管理器构造函数参数和
default_plugin_manager的约定不一致,服务编译期就报错; - 插件类忘了实现接口方法,直到调用时才炸。
关于注解和 attributes:Drupal 11 里 attributes 更常见了,但 9/10/11 并存的项目里,先跟团队规范走,别为了追新把整套注解硬换一遍,升级成本通常大于收益。
性能问题多半不是插件机制的锅
插件本身不慢,写法会慢。几条经验:
构造函数只注入真正用到的服务。图省事把 entity_type.manager、database、cache 一股脑塞进去,后续重构时会很痛苦。
请求内重复计算可以用 static 缓存,但记住它只在当前请求有效,别指望它当持久缓存用。
查实体用 entityQuery,一次把 ID 查回来再批量 load。在循环里逐个 load() 就是教科书式的 N+1。
缓存一定要带 cache tags 和 cache contexts。只设 max-age 不设 tags,内容更新了页面不失效,这种 bug 在线上很难排查。
最后是加载时机。能用路由、Block visibility 或 lazy builder 控制的就别全局跑,尤其是别塞回 hook_init 时代的那种全局执行思路。
和主题集成
注册模板:
function custom_module_theme($existing, $type, $theme, $path) {
return [
'custom_content_processor' => [
'variables' => [
'content' => NULL,
'processor' => NULL,
'attributes' => [],
],
'template' => 'custom-content-processor',
],
];
}'base hook' => 'block' 不是必写项,只有你确实要继承 block 的模板和变量时才加。模板文件放 templates/custom-content-processor.html.twig。
预处理函数里把 attributes 包成 Attribute 对象,顺便补分类、样式类这些变量:
function custom_module_preprocess_custom_content_processor(&$variables) {
$variables['attributes'] = new \Drupal\Core\Template\Attribute($variables['attributes'] ?? []);
}多语言这块别只停留在"注意兼容"。Twig 里用 |t,CSS 尽量写 logical properties,再真开一次 RTL 语言看看布局,很多问题是测出来的不是想出来的。
版本升级:别先写 \Drupal::VERSION 分支
9 到 10 主要是清 deprecated API、升依赖、CKEditor 5 和主题层变化;10 到 11 是 PHP 要求提高、attributes 支持更完善、依赖注入和缓存继续优化。
升级时靠谱的顺序是:
- 跑 Upgrade Status,先把硬伤列出来;
- 开 deprecation 日志,把运行期触发的旧调用抓干净;
- 机械替换交给 Rector,别手工一条条改;
- CI 里挂多版本矩阵,别只在自己机器上测;
- 能用稳定 API 解决的,就不要写
\Drupal::VERSION条件分支——分支越多,下一个大版本越难升。
一套代码同时兼容 9/10/11 是有代价的。更现实的策略是:核心逻辑保持兼容,主题和少数服务按版本拆文件。
一个具体例子:产品规格展示
需求很常见:产品节点展示规格参数和相关推荐,要响应式、要多语言。
我的做法:规格整理交给 ProductSpecProcessor 插件,输出 render array;模板用上面注册的 custom_content_processor;相关推荐用 entityQuery 一次查完再批量 load;缓存打节点和产品分类的 tags;测试分两层,Kernel test 测插件发现,Functional test 测页面渲染,性能只看一个指标——每页查询数有没有降下来。
真实项目里最容易出问题的不是插件写不出来,而是插件发现失败、缓存该失效没失效、主题被覆盖后变量对不上、升级时某个 deprecated 调用漏网。把这几类问题提前列进 checklist,比事后排查省时间得多。

