filament 是需显式注册与契约约束的 laravel 后台框架，常见问题源于模型缺 trait、路由未注册、资源未声明；安装后 404 因未手动添加 filament::routes()；资源空白因模型未 use hasfilamenttablecolumns；表单不入库因 $fillable 缺失或字段名不匹配；媒体库报错因插件未按主版本安装且模型缺两个必要 trait。
Filament 不是“装完就能用”的后台模板，它是一套需要明确契约、显式注册、按层组织的 Laravel 后台构建框架。跳过关键步骤，90% 的报错都源于模型没契约、路由没注册、资源没注册这三处。
php artisan filament:install --panels 运行后访问 /admin 404
这是最常见却最容易被忽略的问题：Filament 默认不自动注册路由。即使安装命令成功执行，Filament::routes() 也不会写入任何路由文件。
- 检查
routes/web.php末尾是否手动添加了Filament::routes(); - 确认
config/filament.php中'path' => 'admin'是字符串，不能是/admin或空值 - 若使用 Nginx，确保重写规则包含
try_files $uri $uri/ /index.php?$query_string;，且APP_URL与实际访问域名一致
php artisan make:filament-resource Post 生成后列表页空白或报错 Call to undefined method
Resource 生成只是骨架，模型必须主动声明 Filament 所需的能力，否则字段渲染、关系加载、权限判断全部失效。
- 在
app/Models/Post.php中引入并使用use Filament\Panel\Traits\HasFilamentTableColumns; - 确保模型的
$fillable包含所有表单字段（如'title','content'），否则保存时被 Laravel 拦截静默失败 - 如果用了软删除，且数据库有
deleted_at字段，但未在表单中排除，编辑时会触发Illuminate\Database\QueryException
表单里加了 TextInput::make('title')，但提交后数据库没写入
这不是 Filament 的 bug，而是 Laravel 的批量赋值保护机制在起作用——它只允许白名单字段入库。
- 检查模型
Post是否定义了$fillable = ['title', 'content'];；若用$guarded = []也等效，但不推荐 - 注意字段名大小写：数据库列是
published_at，但表单写成PublishedAt或publishedAt就不会映射 - 如果字段带下划线（如
is_featured），别误写成驼峰isFeatured，Eloquent 不会自动转换
想用 Spatie Media Library 上传图片，但 SpatieMediaLibraryFileUpload 报错 Class not found
这个组件不属于 Filament 核心包，必须单独安装插件，并且版本必须匹配当前 Filament 主版本。
- 运行
composer require filament/spatie-laravel-media-library-plugin:"^5.0"（Filament v5）或"^4.0"（v4），不能用@latest - 执行
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"并migrate - 模型中必须同时 use
Spatie\MediaLibrary\HasMedia和Spatie\MediaLibrary\InteractsWithMedia，缺一不可
Filament 的“零代码”是建立在严格分层和显式契约之上的——它省掉的是模板代码，不是架构理解。漏掉一个 trait、少写一行路由、填错一个版本号，都会让整个流程卡在看似无关的环节。真正快的不是生成命令，而是你第一次就写对那几行关键配置。
