Filament v4 自定义主题如何升级到 Tailwind CSS v4 并配置 @source 路径？

Filament v4 自定义主题如何升级到 Tailwind CSS v4 并配置 @source 路径？

【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps & admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament

把带有自定义主题的 Filament 应用从 v3 升级到 v4 时，自定义主题的 CSS 写法必须跟着变：v3 用@config 'tailwind.config.js'引入 Tailwind v3 的 JS 配置，v4 则要求改用 Tailwind CSS v4 的 CSS-first 配置，并用@source指令告诉 Tailwind 去哪里扫描你代码中使用的工具类。本文按 升级指南 和 自定义主题文档 给出完整的操作路径。

适用前提：你的项目目前使用 Tailwind CSS v3 与 Filament 自定义主题 CSS 文件。升级指南明确说明，如果面板没有自定义主题 CSS 文件，Tailwind CSS v4.1+ 这条要求不适用于你。

版本要求与准备工作

Filament v4 的新要求：

• PHP 8.2+
• Laravel v11.28+
• Tailwind CSS v4.1+（仅当你在用 Tailwind v3 + 自定义主题 CSS 文件时）
• Filament 不再依赖doctrine/dbal；如果你的应用仍需要它且没有直接安装，要自行加进composer.json

升级的第一步是运行自动化升级脚本。注意两点：如果安装脚本失败，确认 PHPStan 版本至少 v2、Larastan 至少 v3（脚本使用 Rector v2，要求 PHPStan v2+）；Windows PowerShell 会忽略版本号约束中的^，需要改用~：

composer require filament/upgrade:"^4.0" -W --dev vendor/bin/filament-v4 # Run the commands output by the upgrade script, they are unique to your app composer require filament/filament:"^4.0" -W --no-update composer update

Windows PowerShell 下对应命令：

composer require filament/upgrade:"~4.0" -W --dev vendor/bin/filament-v4 # Run the commands output by the upgrade script, they are unique to your app composer require filament/filament:"~4.0" -W --no-update composer update

升级脚本不是升级指南的替代品：它处理了大量重复性改动，但不覆盖所有 breaking change。运行后要仔细审查脚本修改的内容，并核对手动升级清单。另外，部分插件可能尚未提供 v4 版本，可以先从composer.json中临时移除它们，等插件升级后再加回。

把主题 CSS 中的@config替换为@source

自定义主题 CSS 文件里，v3 的写法是：

@import '../../../../vendor/filament/filament/resources/css/theme.css'; @config 'tailwind.config.js';

v4 下应改为：

@import '../../../../vendor/filament/filament/resources/css/theme.css'; @source '../../../../app/Filament/**/*'; @source '../../../../resources/views/filament/**/*';

@import一行加载 Tailwind CSS，@source条目告诉 Tailwind 在你的应用里哪里可以找到用到的类。配置@source路径的具体做法：

1. 查看你旧的tailwind.config.js中的content路径，把它们逐条转写成@source条目。
2. vendor/filament不需要作为@source加入。
3. 检查已安装的插件，看它们是否要求你额外添加@source条目。

运行 Tailwind 官方升级工具

CSS 改完后，运行 Tailwind 的升级工具，它会自动调整你的配置文件以适配 Tailwind v4，并安装 Tailwind v4 的包来替换 v3 的包。该命令会修改你的前端依赖（卸载 v3 相关包、安装 v4 相关包），执行前建议先确认package.json处于干净状态：

npx @tailwindcss/upgrade

完成这一步后，主题的tailwind.config.js文件将不再被使用——Tailwind CSS v4 改为在 CSS 中定义配置。你之前对tailwind.config.js做的自定义项，都要迁进主题 CSS 文件里。

可选分支：没有自定义主题，但自己在代码里用了 Tailwind 类

v4 中 Filament 自身的 Tailwind 类已经移入 CSS 文件、改用@apply指令编写，不再被 Tailwind 扫描，因此不会出现在 Filament 的默认样式表里。如果你在 v3 时期依赖 Filament 的编译产物来提供自己代码中的类（例如在 Blade 视图里直接写hidden、text-primary-600），升级后这些样式会失效，需要先创建自定义主题：

php artisan make:filament-theme

多个面板时指定面板 ID，例如php artisan make:filament-theme admin；不用 NPM 时可用--pm选项，例如php artisan make:filament-theme --pm=bun。该命令会安装 Tailwind 依赖、在resources/css/filament/{panel}/theme.css生成 CSS 文件、尝试把主题加入vite.config.js的input数组、尝试在 panel provider 中注册->viteTheme()，并提示你用 Vite 编译。

如果命令无法自动配置你的文件（例如文件格式不规范），它会打印手动说明，按以下步骤操作：

// vite.config.js input: [ // ... 'resources/css/filament/admin/theme.css', ]

use Filament\Panel; public function panel(Panel $panel): Panel { return $panel // ... ->viteTheme('resources/css/filament/admin/theme.css'); }

然后在生成的theme.css中，为使用 Tailwind 类的文件添加@source条目，例如：

@source '../../../../app/Filament/**/*'; @source '../../../../resources/views/filament/**/*'; @source '../../../../resources/views/components/**/*'; /* Add your own paths */ @source '../../../../resources/views/livewire/**/*'; /* Add your own paths */

重新编译并验证

修改@source路径后，用 Vite 重新编译主题：

npm run build

验证方式：打开使用这些工具类的页面（自定义 Blade 视图、Livewire 组件等），确认样式按预期生效。文档指出的失效模式是——如果某个目录没有被@source覆盖，该目录中使用的类不会进入编译后的 CSS，样式不会应用。发现样式丢失时，回到主题 CSS 检查对应文件位置是否被某条@source通配路径覆盖，补上后重新执行npm run build。

升级全部完成后，升级包可以移除：

composer remove filament/upgrade --dev

相关文档：docs/14-upgrade-guide.md、docs/08-styling/01-overview.md。

【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps & admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament