Livewire 中文文档

主题

全部文档

安装 ​

Livewire 是一个 Laravel 扩展包，因此需要先有一个可运行的 Laravel 应用，才能安装和使用 Livewire。若需要搭建新的 Laravel 应用，请参阅官方 Laravel 文档。

前置条件 ​

安装 Livewire 之前，请确认你已具备：

  • Laravel 10 或更高版本
  • PHP 8.1 或更高版本

安装 Livewire ​

要安装 Livewire，打开终端并进入 Laravel 应用目录，然后运行：

shell
composer require livewire/livewire

就这些！Livewire 使用 Laravel 的包自动发现，无需额外配置。

准备好创建第一个组件了吗？ 前往快速开始指南，几分钟内就能写出第一个 Livewire 组件。

创建布局文件 ​

把 Livewire 组件当作整页使用时，需要一个布局文件。可以用 Livewire 命令生成：

shell
php artisan livewire:layout

这会在 resources/views/layouts/app.blade.php 创建布局文件，内容如下：

blade
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title>{{ $title ?? config('app.name') }}</title>

        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @livewireStyles
    </head>
    <body>
        {{ $slot }}

        @livewireScripts
    </body>
</html>

@livewireStyles 和 @livewireScripts 指令会引入 Livewire 运行所需的 JavaScript 和 CSS。Livewire 把 Alpine.js 打包进自己的 JavaScript，因此两者会一起加载。

INFO

资源注入是自动的

即使没有这些指令，Livewire 也会自动把资源注入到包含 Livewire 组件的页面。不过写上指令可以明确控制资源的放置位置，这对性能优化或与其他扩展包兼容会有帮助。

发布配置文件 ​

Livewire 是「零配置」的：遵循约定即可使用，不必额外配置。如果需要，也可以发布并自定义 Livewire 的配置文件：

shell
php artisan livewire:config

这会在 Laravel 应用的 config 目录下创建 livewire.php，你可以在其中调整各项 Livewire 设置。

高级配置 ​

以下章节面向多数应用用不到的进阶场景。只有在有明确需求时才需要配置。

手动打包 Livewire 与 Alpine ​

何时需要： 若要使用 Alpine.js 插件，或需要精细控制 Alpine 与 Livewire 的初始化时机。

默认情况下，Livewire 会自动加载打包在其 JavaScript 中的 Alpine.js。若需要注册 Alpine 插件或自定义初始化顺序，可以用你的 JavaScript 构建工具手动打包 Livewire 和 Alpine。

首先，在布局文件中加上 @livewireScriptConfig 指令：

blade
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title>{{ $title ?? config('app.name') }}</title>

        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @livewireStyles
    </head>
    <body>
        {{ $slot }}

        @livewireScriptConfig
    </body>
</html>

@livewireScriptConfig 会注入 Livewire 需要的配置和运行时全局变量，但不包含 Livewire 与 Alpine 的 JavaScript（因为你要自己打包）。手动打包时，用 @livewireScriptConfig 替换 @livewireScripts。

接下来，在 resources/js/app.js 中导入并启动 Livewire 和 Alpine：

js
import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'

Alpine.plugin(Clipboard)

Livewire.start()

TIP

更新 Livewire 后请重新构建资源

手动打包时，每次通过 Composer 更新 Livewire 后，都要重新构建 JavaScript 资源（npm run build）。

自定义 Livewire 的更新端点 ​

何时需要： 若应用使用本地化路由前缀（如 /en/、/fr/）或多租户（如 /tenant-1/、/tenant-2/），可能需要自定义 Livewire 的更新端点以匹配路由结构。

默认情况下，Livewire 会把组件更新发送到基于哈希的端点，例如 /livewire-{hash}/update，其中 {hash} 由应用的 APP_KEY 派生。要自定义它，请在服务提供者（通常是 App\Providers\AppServiceProvider）中注册自己的路由：

php
use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setUpdateRoute(function ($handle, $path) {
            return Route::post('/custom' . $path, $handle);
        });
    }
}

$path 参数包含基于哈希的路径（例如 /livewire-{hash}/update），从而保留每个安装实例唯一的端点。

也可以给更新路由加上中间件：

php
Livewire::setUpdateRoute(function ($handle, $path) {
    return Route::post('/custom' . $path, $handle)
        ->middleware(['web', 'auth']);
});

自定义 JavaScript 资源 URL ​

何时需要： 若应用使用本地化或多租户的路由前缀，可能需要自定义 Livewire 提供 JavaScript 的地址，以匹配路由结构。

默认情况下，Livewire 从基于哈希的端点提供 JavaScript，例如 /livewire-{hash}/livewire.js，其中 {hash} 由应用的 APP_KEY 派生。这种每个安装实例唯一的路径，会让自动化扫描更难针对 Livewire 应用。

要自定义它，请在服务提供者中注册自己的路由：

php
use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setScriptRoute(function ($handle, $path) {
            return Route::get('/custom' . $path, $handle);
        });
    }
}

$path 参数包含基于哈希的路径（例如 /livewire-{hash}/livewire.js），从而保留每个安装实例唯一的端点。

将 Livewire 资源发布到 public 目录 ​

何时需要： 若希望由 Web 服务器直接提供 Livewire 的 JavaScript（例如走 CDN 或特定缓存策略），而不是经 Laravel 路由。

可以把 Livewire 的 JavaScript 资源发布到 public 目录：

bash
php artisan livewire:publish --assets

为了在更新 Livewire 时保持资源最新，把下面内容加到 composer.json：

json
{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=livewire:assets --ansi --force"
        ]
    }
}

WARNING

多数应用不需要这样做

发布资源通常没有必要。只有在架构上无法让 Laravel 动态提供这些资源时，才需要这样做。

关闭自动资源注入 ​

何时需要： 若要完全控制 Livewire 资源的加载时机与方式，可以关闭自动注入。

在 config/livewire.php 中把 inject_assets 配置改为：

php
'inject_assets' => false,

关闭后，必须在布局中手动加入 @livewireStyles 和 @livewireScripts，否则 Livewire 无法工作。

也可以在特定页面强制注入资源：

php
\Livewire\Livewire::forceAssetInjection();

在希望确保注入资源的路由或控制器中调用即可。

排错 ​

Livewire 的 JavaScript 无法加载（404） ​

症状： Livewire 的 JavaScript 文件返回 404，或 Livewire 功能不工作。

Livewire 从基于哈希的端点提供 JavaScript，例如 /livewire-{hash}/livewire.js，其中 {hash} 由应用的 APP_KEY 派生。这条唯一路径会随安装实例变化。

常见原因：

Nginx 配置拦截了该路由：

若使用了自定义 Nginx 配置，它可能挡住了 Laravel 的动态 Livewire 路由。可以：

  • 配置 Nginx，把匹配 `/livewire-*/` 的请求交给 Laravel：
    nginx
    location ~ ^/livewire-[a-f0-9]+/ {
    try_files $uri $uri/ /index.php?$query_string;
}

  • 手动打包 Livewire，避免经 Laravel 提供资源

  • 发布 Livewire 的资源，由 Web 服务器直接提供

路由缓存：

若运行过 php artisan route:cache，Laravel 可能识别不到 Livewire 的路由。请清除缓存：

shell
php artisan route:clear

缺少 @livewireScripts：

若已关闭自动资源注入，请确保布局文件在 </body> 之前包含 @livewireScripts。

没有 Livewire 组件的页面上无法使用 Alpine.js ​

症状： 想在没有 Livewire 组件的页面上使用 Alpine.js。

解决办法： Alpine 打包在 Livewire 中，因此即使页面没有 Livewire 组件，也需要引入 @livewireScripts：

blade
<!DOCTYPE html>
<html>
    <head>
        @livewireStyles
    </head>
    <body>
        <!-- No Livewire components, but we want Alpine -->
        <div x-data="{ open: false }">
            <button @click="open = !open">Toggle</button>
        </div>

        @livewireScripts
    </body>
</html>

或者，手动打包 Livewire 和 Alpine，并在 JavaScript 中导入 Alpine。

组件不更新，或浏览器控制台报错 ​

请检查：

  • 确保布局的 <head> 中有 @livewireStyles
  • 确保 @livewireScripts 在布局的 </body> 之前
  • 查看浏览器开发者工具控制台是否有 JavaScript 错误
  • 确认 PHP 版本为 8.1+、Laravel 版本为 10+
  • 清除应用缓存：php artisan cache:clear

若问题仍在，请查阅排错文档获取更详细的调试步骤。