Twig过滤器需三要素齐备：模板语法正确、扩展已加载、参数类型匹配；缺一则|trans返回原键、|date报错、|truncate不识别，自定义过滤器还须打twig.extension标签并严格匹配名称与类型。
Twig过滤器不是“写了就能用”，关键在三件事：模板里写对语法、底层扩展已加载、参数和类型匹配。缺一环，|trans 返回原始键，|date 报错，|truncate 直接不识别。
常见过滤器怎么调用才不出错
基础语法是 {{ variable|filter_name }} 或带参数的 {{ variable|filter_name(arg1, arg2) }}，但很多坑藏在细节里：
-
|date要求输入是DateTime实例或 strtotime 兼容字符串；传null会输出当前时间（除非启用了strict_variables: true） -
|number_format第二个参数是小数位数，第三个才是千分位分隔符，写成{{ price|number_format(2, ',', '.') }}才对 -
|replace的键必须完全一致：写{'%name%': 'Alice'}，不能写成{'name': 'Alice'}或{'%NAME%': 'Alice'} -
|json_encode对资源（resource）、闭包（Closure）会直接失败，建议先用is_iterable或is_object判断
扩展过滤器（如 |data_uri、|html_to_markdown）为什么报“Unknown filter”
这类过滤器不属于 Twig 核心，必须手动安装并启用对应扩展：
- 运行
composer require twig/html-extra twig/extra-bundle才能用|data_uri - 运行
composer require twig/markdown-extra twig/extra-bundle才能用|html_to_markdown - 运行
composer require twig/intl-extra twig/extra-bundle才能用|format_date - 装完后必须确认
twig/extra-bundle已在config/bundles.php中启用（Symfony 默认会自动加，但手动删过就没了） - 验证是否生效：运行
php bin/console debug:twig --filter=data_uri，有输出才说明注册成功
自定义过滤器注册后模板仍不识别？检查这几点
自定义过滤器失效，90% 是容器注册环节断了：
- 服务声明中必须带
tags: [{ name: 'twig.extension' }]，漏掉这个标签，Symfony 就当它不存在 - 类路径要和
services.yaml里写的完全一致，比如App\Twig\TextExtension对应src/Twig/TextExtension.php - Twig ≥ 3.0 必须用
TwigFilter类包装，不能再用旧版Twig_SimpleFilter - 调试命令要跑两遍：
php bin/console debug:container --tag=twig.extension看类是否列出来；php bin/console debug:twig搜索你的过滤器名是否在列表里 - 模板里拼写必须和
new TwigFilter('my_filter', ...)第一个参数严格一致，大小写、下划线都不能错
最常被忽略的是：扩展类里没处理空值或非预期类型——比如 truncateText() 方法声明接收 string，但模板传了 null，PHP 8+ 会直接报 TypeError，而不是静默返回空字符串。
