Blaze 折叠安全指南:如何正确使用 safe 与 unsafe 参数避坑
Blaze 折叠安全指南:如何正确使用 safe 与 unsafe 参数避坑
Blaze 是 Laravel 的 Blade 组件预编译优化库,能把匿名组件编译为优化后的 PHP 函数,将 25,000 个组件的渲染从 500ms 降到 13ms;而它的「编译期折叠(Compile-Time Folding)」策略更激进——组件在运行时彻底消失,只剩静态 HTML,渲染 10 万个组件也只需 0.68ms。但正是这种「烘焙式」优化,用错了会埋下难以排查的坑。本文通过一张避坑清单,带你掌握 @blaze 指令中 safe 与 unsafe 参数的正确用法。
⚡ 安装:
composer require livewire/blaze:^1.0📦 离线仓库:https://gitcode.com/gh_mirrors/blaze37/blaze
1️⃣ 先搞懂折叠:为什么它会"翻车"
启用折叠只需在组件顶部加一行:
@blaze(fold: true)
Blaze 会在编译期把组件渲染成静态 HTML 直接嵌入模板。这意味着组件内部的所有逻辑、条件、动态内容都在编译时被"定死"了。
💡 核心原则:凡是"每次请求都可能不同"的东西,折叠都必须小心。
| 场景 | 结果 |
|---|---|
| 属性、插槽全是静态值 | ✅ 安全,折叠后输出恒定 |
动态属性直接透传输出(如 :id="Str::random()") |
✅ 安全,Blaze 用占位符替换再还原 |
动态属性进入组件内部逻辑(match/if) |
❌ 危险,占位符字符串会参与判断导致逻辑错乱 |
一个典型翻车案例:给按钮组件传 :color="$deleting ? 'red' : 'blue'",组件内部用 match($color) 选样式。若被折叠,$color 在编译期拿到的是字面字符串 "BLAZE_PLACEHOLDER_1_",match 全部落空——按钮永远显示灰色。
好在 Blaze 默认采取防御策略:动态属性名与 @props 中的 prop 同名时,自动中止折叠,回退到普通的函数编译。但当默认行为太保守或太宽松时,就需要 safe / unsafe 出手了。
2️⃣ safe 与 unsafe 参数速查
这两个参数都写在 @blaze 指令中,接受数组:
@blaze(fold: true, safe: ['level'], unsafe: ['slot'])
safe —— 告诉 Blaze:这些 prop 是透传的(原样输出,不参与内部逻辑),即使传入动态值也允许继续折叠。
unsafe —— 告诉 Blaze:这些值不是透传(会被转换或用于逻辑判断),一旦动态就强制中止折叠。
| 取值 | 作用对象 |
|---|---|
* |
全部 props / attributes / slots |
slot |
默认插槽 |
[name] |
指定某个 prop / 属性 / 命名插槽 |
attributes |
所有未在 @props 中定义的属性 |
更详细的判定逻辑可参见 src/Folder/Folder.php 中的 isSafeToFold() 方法。
3️⃣ 什么时候用 safe?(太保守时放行)
判断标准:prop 的值是否被组件"直接输出",而非参与任何计算。
@blaze(fold: true, safe: ['level'])
@props(['level' => 1])
<h{{ $level }}>{{ $slot }}</h{{ $level }}>
{{-- 调用处传入动态值也能成功折叠 --}}
<x-heading :level="$isFeaturedSection ? 1 : 2" />
level 只是原样拼进标签名,没有任何内部逻辑依赖它,标记 safe 后折叠成功,产物形如:
<h{{ $isFeaturedSection ? 1 : 2 }}></h{{ $isFeaturedSection ? 1 : 2 }}>
⚠️ 反例:如果 match($level)、if($level === 1) 之类的逻辑存在于组件内部,绝不能标 safe——那样会重演上面"灰色按钮"的坑。
4️⃣ 什么时候用 unsafe?(太激进时拦截)
① 插槽参与内部逻辑 → unsafe: ['slot']
Blaze 默认把插槽视为透传。但如果你检查了插槽内容($slot->hasActualContent()、$slot->isEmpty()),占位符会让检查结果失真:
@blaze(fold: true, unsafe: ['slot'])
@if ($slot->hasActualContent())
<span>No results</span>
@else
<div>{{ $slot }}</div>
@endif
命名插槽同理:unsafe: ['footer']。注意:标记 unsafe 后,只要该次调用传了内容就一律中止折叠,但自闭合(无内容)的调用仍会正常折叠——Blaze 不会去分析插槽内容本身。
② 读取属性袋参与逻辑 → unsafe: ['attributes'] 或指定属性名
组件通过 $attributes->get('href') 把"非 prop 属性"用于逻辑判断时:
@blaze(fold: true, unsafe: ['href'])
@php
$active = $attributes->get('href') === url()->current();
@endphp
<a {{ $attributes->merge(['data-active' => $active]) }}>
{{ $slot }}
</a>
如果整个属性袋多处参与逻辑,直接标 unsafe: ['attributes'],任何动态属性出现都会中止折叠。
5️⃣ 避坑清单:折叠前的 6 道安检 🛡️
以下清单整理自仓库内置的检查参考 resources/boost/skills/blaze-optimize/references/folding-safety.md:
| # | 检查项 | 处理建议 |
|---|---|---|
| 1 | 组件内部是否访问全局状态?($errors、session()、auth()、request()、old()、@csrf、@once、@auth、now()、config()、Cache:: 等) |
❌ 禁止折叠,改用默认编译策略即可 |
| 2 | 是否嵌入了 Livewire 组件?(<livewire:*> / @livewire) |
❌ 禁止折叠 |
| 3 | 动态 prop 是否参与内部逻辑(match/if/switch)? |
❌ 保持默认即可自动中止折叠;确认透传才标 safe |
| 4 | 插槽/属性是否被组件逻辑消费? | ✅ 标 unsafe: ['slot']、unsafe: ['attributes'] |
| 5 | 只有局部需要动态能力? | ✅ 用 @unblaze 圈出该段,其余照常折叠 |
| 6 | 性能真的有问题吗?组件是否在频繁改动? | 没有实测瓶颈就别折叠——频繁改动还需每次 view:clear,徒增心智负担 |
💡 第 5 条示例(表单输入 + 错误提示):
@blaze(fold: true)
@props(['name', 'label'])
<div>
<label>{{ $label }}</label>
<input name="{{ $name }}">
@unblaze(scope: ['name' => $name])
@error($scope['name'])
{{ $message }}
@enderror
@endunblaze
</div>
@unblaze 区块内的内容不参与折叠,且作用域变量必须通过 scope 参数显式传入。
6️⃣ 调试建议:让问题无处遁形 🔍
- 开启严格模式:折叠出错时 Blaze 默认静默回退到函数编译(你甚至察觉不到)。在
AppServiceProvider中调用Blaze::throw(),可让折叠期间的异常直接抛出,配合 src/Exceptions/InvalidBlazeFoldUsageException.php 中清晰的错误信息(如 "Components using session() should not use @blaze fold...")快速定位。 - 开启调试面板:设置
BLAZE_DEBUG=true或调用Blaze::debug(),页面上会出现渲染耗时浮层和火焰图 Profiler,能直接看到每个组件实际采用的是 compiled、folded、memoized 还是 blade 策略。 - 改完模板记得清缓存:
php artisan view:clear,否则折叠产物不会更新。
总结 ✅
| 策略 | 一句话记忆 |
|---|---|
| 默认编译 | 万能、无副作用,大多数场景的首选 |
fold: true |
极致性能,但先过安检清单再放行 |
safe |
"它只是透传,放心折叠" |
unsafe |
"它会参与逻辑,动态时请折叠让路" |
把折叠当"特权"而非"默认":先确认组件不碰全局状态,再为每个动态值问一句"它是透传还是参与逻辑",safe 与 unsafe 自然水到渠成。🚀
📌 延伸阅读
- 折叠与参数完整文档:README.md
- 折叠判定与
safe/unsafe核心源码:src/Folder/Folder.php - 占位符替换与还原实现:src/Folder/Foldable.php
- 折叠安全检查清单(仓库内置):resources/boost/skills/blaze-optimize/references/folding-safety.md