Blaze 折叠安全指南:如何正确使用 safe 与 unsafe 参数避坑

原创2026-10-28 15:29:232,171 阅读

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 自然水到渠成。🚀

📌 延伸阅读

登录后查看全文
blaze