Livewire 中文文档

主题

安装 ​

Livewire 是一个 Laravel 扩展包，因此你需要先有一个运行中的 Laravel 应用才能安装和使用 Livewire。如果你需要帮助设置新的 Laravel 应用，请参阅Laravel 中文文档。

前置要求 ​

在安装 Livewire 之前，请确保你有：

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

安装 Livewire ​

要安装 Livewire，打开终端并导航到你的 Laravel 应用目录，然后运行以下命令：

shell
composer require livewire/livewire:^4.0

就这样！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 捆绑在一起，因此两者会一起加载。

资源注入是自动的

即使没有这些指令，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()

更新 Livewire 后重新构建资源

手动捆绑时，记得在通过 Composer 更新 Livewire 后重新构建 JavaScript 资源（npm run build）。

自定义 Livewire 的更新端点 ​

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

默认情况下，Livewire 将组件更新发送到 /livewire/update。要自定义此设置，在服务提供者（通常是 App\Providers\AppServiceProvider）中注册你自己的路由：

php
use Livewire\Livewire;

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

你还可以为更新路由添加中间件：

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

自定义 JavaScript 资源 URL ​

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

默认情况下，Livewire 从 /livewire/livewire.js 提供其 JavaScript。要自定义此设置，在服务提供者中注册你自己的路由：

php
use Livewire\Livewire;

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

将 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"
        ]
    }
}

大多数应用不需要这样做

发布资源很少是必要的。只有在你有特定的架构需求阻止 Laravel 动态提供资源时才这样做。

禁用自动资源注入 ​

何时需要： 如果你想完全控制 Livewire 资源何时以及如何加载，可以禁用自动注入。

在你的 config/livewire.php 文件中更新 inject_assets 配置选项：

php
'inject_assets' => false,

禁用后，你必须在布局中手动包含 @livewireStyles 和 @livewireScripts，否则 Livewire 将无法运行。

或者，你可以在特定页面强制资源注入：

php
\Livewire\Livewire::forceAssetInjection();

在你想确保注入资源的路由或控制器中调用此方法。

故障排除 ​

Livewire JavaScript 未加载（404 错误） ​

症状： 访问 /livewire/livewire.js 返回 404 错误，或 Livewire 功能不工作。

常见原因：

Nginx 配置阻止了路由： 如果你使用带有自定义配置的 Nginx，它可能阻止了 Laravel 对 /livewire/livewire.js 的路由。你可以：

路由缓存： 如果你运行过 php artisan route:cache，Laravel 可能无法识别 Livewire 的路由。清除缓存：

shell
php artisan route:clear

缺少 @livewireScripts： 如果你禁用了自动资源注入，确保 @livewireScripts 在布局文件中的 </body> 之前。

没有 Livewire 组件的页面上 Alpine.js 不可用 ​

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

解决方案： 由于 Alpine 与 Livewire 捆绑在一起，你需要在没有 Livewire 组件的页面上也包含 @livewireScripts：

blade
<!DOCTYPE html>
<html>
    <head>
        @livewireStyles
    </head>
    <body>
        <!-- 没有 Livewire 组件，但我们需要 Alpine -->
        <div x-data="{ open: false }">
            <button @click="open = !open">Toggle</button>
        </div>

        @livewireScripts
    </body>
</html>

或者，手动捆绑 Livewire 和 Alpine 并在 JavaScript 中导入 Alpine。

组件不更新或浏览器控制台出现错误 ​

检查以下内容：

  • 确保 @livewireStyles 在布局的 <head> 中
  • 确保 @livewireScripts 在布局的 </body> 之前
  • 检查浏览器开发者控制台是否有 JavaScript 错误
  • 验证你运行的是支持的 PHP 版本（8.1+）和 Laravel 版本（10+）
  • 清除应用缓存：php artisan cache:clear

如果问题仍然存在，请查看故障排除文档获取更详细的调试步骤。