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.2Laravel v11.28Tailwind CSS v4.1仅当你在用 Tailwind v3 自定义主题 CSS 文件时Filament 不再依赖doctrine/dbal如果你的应用仍需要它且没有直接安装要自行加进composer.json升级的第一步是运行自动化升级脚本。注意两点如果安装脚本失败确认 PHPStan 版本至少 v2、Larastan 至少 v3脚本使用 Rector v2要求 PHPStan v2Windows 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 updateWindows 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 CSSsource条目告诉 Tailwind 在你的应用里哪里可以找到用到的类。配置source路径的具体做法查看你旧的tailwind.config.js中的content路径把它们逐条转写成source条目。vendor/filament不需要作为source加入。检查已安装的插件看它们是否要求你额外添加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 --pmbun。该命令会安装 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考