最常见原因是标签类未被框架识别为taglib实例：未继承think emplate aglib、类名不以taglib结尾、未放在app aglib下、命名空间与路径不匹配，或$tags数组未正确定义对应标签键。
升级到 ThinkPHP 8 后，自定义标签库原样输出、不解析、报错或静默失效——基本可以确定是标签类未被识别或解析逻辑返回非法 PHP 代码，不是模板写法问题，也不是缓存没清。
为什么<xxx></xxx>在TP8里直接当文本输出？
最常见原因：框架根本没把你的类当 TagLib 实例加载。TP8 对自动加载和命名规范更严格，漏掉任一条件都会导致整个 XML 标签块透传。
- 类没继承
think emplateTagLib（必须显式extends，不能只写命名空间） - 类名不以
TagLib结尾（如Xyz不行，必须是XyzTagLib） - 文件没放在
app aglib目录下（TP8 默认只扫描该路径，appcommon aglib等自定义路径需手动注册） - 命名空间与目录结构不匹配（例如
app aglibXyzTagLib.php必须声明namespace app aglib;） -
$tags数组里没定义对应标签键（如写了<if></if>，但$tags里没有'if' => []）
parseXxx()方法返回什么才算合法？
它必须返回**可被 PHP eval() 执行的纯 PHP 代码字符串**，不是 HTML、不是 JSON、不能含未转义变量，否则编译阶段就崩。
- 闭合标签的
$content是子内容体，需原样拼入 PHP 输出逻辑中，例如：'<?php if ($condition): ?>' . $content . '<?php endif; ?>' - 所有变量插值必须手动加引号并转义：
'"'.addcslashes($tag['role'], '"\').'"'，否则生成的 PHP 会语法错误 - 非闭合标签（如
<break></break>）的$content恒为空字符串，别假设它有值 - 若需支持内层标签嵌套（比如自定义循环里再用
<volist></volist>），必须在$tags['xxx']中设'level' => 1，否则内层不会二次解析
TP8下如何注册非标准路径的标签库？
TP8 不再自动扫描 appcommon aglib 或 vendor 插件里的标签类，必须显式注册。靠改 config/template.php 的 taglib 配置项无效——那是 TP5/6 的写法。
- 在
app/bootstrap.php或服务提供者中，调用hinkTemplate::addTagLib('app aglibXyzTagLib'); - 如果标签类在 vendor 包里（如老插件迁移），先确认其
composer.json有正确psr-4映射，再用完整命名空间注册 - 注册后务必清空
runtimecache emplate，否则旧缓存仍走默认路径逻辑 - 别在 TagLib 构造函数里做 DB 查询或文件读取——实例是每次模板编译时 new 的，性能敏感
升级后标签突然不生效，但代码没动？
大概率是 runtime 缓存残留或配置未重载。TP8 的模板编译结果、标签注册状态、甚至 $tags 数组结构都缓存在 runtime/ 下，改完代码不清理等于白改。
- 执行
php think clear清除全部缓存（包括模板、配置、日志） - 检查
runtimelog是否有TagLib not found或Parse error in template类警告 - 临时在
parseXxx()开头加throw new Exception('parsed');，看是否进得去方法——进不去说明没注册或没识别；进得去但页面空白，说明返回的 PHP 代码有语法错误 - TP8.1+ 对
parseXxx()返回值做了更严格的校验，空字符串或仅含注释会被跳过，必须返回至少一条有效 PHP 语句
真正卡住人的从来不是怎么写 parse 方法，而是框架压根没调它——所以排查顺序永远是：路径/命名/注册 → $tags 声明 → parse 返回值合法性 → runtime 缓存。
