如何将FilamentPHP中的Heroicon版本从v1更换为v2？

API 探路者

2026-8-5

解决FilamentPHP 2.x切换到Heroicon v2的问题

核心原因

FilamentPHP 2.x的filament/forms等核心包强制依赖blade-ui-kit/blade-heroicons ^1.2（即Heroicon v1），所以无法直接替换为纯v2版本，只能同时兼容v1和v2，再手动让Filament调用v2图标。

解决步骤

确保同时安装v1和v2版本
你的composer.json中已经设置了^1.2|^2.10，执行以下命令确保依赖安装完成：
```
composer update blade-ui-kit/blade-heroicons
```

自定义Filament图标注册
在app/Providers/AppServiceProvider.php的boot方法中，注册v2图标替换Filament默认的v1图标：

use Filament\Facades\Filament;
use Illuminate\Support\Facades\Blade;

public function boot()
{
    // 注册单个图标替换示例
    Filament::registerIcons([
        'user' => Blade::render('<x-heroicon-o-user />'), // v2 outline图标
        'user-solid' => Blade::render('<x-heroicon-s-user />'), // v2 solid图标
        // 按需添加你需要替换的其他图标，比如dashboard、settings等
    ]);

    // 全局替换图标解析逻辑
    Filament::resolveUsing(function ($name) {
        // 将Filament默认的v1前缀映射到v2组件
        if (str_starts_with($name, 'heroicon-o-')) {
            return Blade::render('<x-heroicon-o-' . substr($name, 11) . ' />');
        }
        if (str_starts_with($name, 'heroicon-s-')) {
            return Blade::render('<x-heroicon-s-' . substr($name, 11) . ' />');
        }
        return $name;
    }, 'icon');
}

覆盖Filament视图（可选，彻底替换）
如果图标注册方式不够彻底，可发布Filament视图文件并修改图标引用：
```
php artisan vendor:publish --tag=filament-views
```
找到resources/views/vendor/filament下所有包含x-heroicon-o-或x-heroicon-s-的文件，替换为v2对应的组件（注意v2部分图标名称有调整，需核对图标库）。