安装

您是视觉学习者吗？
通过我们深入的屏幕录制掌握 Livewire
立即观看

Livewire 是一个 Laravel 软件包，因此在安装和使用 Livewire 之前，您需要启动并运行一个 Laravel 应用程序。如果您需要帮助设置新的 Laravel 应用程序，请参阅官方 Laravel 文档。

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

composer require livewire/livewire

就是这样 — 真的是这样。如果您想要更多自定义选项，请继续阅读。否则，您可以直接开始使用 Livewire。

/livewire/livewire.js 返回 404 状态代码

默认情况下，Livewire 在您的应用程序中公开一个路由，以从以下位置提供其 JavaScript 资产：/livewire/livewire.js。对于大多数应用程序来说，这很好，但是，如果您在使用具有自定义配置的 Nginx，您可能会从该端点收到 404。要解决此问题，您可以自行编译 Livewire 的 JavaScript 资产，或配置 Nginx 以允许这样做。

发布配置文件

Livewire 是“零配置”的，这意味着您可以按照惯例使用它，而无需任何其他配置。但是，如果需要，您可以通过运行以下 Artisan 命令来发布和自定义 Livewire 的配置文件

php artisan livewire:publish --config

这将在您的 Laravel 应用程序的config目录中创建一个新的livewire.php文件。

手动包含 Livewire 的前端资产

默认情况下，Livewire 会将它需要的 JavaScript 和 CSS 资产注入到包含 Livewire 组件的每个页面中。

如果您想更多地控制此行为，可以使用以下 Blade 指令手动在页面上包含资产

<html>
<head>
    ...
    @livewireStyles
</head>
<body>
    ...
    @livewireScripts
</body>
</html>

通过在页面上手动包含这些资源，Livewire 知道不要自动注入资源。

AlpineJS 与 Livewire 捆绑在一起

因为 Alpine 与 Livewire 的 JavaScript 资源捆绑在一起，所以你必须在希望使用 Alpine 的每个页面上包含 @livewireScripts。即使你没有在该页面上使用 Livewire。

尽管很少需要，但你可以通过更新应用程序的 config/livewire.php 文件中的 inject_assets 配置选项 来禁用 Livewire 的自动注入资源行为

'inject_assets' => false,

如果你希望强制 Livewire 在单个页面或多个页面上注入其资源，你可以从当前路由或服务提供程序调用以下全局方法。

\Livewire\Livewire::forceAssetInjection();

配置 Livewire 的更新端点

Livewire 组件中的每次更新都会在以下端点向服务器发送网络请求：https://example.com/livewire/update

对于一些使用本地化或多租户的应用程序来说，这可能是一个问题。

在这些情况下，你可以根据需要注册自己的端点，只要你这样做是在 Livewire::setUpdateRoute() 内，Livewire 就会知道对所有组件更新使用此端点

Livewire::setUpdateRoute(function ($handle) {
    return Route::post('/custom/livewire/update', $handle);
});

现在，Livewire 将向 /custom/livewire/update 发送组件更新，而不是使用 /livewire/update。

因为 Livewire 允许你注册自己的更新路由，所以你可以声明任何你希望 Livewire 直接在 setUpdateRoute() 内使用的附加中间件

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

自定义资源 URL

默认情况下，Livewire 将从以下 URL 提供其 JavaScript 资源：https://example.com/livewire/livewire.js。此外，Livewire 将像这样从脚本标记引用此资源

<script src="/livewire/livewire.js" ...

如果你的应用程序由于本地化或多租户而具有全局路由前缀，你可以注册自己的端点，Livewire 在获取其 JavaScript 时应在内部使用该端点。

要使用自定义 JavaScript 资源端点，你可以在 Livewire::setScriptRoute() 内注册自己的路由

Livewire::setScriptRoute(function ($handle) {
    return Route::get('/custom/livewire/livewire.js', $handle);
});

现在，Livewire 将像这样加载其 JavaScript

<script src="/custom/livewire/livewire.js" ...

手动捆绑 Livewire 和 Alpine

默认情况下，Alpine 和 Livewire 使用 <script src="livewire.js"> 标记加载，这意味着你无法控制加载这些库的顺序。因此，如以下示例所示，导入和注册 Alpine 插件将不再起作用

// Warning: This snippet demonstrates what NOT to do...
 
import Alpine from 'alpinejs'
import Clipboard from '@ryangjchandler/alpine-clipboard'
 
Alpine.plugin(Clipboard)
Alpine.start()

要解决此问题，我们需要告知 Livewire 我们希望自己使用 ESM（ECMAScript 模块）版本，并阻止注入 livewire.js 脚本标记。要实现此目的，我们必须将 @livewireScriptConfig 指令添加到我们的布局文件（resources/views/components/layouts/app.blade.php）中

<html>
<head>
    <!-- ... -->
    @livewireStyles
    @vite(['resources/js/app.js'])
</head>
<body>
    {{ $slot }}
 
    @livewireScriptConfig 
</body>
</html>

当 Livewire 检测到 @livewireScriptConfig 指令时，它将不会注入 Livewire 和 Alpine 脚本。如果你正在使用 @livewireScripts 指令来手动加载 Livewire，请务必将其删除。确保添加 @livewireStyles 指令（如果尚未存在）。

最后一步是在我们的 app.js 文件中导入 Alpine 和 Livewire，这允许我们注册任何自定义资源，并最终启动 Livewire 和 Alpine

import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'
 
Alpine.plugin(Clipboard)
 
Livewire.start()
在 composer update 后重新构建你的资源

确保如果你正在手动捆绑 Livewire 和 Alpine，那么在你每次运行 composer update 时重新构建你的资源。

与 Laravel Mix 不兼容

如果你正在手动捆绑 Livewire 和 AlpineJS，Laravel Mix 将不起作用。相反，我们建议你 切换到 Vite。

发布 Livewire 的前端资源

发布资源不是必需的

发布 Livewire 的资源对于 Livewire 运行不是必需的。只有在你有特定需要时才这样做。

如果你希望 JavaScript 资源由你的 Web 服务器提供，而不是通过 Laravel，请使用 livewire:publish 命令

php artisan livewire:publish --assets

为了保持资源是最新的并避免在未来更新中出现问题，我们强烈建议你将以下命令添加到你的 composer.json 文件中

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