中文 Livewire 指南 / 2026

把动态界面,
写回 PHP。

不把页面交给另一套运行时。用 Laravel 组合 PHP,用 Livewire 把状态、校验和反馈留在同一条清晰的路径上。

单文件组件 · 浏览器本地校验 · 当前页面预览

01 / 交互的秩序

复杂的事情,
留在服务端。

Livewire 让浏览器负责呈现,让 PHP 负责判断。你写下的每一行规则,都离业务更近。

以下内容介绍真实 Livewire 应用的工作方式;当前 Astro 静态站只阅读这些概念,不运行 Livewire。

01

状态,和页面在一起

字段绑定到组件属性,提交时不需要另写一套状态管理。

public string $title = '';
02

校验,交给 PHP

在真实应用中,必填、长度和字段名称都在服务端确认,反馈直接回到输入框。

$this->validate(...)
03

反馈,留在当前页

发布结果只存在于组件内存,读完即走,不给数据库添负担。

wire:loading

02 / 从零开始

五步,
跑起第一个组件。

下面是 Livewire 4 官方快速上手的中文骨架,可以对照 4.x 快速上手 一起读。先理解这条链路,再用本页的静态演示体验浏览器本地校验。

官方要求 Laravel 10 及以上、PHP 8.1 及以上;本页内容以 Laravel 13 与 PHP 8.4 为例,完全兼容这条官方流程。

  1. 01

    安装 Livewire

    在 Laravel 项目根目录引入 Livewire 4,不需要再配前端框架。

    composer require livewire/livewire
  2. 02

    生成页面布局

    布局负责引入样式、脚本,并用 {{ $slot }} 留出组件位置。

    php artisan livewire:layout
  3. 03

    创建一个页面组件

    用页面组件名前缀保持整洁,生成后即可得到一个单文件组件。文件名中的闪电符号只是为了在编辑器中快速识别,也可以在配置中关闭。

    php artisan make:livewire pages::post.create
  4. 04

    写状态、动作和模板

    属性保存状态,方法处理提交,模板只负责呈现和反馈。

    public string $title = '';
    
    public function save(): void
    {
        $this->validate(['title' => 'required']);
    }
  5. 05

    注册路由并访问

    把组件挂到路由上,打开页面即可看到无刷新表单。

    Route::livewire('/post/create', 'pages::post.create');

官方示例组件全文

把下面这份代码放进 resources/views/pages/post/⚡create.blade.php,就是官方演示用的文章表单。注意它刻意没有样式,重点是状态、校验和提交;以下代码只作说明,不会在 Astro 页面运行。

<?php

use Livewire\Component;

new class extends Component
{
    public string $title = '';

    public string $content = '';

    public function save()
    {
        $this->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);

        dd($this->title, $this->content);
    }
};
?>

<form wire:submit="save">
    <label>
        Title
        <input type="text" wire:model="title">
        @error('title') <span>@{{ $message }}</span> @enderror
    </label>

    <label>
        Content
        <textarea wire:model="content" rows="5"></textarea>
        @error('content') <span>@{{ $message }}</span> @enderror
    </label>

    <button type="submit">Save Post</button>
</form>
组件属性
$title 和 $content 保存用户输入,是组件在服务端的状态。
组件方法
save() 在提交时被调用,先校验,再用 dd() 输出结果,方便确认数据链路。
绑定指令
wire:submit 阻止整页刷新并调用方法;wire:model 把输入框和属性连起来;@error 负责在字段下方显示错误。
校验时机
在真实 Livewire 应用中,输入时不会频繁请求服务器,点提交后才统一校验;如果想边填边校验,可以继续看官方实时校验文档。

生产环境一般怎么写

演示用 dd() 停下来看数据,真实项目通常是写入数据库再跳转。

public function save()
{
    $validated = $this->validate([
        'title' => 'required|max:255',
        'content' => 'required',
    ]);

    Post::create($validated);

    return $this->redirect('/posts');
}

提交状态也属于 Livewire 模板

在真实 Livewire 表单中,可以用加载指令禁用按钮、切换文案并播报进度;本页静态演示使用原生 JavaScript 实现相同状态。

<button type="submit"
    wire:loading.attr="disabled"
    wire:target="publish">
    <span wire:loading.remove wire:target="publish">发布文章</span>
    <span wire:loading wire:target="publish">正在发布…</span>
</button>

动手验证两次

  1. 在真实 Livewire 应用中空表单直接提交,应该在两个字段下方看到服务端返回的错误,而且页面没有刷新。

  2. 填好标题和内容再提交,应该能看到提交成功后的数据回显;在本页则使用浏览器本地校验与当前页面预览。

03 / 发布台

写一段,
立即看见回声。

这是静态站演示:内容由浏览器本地校验,只在当前页面预览,不会发送到服务器,也不会运行 Livewire。

文章标题
必填,最多 80 个字符;错误会回到标题输入框。
文章内容
必填,最多 2000 个字符;错误会回到内容输入框。
预览结果
只保存在当前页面内存,刷新页面即消失。
  1. 01

    填写标题与内容

  2. 02

    浏览器执行本地校验

  3. 03

    在当前页面阅读预览

ARTICLE / 001

预览一篇文章

静态站演示
最多 80 字
最多 2000 字

浏览器本地校验 / 当前页面预览 · 内容不会上传或写入数据库。

04 / 常见问题

先看这里,
少走弯路。

这些都是 Livewire 4 新手最容易遇到的现场问题,对照检查即可。

提示组件找不到,应该先查哪里?

先确认组件文件路径与路由中的组件名一致,例如页面组件应为 pages::post.create。再检查文件名、命名空间分隔符和路由拼写是否完全对应。

提交没有反应,也没有错误信息?

先检查布局里是否有 @livewireStyles 和 @livewireScripts,再打开浏览器控制台,看 Livewire 更新请求是否成功返回。

访问页面返回 404,可能漏了哪一步?

多半是路由没有注册或路径不一致。请确认 routes/web.php 中已经挂载对应组件,然后用 php artisan route:list 核对实际路径。

为什么组件只能有一个根元素?

Livewire 需要用一个稳定的根节点跟踪组件状态。把模板内容包在一个 <form> 或 <div> 里,更新和校验才不会错位。

标题明明没超长,为什么还是校验失败?

先看失败的是必填还是长度。空提交会触发必填错误;只有真正超过 80 或 2000 个字符时,才会触发长度错误,页面会明确告诉你是哪一种。

05 / 下一步

发布台之后,
读这五份文档。

从组件结构开始,逐步进入属性、动作、表单和完整校验体系。也可以回到 Livewire 官网 阅读英文原文。

06 / 参与与许可

用完指南,
也可以参与上游。

以下入口来自 Livewire 官方 README:贡献、行为准则、安全反馈和开源许可都在这里。

07 / 技术栈

少一点切换,
多一点连贯。

从真实 Livewire 项目的路由到构建,再回到当前静态站的发布链路,页面本身不依赖 UI 框架。

01

Laravel 13

真实应用中,路由、会话与验证保持在同一条 PHP 请求链上。

后端
02

Livewire 4

单文件组件承载状态、动作与页面内反馈;当前页面仅展示官方用法。

交互
03

Bun + Astro

用 Bun 安装依赖,用 Astro 生成可部署到 GitHub Pages 的静态站。

构建
04

原生 CSS + 原生 JS

不引入 Tailwind、React 或 Vue,动效与表单都服务于阅读。

界面