升级指南

除了将默认的磁盘改成了 local 外，默认情况下，各个组件的文件可见性设置已更改为 private，而不是 public。

Filament 初创时，Laravel 没有为本地文件生成临时签名 URL 的方法。因此，Filament 的默认磁盘设置为 public，文件上传的可见性也设置为 public 以简化开发体验，而无需额外配置。

然而，Laravel 11 引入了一个新的“本地临时 URL”功能，该功能默认启用。在添加此功能之前创建项目的用户可能必须更新其 config/filesystems.php 文件才能启用它。

在 v4 中，Filament 的默认磁盘设置为 local，文件上传的可见性默认设置为 private。这意味着默认情况下文件不可公开访问，你需要生成一个临时签名的 URL 来访问它们。此更改会影响以下组件：

• FileUpload 表单字段，包括 SpatieMediaLibraryFileUpload
• ImageColumn 表格列字段，包括 SpatieMediaLibraryImageColumn
• ImageEntry 信息列表 entry，包括 SpatieMediaLibraryImageEntry

use Filament\Forms\Components\FileUpload;
use Filament\Infolists\Components\ImageEntry;
use Filament\Tables\Columns\ImageColumn;

FileUpload::configureUsing(fn (FileUpload $fileUpload) => $fileUpload
    ->visibility('public'));

ImageColumn::configureUsing(fn (ImageColumn $imageColumn) => $imageColumn
    ->visibility('public'));

ImageEntry::configureUsing(fn (ImageEntry $imageEntry) => $imageEntry
    ->visibility('public'));

之前，自定义主题的 CSS 文件应该包含这些：

@import '../../../../vendor/filament/filament/resources/css/theme.css';

@config 'tailwind.config.js';

现在，应该包含这些：

@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament';
@source '../../../../resources/views/filament';

这将加载 Tailwind CSS。@source 告诉 Tailwind 在哪里可以找到你应用中使用的类。你应该检查在旧的 tailwind.config.js 文件中的 content 路径，并将像这样将它们添加为 @source 条目。你不需要导入 vendor/filament 作为 @source，不过请检查你安装的插件查看它们是否需要 @source 条目。

最后，你应该使用 [Tailwind 升级工具]((https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool)自动调整配置文件以使用 Tailwind v4，并安装 Tailwind v4 包以替换 Tailwind v3 包：

npx @tailwindcss/upgrade

用于主题的 tailwind.config.js 文件不再使用，因为 Tailwind CSS v4 在 CSS 中定义了配置。你对 tailwind.config.js 文件所做的任何自定义都应该添加到 CSS 文件中。

Filament v3 的 deferFilters() 方法现在在 Filament v4 中是默认行为。因此，用户点击按钮之后，过滤器才会应用到表格中。要禁用该行为，你可以使用 deferFilters(false) 方法。

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->deferFilters(false);
}

use Filament\Tables\Table;

Table::configureUsing(fn (Table $table) => $table
    ->deferFilters(false));

在 v3 中，Grid、Section 和 Fieldset 布局组件默认消费了其父级网格的所有宽度。这与 Filament 中其他所有组件的行为不一致，默认情况下，Filament 只消耗一列网格。其目的是使这些组件更容易集成到默认的 Filament 资源表单和 infolist 中，也即使用开箱即用的两列网格。

在 v4 中，Grid、Section 和 Fieldset 布局组件现在默认只消费一列网格。如果你希望它们占有所有列宽，请使用 columnSpanFull() 方法：

use Filament\Schemas\Components\Fieldset;
use Filament\Schemas\Components\Grid;
use Filament\Schemas\Components\Section;

Fieldset::make()
    ->columnSpanFull()
    
Grid::make()
    ->columnSpanFull()

Section::make()
    ->columnSpanFull()

use Filament\Schemas\Components\Fieldset;
use Filament\Schemas\Components\Grid;
use Filament\Schemas\Components\Section;

Fieldset::configureUsing(fn (Fieldset $fieldset) => $fieldset
    ->columnSpanFull());

Grid::configureUsing(fn (Grid $grid) => $grid
    ->columnSpanFull());

Section::configureUsing(fn (Section $section) => $section
    ->columnSpanFull());

在 v3 中 ，unique() 方法验证默认不忽略当前表格 Eloquent 记录。该行为通过 ignoreRecord: true 参数启用，或者传入一个自定义的ignorable 记录。

在 v4 中，unique() 方法的 ignoreRecord 参数默认为 true。

如果你之前使用了 unique() 验证规则而未使用 ignoreRecord 或者 ignorable 参数，你应该使用 ignoreRecord: false 来禁用该新行为。

use Filament\Forms\Components\Field;

Field::configureUsing(fn (Field $field) => $field
    ->uniqueValidationIgnoresRecordByDefault(false));

all 页选项现在默认对表格不可用。如果你想要将其用到表格上，你可以将其添加到配置中：

use Filament\Tables\Table;

public function table(Table $table): Table
{
    return $table
        ->paginationPageOptions([5, 10, 25, 50, 'all']);
}

请注意使用 all 处理大量记录会带来性能问题。

use Filament\Tables\Table;

Table::configureUsing(fn (Table $table) => $table
    ->paginationPageOptions([5, 10, 25, 50, 'all']));

去年，Filament 团队决定将 Spatie Translatable 插件转交给 Lara Zeus 团队，它是许多 Filament 插件的可靠开发者。从那之后，他们维护了该插件的 fork。

因此，官方 Spatie Translatable 插件将不接受 v4 支持，现已弃用。你可以使用 Lara Zeus Translatable 插件作为替代方案。该插件与 Spatie Translatable 官方插件同个版本号兼容，且已经通过 Filament v4 测试。它同时也修复了官方插件中长期存在的一些插件。

自动升级脚本建立命令行卸载官方插件并安装 Lara Zeus 插件，并将代码中的引用从官方插件改成 Lara zeus 插件。

在 v3 中使用租户时，Filament 只对当前租户限定资源查询范围(Scope)：以渲染资源表格、解析 URL 参数以及获取全局搜索结果。在许多情况下，面板中的其他查询默认情况下没有限定查询范围，开发人员必须手动限定。虽然这是一个有文档化的特性，但它为开发人员带来了很多额外的工作。

在 v4 中，Filament 会自动将面板中的所有查询范围限定为当前租户，并使用模型事件自动将新记录与当前租户相关联。这意味着在大多数情况下，你不再需要手动限定查询范围或关联新的 Eloquent 记录。还有一些重要的问题需要考虑，因此文档已经更新以反映这一点。

在 v3 中，inline() 方法将 Radio 按钮与其他同类串联在同一行，同时也与其标签串联。这与其他组件是不一致的。

在 v4 中，inline() 方法只将 Radio 按钮与其他同类 Radio 串联在同一行，而不包括标签。如果你想让其与标签内联在一起，可以使用 inlineLabel() 方法。

如果你之前使用 inline()->inlineLabel(false) 来达成 v4 的默认行为，你现在可以只使用 inline()。

use Filament\Forms\Components\Radio;

Radio::configureUsing(fn (Radio $radio) => $radio
    ->inlineLabel(fn (): bool => $radio->isInline()));

在 Filament v3 中，如果导入和导出作业失败，则会持续重试 24 小时，默认情况下重试没有间隔事件。这给一些用户带来了问题，因为没有间隔，而且作业可能会很快重试，导致队列中充斥着不断失败的作业。

在 v4 中，它们被重试 3 次，每次重试之间有 60 秒的回退。

该行为可以在导入器和导出器类中自定义。

以前，用户可以使用 isSeparate 参数将有限图像的数量单独显示到图像堆栈中。现在该参数已被删除，如果存在堆栈，文本将始终堆叠在顶部，而不是分开。如果图像没有堆叠，文本将是单独的。

disableGrammarly() 方法已经从 RichEditor 组件中移除。该方法用于禁止 Grammarly 浏览器扩展在该编辑器上使用。由于将底层的实现从 Trix 移动到 TipTap 后，没有找到在编辑器上禁用 Grammarly 的方式。

Field::make(), MorphToSelect::make(), Placeholder::make(), and Builder\Block::make() 方法的签名已经改变。任何继承 Field, MorphToSelect, Placeholder 或 Builder\Block 和重写 make() 方法的类必须更新方法签名以匹配新的签名。新签名如下：

public static function make(?string $name = null): static

此变更是因为引入了 getDefaultName() 方法，如果没有指定值(null)，可以通过重写它来提供默认的 $name 值。如果你此前重写了 make() 方法来提供默认的 $name 值，现在建议通过重写 getDefaultName() 方法来实现，以避免将来的维护负担：

public static function getDefaultName(): ?string
{
    return 'default';
}

如果你重写了 make() 方法，以便在其初始化时传入默认配置，则推荐改为重写 stepUp() 方法，该方法在对象初始化之后立即调用：

protected function setUp(): void
{
    parent::setUp();

    $this->label('Default label');
}

理想情况下，你应该避免重写 make() 方法，因为还有 setUp() 等替代方法，如果 Filament 决定在未来引入新的构造函数参数，这样做会导致你的代码变得脆弱。

Entry::make() 方法的签名已经改变。任何继承 Entry 类和重写 make() 方法的类都必须更新其签名使之匹配新的签名。新签名如下：

public static function make(?string $name = null): static

此变更是因为引入了 getDefaultName() 方法，如果没有指定值(null)，可以通过重写它来提供默认的 $name 值。如果你此前重写了 make() 方法来提供默认的 $name 值，现在建议通过重写 getDefaultName() 方法来实现，以避免将来的维护负担：

public static function getDefaultName(): ?string
{
    return 'default';
}

如果你重写了 make() 方法，以便在其初始化时传入默认配置，则推荐改为重写 stepUp() 方法，该方法在对象初始化之后立即调用：

protected function setUp(): void
{
    parent::setUp();

    $this->label('Default label');
}

理想情况下，你应该避免重写 make() 方法，因为还有 setUp() 等替代方法，如果 Filament 决定在未来引入新的构造函数参数，这样做会导致你的代码变得脆弱。

Column::make() 和 Constraint::make() 方法的签名已经改变。任何继承 Column::make() 和 Constraint::make() 类和重写 make() 方法的类都必须更新其签名使之匹配新的签名。新签名如下：

public static function make(?string $name = null): static

此变更是因为引入了 getDefaultName() 方法，如果没有指定值(null)，可以通过重写它来提供默认的 $name 值。如果你此前重写了 make() 方法来提供默认的 $name 值，现在建议通过重写 getDefaultName() 方法来实现，以避免将来的维护负担：

public static function getDefaultName(): ?string
{
    return 'default';
}

如果你重写了 make() 方法，以便在其初始化时传入默认配置，则推荐改为重写 stepUp() 方法，该方法在对象初始化之后立即调用：

protected function setUp(): void
{
    parent::setUp();

    $this->label('Default label');
}

理想情况下，你应该避免重写 make() 方法，因为还有 setUp() 等替代方法，如果 Filament 决定在未来引入新的构造函数参数，这样做会导致你的代码变得脆弱。

ExportColumn::make() 和 ImportColumn::make() 方法的签名已经改变。任何继承 ExportColumn 或 ImportColumn 类和重写 make() 方法的类都必须更新其签名使之匹配新的签名。新签名如下：

public static function make(?string $name = null): static

此变更是因为引入了 getDefaultName() 方法，如果没有指定值(null)，可以通过重写它来提供默认的 $name 值。如果你此前重写了 make() 方法来提供默认的 $name 值，现在建议通过重写 getDefaultName() 方法来实现，以避免将来的维护负担：

public static function getDefaultName(): ?string
{
    return 'default';
}

如果你重写了 make() 方法，以便在其初始化时传入默认配置，则推荐改为重写 stepUp() 方法，该方法在对象初始化之后立即调用：

protected function setUp(): void
{
    parent::setUp();

    $this->label('Default label');
}

理想情况下，你应该避免重写 make() 方法，因为还有 setUp() 等替代方法，如果 Filament 决定在未来引入新的构造函数参数，这样做会导致你的代码变得脆弱。

In v3, the Illuminate\Auth\Events\Login event was fired from the import and export jobs, to set the current user. This is no longer the case in v4: the user is authenticated, but that event is not fired, to avoid running any listeners that should only run for actual user logins.

虽然这些方法(如 canCreate(), canViewAny() 和 canDelete()) 没有记入文档，在 v3 中重写这些类可以提供自定义授权逻辑，你应该清楚的是，他们在 v4 中不总是被调用。新版本中授权被改进来正确支持策略，而这些方法太过简单因为他们只能返回布尔值。

如果你能够在模型策略中实现自定义授权，请使用该方式实现。如果你需要在资源或资源管理类中自定义授权逻辑，你应该重写 get*AuthorizationResponse() 方法，比如 getCreateAuthorizationResponse(), getViewAnyAuthorizationResponse() 和 getDeleteAuthorizationResponse()。这些方法在授权逻辑执行时调用，并返回策略响应对象。如果你删除了重写的 can*() 方法， get*AuthorizationResponse() 方法将用于确定授权响应布尔值，因此你无需两次维护其逻辑。

欧洲葡萄牙语已经从 pt_PT 改为 pt，其为 Laravel 社区中更常用的语言代码。

尼泊尔语翻译已经从 np 改为 ne，其为 Laravel 社区中更常用的语言代码。

挪威语翻译翻译已经从 no 改为 nb，其为 Laravel 社区中更常用的语言代码。

高棉语翻译已经从 kh 改为 km，其为 Laravel 社区中更常用的语言代码。

Filament v3 之前，表格可以通过重写 Livewire 组件类方法来配置，而不是修改 $table 配置对象。这在 v3 中弃用，在 v4 中删除了。如果你使用以下这些方法，应该将其从 Livewire 组件类中删除，而使用对应的 $table 配置方法：

• getTableRecordUrlUsing() 应该替换成 $table->recordUrl()
• getTableRecordClassesUsing() 应该替换成 $table->recordClasses()
• getTableRecordActionUsing() 应该替换成 $table->recordAction()
• isTableRecordSelectable() 应该替换成 $table->checkIfRecordIsSelectableUsing()