Blade 指令注册必须在服务提供者 boot 方法中，因 Blade 编译器仅在 boot 阶段初始化；指令名需唯一、禁用连字符，回调须返回合法 PHP 字符串，$expression 是原始字符串，安全起见应白名单校验。
Blade 指令注册必须在服务提供者 boot 方法里
Blade 编译器实例只在 boot() 阶段可安全操作，register() 里调用 BladeCompiler::directive() 会报错或无效。Laravel 启动流程中，Blade 编译器在 boot() 时才完成初始化并绑定到容器。
实操建议：
- 新建服务提供者（如
App\Providers\BladeServiceProvider），运行php artisan make:provider BladeServiceProvider - 在
boot()中获取编译器：$this->app['blade.compiler']或resolve('blade.compiler') - 每个自定义指令需唯一名称，不能与内置指令（如
@if、@foreach）重名，否则覆盖后原有行为丢失 - 指令名不支持连字符（
-），推荐用驼峰或下划线，如@jsonScript可行，@json-script会解析失败
@directive 回调函数返回的是 PHP 代码字符串
Blade 不执行你写的逻辑，只是把指令“翻译”成等效的 PHP 代码，再交给 PHP 解析器执行。所以回调里不能直接 echo 或 return 值，而要拼出合法、可执行的 PHP 字符串。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
- 写
return json_encode($expression);→ 模板里直接输出 JSON 字符串，而非执行逻辑 - 漏掉分号或括号，导致编译后 PHP 语法错误，报
ParseError: syntax error - 未转义双引号或变量插值，比如
"echo $value;"中$value被提前解析，应写成'echo ' . $value . ';'或用<?php echo {$expression}; ?>形式
正确示例（定义 @jsonScript 输出内联 JSON）：
$compiler->directive('jsonScript', function ($expression) {
return "<?php echo '<script>window.__DATA__ = ' . json_encode({$expression}, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . ';<\/script>'; ?>";
});
复杂指令建议用 @include + 组件替代 @directive
当逻辑涉及 HTML 结构、多行输出、条件嵌套或需要复用样式/JS 时，硬塞进 directive() 回调会让代码难以维护，且无法享受 Blade 组件的 slot、props、生命周期等能力。
使用场景对比：
- 纯逻辑转换（如日期格式化、URL 签名）→ 适合
@directive - 带 DOM 结构的 UI 片段（如卡片、表单组、加载骨架）→ 应该用
@include('components.card')或<x-card :title="$title"></x-card> - 需要 JS 初始化或响应 props 变化的交互组件 → 必须走组件，
@directive无法传入作用域变量或监听事件
性能影响：指令是编译期替换，无运行时开销；但过度使用会导致缓存文件体积增大、调试困难——Blade 缓存文件里全是拼接的 PHP，不像组件有清晰边界。
指令中的 $expression 是原始字符串，不是已解析变量
BladeCompiler::directive() 回调接收的参数是用户在模板中写的原始内容，比如 @jsonScript $user 传入的是字符串 "$user"，不是 $user 的值。它不会自动求值，也不会帮你做变量存在性检查。
容易踩的坑：
- 直接拼接进
json_encode($expression)→ 实际编码的是字面量"$user"，不是变量值 - 想支持多种写法（如
@jsonScript ['id' => 1]或@jsonScript $data）→ 需手动判断字符串是否以$开头，或用正则提取，不能依赖 PHP 自动解析 - 未过滤用户输入就拼进 PHP 字符串 → 存在远程代码执行（RCE）风险，例如
@jsonScript {!! $malicious !!}若未校验，可能注入任意 PHP 代码
安全建议：对 $expression 做白名单校验（如仅允许变量名、数组访问、点号链），或改用组件传参方式，由 Laravel 自动处理数据绑定和转义。
真正麻烦的从来不是怎么写指令，而是怎么让别人（包括一个月后的你自己）看懂那段被编译进 cache 文件里的 PHP 字符串 —— 它既不能断点调试，也不能 IDE 跳转，还混着 HTML 和 PHP。能用组件的地方，别省那两行 @。
