必须在服务提供者boot()方法中调用blade::directive()注册，传入指令名（如'role'）和返回合法php字符串的闭包，闭包内不可调用auth()等facade，修改后须执行php artisan view:clear。
Blade 指令不是 Artisan 命令，不能用 php artisan make:command 生成——这是最常见的混淆点。Laravel 不提供“自定义 Blade 指令”的官方命令行工具，所有 Blade 扩展必须手动注册、硬编码在服务提供者中。
怎么注册一个自定义 Blade 指令
Blade 指令注册发生在服务启动阶段，必须在 AppServiceProvider::boot() 或独立服务提供者里调用 Blade::directive()。它不走命令行，也不生成文件，纯 PHP 函数调用。
- 确保已引入
use IlluminateSupportFacadesBlade; - 指令名只能是字母+下划线（
my_if✅，my-if❌），不能含冒号或空格 - 回调函数接收原始表达式字符串（如
$user->is_active），**不自动解析为 PHP 值**，需手动包裹<?php echo ... ?>或<?php if (...) { ... } ?> - 返回值必须是合法 PHP 代码字符串，末尾不加分号（
Blade会自动补）
示例：注册 @role('admin')
Blade::directive('role', function ($expression) {
return "<?php if (auth()->check() && auth()->user()->hasRole{$expression}): ?>";
});
为什么 @mydirective 在模板里不生效
常见原因就三个：缓存未清、注册时机错、表达式拼接出错。
- Blade 编译后缓存位于
storage/framework/views/，改完指令必须删缓存：rm -rf storage/framework/views/*或php artisan view:clear - 指令必须在
boot()中注册，写在register()里无效（容器尚未完全启动） - 返回的字符串若漏掉
<?php或多写了分号，会导致编译失败，错误通常静默吞掉，只渲染空白——建议先用dd()打印返回值确认结构 - 别在指令里直接调用
$this->...或依赖请求上下文（如request()），Blade 编译时无 request 实例
带参数和嵌套逻辑的指令怎么写安全
Blade 指令本质是字符串替换，不经过 PHP 解析器校验。复杂逻辑容易因引号、括号配对失败导致编译崩溃。
- 避免在指令中拼接 HTML 属性值（如
"class="{$class}""），优先用原生@props+ 组件替代 - 需要多行逻辑？改用
Blade::if()（Laravel 9.20+）注册条件宏，比directive()更安全：Blade::if('env', function ($environment) { return app()->environment($environment); });→ 可用@env('local') - 想支持闭合标签（如
@markdown ... @endmarkdown）？必须用Blade::component()+<x-markdown>...</x-markdown>，directive()无法处理成对标签 - 表达式含单引号时，用
str_replace("'", "\'", $expression)转义，否则生成的 PHP 会语法报错
最易被忽略的是：Blade 指令注册代码本身不会被热更新监听，改完 AppServiceProvider 后必须清 view 缓存，且不能依赖 php artisan serve 的自动重载——它只监视路由、配置、视图文件，不监视服务提供者代码变更。
