自定义标签原样输出最常见原因是未继承think\template\TagLib类、类名未以TagLib结尾或未置于app\taglib目录下，导致框架无法识别为有效TagLib实例；其次$tags数组未正确定义对应标签键名（须全小写），或parseXxx方法未返回合法PHP代码片段。
ThinkPHP 的模板标签解析不是“写完就能用”，语法兼容性取决于三件事：标签库是否被识别、XML 标签是否在 $tags 中声明、解析方法返回的是否是合法 PHP 代码片段。
为什么自定义标签在模板里原样输出？
最常见原因是标签类没被框架识别为有效 TagLib 实例。不继承 think\template\TagLib，或类名没以 TagLib 结尾（如 TagLibXyz），或没放在默认路径 app\taglib\ 下，都会导致整个 XML 标签块被当作文本透传——连报错都不会抛。
另一个高频原因：你在模板写了 <if condition="xxx"></if>，但 $tags 数组里漏了 'if' => [...] 这一项，或者 key 写成 'If' 或 'IF'。属性名必须全小写，大小写敏感。
-
$tags是硬性开关，没定义 = 不进解析流程 - 构造函数里别做 DB 查询或文件读取，TagLib 实例是每次模板编译时临时 new 的，性能敏感
- 如果用的是 ThinkPHP 6+，注意命名空间要严格匹配目录结构，比如
app\taglib\Xyz.php对应namespace app\taglib;
如何让 <xxx></xxx> 标签正确转成 PHP 逻辑？
parseXxx() 方法不能返回 HTML 字符串，它必须返回能被 PHP eval() 执行的代码片段。例如 <auth role="admin">管理入口</auth>，对应方法应拼出类似：
立即学习“PHP免费学习笔记（深入）”；
<?php
public function parseAuth($tag, $content)
{
$role = $tag['role'] ?? 'user';
return '<?php if (session("user.role") === "' . $role . '"): ?>' . $content . '<?php endif; ?>';
}
?>
关键点：
- 所有变量插值必须手动加引号并转义，否则生成的 PHP 会语法错误
-
$content是子内容体，闭合标签才存在；非闭合标签（如<break></break>）的$content为空字符串 - 若需嵌套解析（比如自定义循环里再用
<volist></volist>），得在$tags中设'level' => 1，否则内层标签不会被二次处理
预加载 vs 内置 vs 手动导入：哪种方式更稳？
三种注册方式本质是加载时机和作用域不同，没有绝对优劣，但容易踩坑：
-
'taglib_pre_load' => 'app\taglib\MyTag'：启动即加载，模板里直接用<xxx></xxx>，无需<taglib name="my"></taglib>。适合项目级通用标签，但多个预加载类之间若$tags键冲突（比如都定义了'if'），后加载的会覆盖前一个 -
'TAGLIB_BUILD_IN' => 'cx,html,my'：把你的类加入内置列表，效果同预加载，但风险更高——一旦和其他扩展同名（如别人也叫MyTag），就可能静默覆盖 - 模板内写
<taglib name="my"></taglib>：最轻量，按需加载，适合模块级临时扩展。但每个要用该标签的模板都得加这行，漏了就失效
建议新项目统一走 taglib_pre_load，并确保类名唯一、$tags 键前缀化（如全用 'my_if' 而非 'if'）。
ThinkPHP 6 和 5.x 在标签解析上有什么关键差异？
核心逻辑一致，但路径和命名空间约定变了：
- TP6 默认标签库路径是
app\view\taglib\（非 TP5 的app\taglib\），配置项也从APP_PATH.'taglib/'改为可配置的view.taglib_path - TP6 中
TagLib基类在think\template\TagLib（首字母大写），而 TP5 是think\template\taglib（全小写），继承错就彻底失效 - TP6 模板缓存机制更激进，默认把解析结果编译成 PHP 文件存进
runtime/view/，改了parseXxx()一定要清空该目录，否则旧代码还在执行
跨版本迁移时，最容易忽略的是缓存残留和命名空间大小写——这两处一错，标签就“看起来写了，但没反应”。
