必须使用 laravel-admin 1.8.x + Laravel 9.x 组合，因 2.x 已停止维护且与 PHP 8.2+、Laravel 10/11 不兼容，会导致 Class not found、路由不加载、页面空白等问题。
直接装 laravel-admin 最新版（2.x）基本会失败，Class 'Encore\Admin\Form' not found 或路由完全不加载是典型症状。必须用 laravel-admin 1.8.x + Laravel 9.x 组合，这是当前（2026年）唯一稳定能跑通的搭配。
为什么 laravel-admin 2.x 不能用
新版已停止维护，PHP 8.2+ 下大量类型反射失效，Laravel 10/11 的容器绑定机制也和它不兼容。即使强行 composer require 成功，php artisan admin:install 也会卡在 migration 阶段，或生成的后台页面空白、JS 报错。
- 报错
Target class [Admin] does not exist：多半是AdminServiceProvider没注册进容器，新版 Laravel 的自动发现机制跳过了它 - 路由访问返回 404：不是路由没定义，而是
Encore\Admin\Routes的服务提供者根本没加载 - 前端资源 404：新版默认把静态文件扔进
public/vendor/admin，但 Laravel 10+ 的 asset() 辅助函数默认拼的是vendor/laravel-admin路径
正确安装步骤（Laravel 9 + laravel-admin 1.8）
别在已有项目里硬升，从干净环境起步最省事：
- 新建项目：
composer create-project laravel/laravel myapp "9.*" - 装配套 admin：
composer require encore/laravel-admin "1.8.*" - 确认
config/app.php中已手动添加：Encore\Admin\Providers\AdminServiceProvider::class - 运行安装：
php artisan admin:install—— 此命令依赖数据库连通，先用php artisan tinker执行DB::connection()->getPdo()验证 - 若数据库连接名不是
mysql（比如叫legacy_db），需提前在config/admin.php里设'connection' => 'legacy_db'
admin:install 失败的三个高频原因
不是代码问题，全是环境或配置漏项：
-
SQLSTATE[HY000] [1045] Access denied：.env 里的DB_USERNAME/DB_PASSWORD错了，或者 MySQL 用户没授权对应库；不是框架 bug，是 Laravel 自身 DB 连接不通 - 执行完命令没反应、卡住不动：PHP 进程被 SELinux 或防火墙拦截，或
bootstrap/cache目录权限不够（应为775且属组www） - 装完能进登录页但点任何菜单都 404：检查
APP_URL是否带http://或https://前缀，漏写会导致前端 JS 构造 API 地址时变成相对路径
列表页 filter 和 model 顺序搞反就白写
常见写法：$grid->filter(...)->like('title') 放在 $grid->model()->where('status', 1) 后面，结果搜索失效——因为 model() 会重置整个查询构建器，把之前 filter 加的条件全清掉。
- 正确顺序：先
$grid->model()定基础范围，再$grid->filter()加用户可调条件 - 大数据量慎用
$filter->like('title')：底层是LIKE '%xxx%'，没索引支持时慢得离谱 - 多字段联合搜索别堆
like：改用$filter->custom(function ($query, $value) { $query->where('title', 'like', "%{$value}%")->orWhere('content', 'like', "%{$value}%"); })
真正麻烦的不是装不上，而是装上后 filter 不生效、资源路径错乱、密码改不了这些“半成功”状态——它们比直接报错更难定位。务必在 admin:install 前确认数据库、权限、APP_URL 三件事都对，否则后面全是无意义的调试。
