Coolify 中的 Blade 视图最佳实践：组件属性合并、Fragment 局部渲染与视图数据组织

本文围绕 Coolify 仓库内置的 Laravel 最佳实践规则文档 rules/blade-views.md 展开，系统讲解 Blade 组件属性合并（$attributes->merge()）、@pushOnce 脚本去重、组件与 @include 的取舍、View Composer 集中供给视图数据、Blade Fragment 局部重渲染（htmx/Turbo 场景）以及 @aware 深层组件属性透传这六条核心规范。读完本文，你将掌握在 Coolify 这类大型 Laravel 12 项目中组织 Blade 视图的正确方式，并能在仓库源码中找到每条规则的真实落地证据。

一、规则出处与适用前提

blade-views.md 位于 .agents/skills/laravel-best-practices/rules/ 目录，是 Coolify 仓库为 AI 编码助手与开发者维护的一套 Laravel 最佳实践技能包（laravel-best-practices）中的第 18 节「Blade & Views」规则文件。配套的 SKILL.md 明确了其使用方式：

1. Consistency First（一致性优先）：应用任何规则之前，先检查应用已有代码做了什么。Laravel 提供多种有效方案——最佳选择是代码库已经采用的那种，即使另一种模式理论上更好。不一致比次优模式更糟糕；
2. 规则是「尚无既有模式时」的默认值，而非对既有模式的覆盖；
3. 应用时需识别文件类型，选择相关章节，并优先跟随兄弟文件中已确立的模式。

当前仓库的技术栈为 PHP 8.4 + Laravel 12.65（见 composer.json），因此本文所有 API 均对应 Laravel 12 的 Blade 引擎能力。规则总览在 SKILL.md 的 §18 中浓缩为四条要点：

• $attributes->merge() in component templates
• Blade components over @include；@pushOnce for per-component scripts
• View Composers for shared view data
• @aware for deeply nested component props

下面逐条展开，并结合仓库源码印证。

二、在组件模板中使用 $attributes->merge()

规则原文：硬编码 class 会阻止使用者（consumer）追加自己的类；merge() 能干净地合并 class 属性。

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $message }}
</div>

这条规则的核心在于「可组合性」：组件模板若直接写死 <div class="...">，外部传入的任何 class 都会被丢弃或无法生效；而 {{ $attributes->merge([...]) }} 会把组件自身声明的默认类与外部传入的 class、id 等属性按规则合并——class 会拼接保留，其他属性（如 data-*、style）则外部优先。

Coolify 中的真实用法

仓库在 resources/views/components/ 下有大量按此规则实现的匿名组件。以 auth/alert.blade.php 为例，它先通过 @props() 声明默认值，再用 @php 块根据 type 计算样式类：

@props([
    'type' => 'info',
])

@php
    $styles = match ($type) {
        'success' => 'border-success/35 bg-success/10 text-success',
        'error'   => 'border-error/35 bg-error/10 text-error',
        'warning' => 'border-warning/35 bg-warning/10 text-warning',
        default   => 'border-neutral-300 bg-neutral-100 text-neutral-700
                     dark:border-white/10 dark:bg-white/[0.04] dark:text-fg-dim',
    };
@endphp

resources/views/components/ 目录中至少 22 个组件文件使用了 $attributes->merge()，覆盖 git-icon.blade.php、empty.blade.php、callout.blade.php、slide-over.blade.php、表单类组件 forms/input.blade.php、forms/select.blade.php、[forms/textarea.blade.php)(resources/views/components/forms/textarea.blade.php) 等。这说明 merge() 模式在 Coolify 中已是「既有模式」——按照 Consistency First 原则，新增组件时应当沿用，而不是引入写死 class 的第二种写法。

三、使用 @pushOnce 处理组件级脚本

规则原文：当组件渲染在 @foreach 内时，@push 会把同一段脚本插入 N 次；@pushOnce 保证它只被包含恰好一次。

典型风险场景是：一个列表页循环渲染 50 个「带初始化的交互组件」，每个组件内部都写 @push('scripts') 注册同一份 JS，页面最终会输出 50 份重复脚本，造成重复初始化、体积膨胀。@pushOnce('scripts', ...)（@once 指令同样可用于包裹一次性输出）按块名去重，只保留第一份。

从当前仓库的检索结果看，resources/ 下尚未检索到 @pushOnce 的实际使用——Coolify 的前端交互主要交给 Livewire 组件承担，页面级脚本较少。这条规则的价值在于预防性约束：一旦未来出现「循环中渲染、且每个组件携带脚本」的视图，应直接选用 @pushOnce，避免重复脚本的隐患。

四、优先使用 Blade 组件而非 @include

规则原文：@include 会隐式共享父视图的全部变量（隐藏耦合）；组件拥有显式的 props、属性袋（attribute bag）和 slots。

两者对比：

维度	@include('x', ['a' => 1])	Blade 组件
变量可见性	隐式继承父视图所有变量，子模板可随意取用，形成隐藏依赖	仅显式声明的 $props、$attributes、slots 可见
契约清晰度	无契约，父视图变量改名会静默破坏子模板	组件头部即 API 文档（@props 带默认值）
属性合并	不支持	支持 $attributes->merge() 等能力
可测试性	只能整页断言	可独立断言组件渲染结果

Coolify 仓库同时存在两种写法：resources/views/livewire/ 下仍有使用 @include( 的视图（如 livewire/storage/index.blade.php、livewire/destination/show.blade.php、source/all.blade.php 等），它们多用于纯静态、无契约的片段复用；而 resources/views/components/empty.blade.php 这类需要行为契约的 UI 则使用组件，头部即声明完整接口：

@props([
    'title',
    'description' => null,
    'size' => 'base', // sm | base | lg
    'iconName' => null, // reicon name; use with icon-name="…"
])

按照规则文档的指引，新增带状态的、需要复用的 UI 应写成组件；@include 保留给确实无需契约的纯展示片段。

五、用 View Composer 集中供给共享视图数据

规则原文：如果每个渲染侧边栏的控制器都必须传 $categories，那是重复代码。View Composer 可以把这件事集中起来。

用法上，在 AppServiceProvider::boot() 中调用 View::composer('sidebar', fn ($view) => $view->with('categories', ...))（或按视图模式批量注册），即可让所有匹配视图自动获得 $categories，控制器不再各自重复查询与传参。

需要如实说明：检索 app/ 与 routes/ 目录后，未发现 Coolify 当前使用 View::composer 的代码。从源码结构看，Coolify 的视图数据供给主要走 Livewire 组件自身的数据方法（public 属性与方法自动进入视图作用域），因此这条规则对本仓库更多是一种「备用工具」——当出现多个控制器/Livewire 组件需要向同一视图注入同一份数据时，它是消除重复查询的标准手段。

六、用 Blade Fragment 做局部重渲染（htmx/Turbo 场景）

规则原文：同一个视图可以返回完整页面，也可以只返回一个 fragment，从而保持路由干净。

文档给出的示例：

return view('dashboard', compact('users'))
    ->fragmentIf($request->hasHeader('HX-Request'), 'user-list');

含义是：普通浏览器请求返回完整 dashboard 页面；当请求携带 htmx 的 HX-Request 头（或可换成 Turbo 等对应请求头判断）时，只返回 id 为 user-list 的 fragment 片段，前端局部替换即可。这样无需为局部刷新单独开辟一条路由，路由定义保持单一。

Coolify 仓库当前未检索到 fragmentIf 的调用，其局部更新依赖 Livewire 的 morphing 机制完成。但从源码结构看，fragmentIf 是 Laravel 12 内建的视图能力，若项目中存在 htmx/Turbo 直连 PHP 端点的场景，这是官方推荐的「单视图、双形态」实现方式，与 Coolify 现有路由风格（如 routes/web.php）并不冲突。

七、用 @aware 承载深层嵌套组件的属性

规则原文：避免把父组件的 props 逐层重新传给每一层嵌套组件。

问题场景：<x-nav> → <x-nav.section> → <x-nav.item> 三层嵌套，最内层的 item 需要用到最外层传入的 activeId 或 theme。没有 @aware 时，只能让中间每一层手动接收再转发，属性链越长越啰嗦。在组件模板顶部声明 @aware(['activeId']) 后，祖先组件中的同名属性会沿组件栈自动向下可见，中间层无需关心。

与 View Composer 一样，当前仓库检索未发现 @aware 的实际用例；Coolify 的组件树以扁平化为主（组件直接由 Livewire 视图调用）。该规则在引入更深层组件嵌套（例如设计系统级组件库）时具有实用价值，可视为预防性约定。

八、规则落地检查清单

将 blade-views.md 的六条规则浓缩为可在代码评审中直接核对的清单：

1. 组件模板中是否用 $attributes->merge() 而非写死 class？（仓库既有模式：resources/views/components/auth/alert.blade.php 等 20 余组件）
2. 循环渲染的组件是否用 @pushOnce 注册脚本，避免 N 份重复？
3. 新增带契约的复用 UI 是否写成组件而非 @include？
4. 多个渲染入口共享同一视图数据时，是否已改用 View Composer 集中注入？
5. htmx/Turbo 局部刷新是否用 ->fragmentIf() 复用同一路由与视图？
6. 深层嵌套组件是否用 @aware 替代逐层透传 props？

最后再次强调 SKILL.md 的总原则：以上规则在 Coolify 中是「无既有模式时的默认值」。写任何视图之前，先检索兄弟文件——仓库已有的 $attributes->merge() 组件写法就是必须跟随的既定模式；而仓库尚未启用的 @pushOnce、View Composer、fragmentIf、@aware 则应视为引入新场景时的首选工具，而不是要求对现有视图做无关紧要的重构。

延伸阅读

• blade-views.md（本文依据的规则原文）
• laravel-best-practices SKILL.md（规则总目录与 Consistency First 原则）
• style.md（约定与风格，含「Blade 中不放 JS/CSS」）
• Livewire 组件视图目录（Coolify 视图层的主要组织位置）