laravel-admin 1.8.x 是 laravel 9 唯一兼容且稳妥的版本，安装需指定版本、正确注册服务提供者、确保数据库连通与权限配置，并注意资源发布、路由规则及 grid 中 filter 与 model 的调用顺序。
laravel-admin 1.8.x 是 Laravel 9 的唯一稳妥选择
别装 laravel-admin 2.x 或最新 dev 分支——它已停止维护，与 Laravel 9 不兼容，运行时大概率报 Class 'Encore\Admin\Form' not found 或路由完全不加载。真实项目里能跑通的组合只有 laravel-admin 1.8.* + Laravel 9.*。
实操步骤：
- 新建 Laravel 9 项目：
composer create-project laravel/laravel myapp "9.*" - 进项目目录，指定版本安装：
composer require encore/laravel-admin "1.8.*" - 检查
config/app.php中是否已注册Encore\Admin\Providers\AdminServiceProvider::class；如果没出现，手动加进去（别放在if (app()->isLocal())条件块里）
admin:install 失败？先验证数据库连通性
php artisan admin:install 命令本质是建表 + 插入默认管理员，它完全依赖 Laravel 自身的数据库配置。卡住或报 SQLSTATE[HY000] [1045] Access denied，99% 是 .env 里 DB_* 配置错，或 MySQL 用户没权限。
排查顺序：
- 先执行
php artisan tinker，输入DB::connection()->getPdo()—— 能返回 PDO 实例才算通 - 确认
DB_DATABASE对应的库已手动创建（laravel-admin不会自动建库） - 若你改过默认数据库连接名（比如叫
legacy_db），必须在config/admin.php里显式设'database' => ['connection' => 'legacy_db'] - 遇到
Specified key was too long错误：在app/Providers/AppServiceProvider.php的boot()方法里加一行Schema::defaultStringLength(191);，删掉已建的表再重试
登录后空白/样式错乱？重点查 public/vendor 和 APP_URL
laravel-admin 的前端资源（JS/CSS）默认发布到 public/vendor/laravel-admin。如果页面空白、按钮不渲染、图标变方块，不是框架坏了，而是资源没加载成功。
关键检查点：
- 运行
php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider"后，确认public/vendor/laravel-admin目录存在且非空 - 浏览器打开开发者工具，看 Network 标签页里是否有 404 的 JS/CSS 请求；如果有，大概率是
APP_URL配置错误（比如少写了http://或结尾多了斜杠） - Nginx/Apache 必须指向
public/目录；Apache 还需开启mod_rewrite，Nginx 需配伪静态规则：location / { try_files $uri $uri//index.php?$query_string; }
自定义 Grid 列表时 filter 和 model 的调用顺序不能颠倒
写商品列表页加搜索功能时，$grid->filter() 和 $grid->model()->where() 的顺序直接影响结果。如果先写 filter 再写 model()->where()，过滤器会失效——因为 model() 会重建查询构建器，把之前 filter 添加的条件全清掉。
正确写法：
- 所有数据范围限制（如只查
status = 1）必须写在$grid->model()->where('status', 1)里 - 且这行必须放在
$grid->filter(...)之后 -
$filter->like('title')底层生成LIKE '%xxx%'，大数据量时注意给字段加前缀索引；如需 title 或 content 同时匹配，别堆多个like，改用$filter->custom(function ($query) { $query->where('title', 'like', "%{$this->input}%")->orWhere('content', 'like', "%{$this->input}%"); })
真正容易被忽略的是 admin:install 后的权限初始化——它只建表、插一条 admin/admin 用户，但不会自动分配角色和权限。进后台后第一件事，得去「权限管理」里把「所有权限」分配给「管理员角色」，否则点任何菜单都 403。
