需用 Blade::directive 分别注册 @role 和 @endrole，闭包返回合法 PHP 片段（不加';'），运行时逻辑须写入返回字符串，不可在闭包中调用 auth() 等 Facade；修改后须执行 php artisan view:clear。
如何注册自定义 Blade 指令（Blade::directive）
直接在服务提供者（如 AppServiceProvider）的 boot 方法里调用 Blade::directive，传入指令名和返回 PHP 字符串的闭包即可。Laravel 不会自动解析或校验你返回的内容，它只是原样插入到编译后的 PHP 模板里。
常见错误是闭包里直接 echo 或写 HTML 字符串——这会导致运行时报错，因为 Blade 编译后生成的是 PHP 代码，不是执行环境。
- 指令名不加
@，比如注册@role就传'role' - 闭包参数是
$expression，即括号里的内容（不含括号），例如@role('admin')中的'admin' - 必须返回合法 PHP 表达式或语句片段，结尾不加分号（Blade 会自动补）
- 如果要输出 HTML，得返回
echo语句，比如return "echo 'hello';";
Blade::directive('role', function ($expression) {
return "<?php if (auth()->check() && auth()->user()->hasRole{$expression}): ?>";
});
为什么 @endrole 必须手动配对且不能用 Blade::if
Blade::if 只能定义单标签指令（如 @env），不支持开闭配对。而像 @role / @endrole 这类结构，本质是「自定义区块指令」，需要两个独立的 Blade::directive 注册，并靠 Blade 编译器内部的栈机制匹配起始/结束位置。
容易踩的坑是：只注册了 @role 却忘了 @endrole，或两者返回的 PHP 片段语法不对应（比如一个用 if 开头，另一个没用 endif 结尾），导致编译出错或逻辑断裂。
-
@endrole的闭包不需要参数，直接返回return '<?php endif; ?>'; - 不能用
Blade::if替代，否则@endrole会被忽略，模板直接报错 - 多个嵌套时，Blade 靠缩进无关的 token 匹配，所以起始/结束指令名必须严格一致（大小写敏感）
自定义指令中访问用户、请求等上下文数据的限制
指令闭包运行在模板编译阶段，不是执行阶段——此时 auth()、request() 等 Facade 还没初始化，也不能直接调用。所有运行时逻辑必须包裹在返回的 PHP 字符串里，延迟到视图真正渲染时执行。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
典型错误是闭包里直接写 auth()->user()->id，这会在编译时报 Call to a member function user() on null。
- 所有依赖运行时的数据，都得写进返回字符串中，比如
"<?php if (auth()->check() && auth()->user()->is_active): ?>" - 避免在闭包里做 DB 查询、API 调用——它们不会被执行，而且会污染编译缓存
- 想复用逻辑？把判断抽成辅助函数（如
function userCan($ability) { ... }），然后在返回字符串里调用
性能与缓存影响：指令内容被硬编码进编译文件
Blade 把每个自定义指令的返回值原样塞进缓存的 PHP 模板文件（路径类似 storage/framework/views/xxx.php）。这意味着：指令里写的任何 PHP 代码都会随模板一起被 OPCache 加载，无法热更新；一旦改了指令逻辑，必须清空 storage/framework/views 才生效。
更隐蔽的问题是：如果指令返回了带闭包或匿名类的代码，可能触发 PHP 序列化失败或作用域异常。
- 上线前务必清空视图缓存：
php artisan view:clear - 避免在指令中拼接大量动态 PHP 代码，可读性和调试成本陡增
- 复杂逻辑优先考虑组件（
<x-foo></x-foo>）或普通 PHP 函数，而非塞进指令
最麻烦的其实是调试——报错行号指向编译后的 .php 文件，而不是你写的指令注册处。得打开 storage/framework/views 对应文件，逆向定位原始逻辑。
