laravel-admin 2.x 已停止维护，升级会失败；应锁死1.8.x+Laravel 9或迁移到Dcat Admin 2.x。前者需精准版本对齐与配置覆盖，后者需命名空间替换、目录结构调整及基础配置补全。
别直接升级 laravel-admin 2.x —— 它已停止维护，PHP 8.2+ 和 Laravel 10/11 下大概率报 Class 'Encore\Admin\Form' not found 或路由不生效。真正能平滑过渡的路径只有两条：锁死 1.8.x + Laravel 9，或切换到 Dcat Admin 2.x。
为什么 laravel-admin 2.x 升级会失败
laravel-admin 2.x 自 2023 年起不再更新，官方 GitHub 仓库已归档。它依赖的 laravelcollective/html 在 Laravel 9+ 中被彻底移除，且未适配 PHP 8.2 的类型系统变更。你执行 composer require encore/laravel-admin "^2.0" 后，php artisan admin:install 很可能卡在服务提供者注册阶段，或抛出 Target class [Admin] does not exist。
常见错误现象包括：
-
Class 'Encore\Admin\Form' not found（核心类加载失败） - 访问
/admin返回 404，但路由列表里确实有admin/*（服务提供者未加载） -
admin:install报 SQL 错误，但实际是迁移前就因模型类缺失而中断
方案一：继续用 laravel-admin 1.8.x（推荐存量项目）
适用于已有 Laravel 9 项目、不想重构 UI 层、只需安全补丁和小功能增强的场景。关键不是“升级”，而是“精准对齐”：
- 确认当前 Laravel 版本是
9.*（非9.52.0这种带补丁号的写法，避免 Composer 解析歧义） - 执行
composer require encore/laravel-admin "1.8.*"，**不要写^1.8或1.8.19** —— 小版本间存在表单字段渲染差异 - 运行
php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider" --force强制覆盖配置，但先备份旧config/admin.php -
admin:install前务必验证数据库连通：php artisan tinker→DB::connection()->getPdo()成功才继续 - 若需自定义登录页或菜单结构，优先改
app/Admin/bootstrap.php，而非重写控制器 —— 避免升级后冲突
方案二：迁移到 Dcat Admin 2.x（推荐新项目或中长期维护）
Dcat Admin 是 laravel-admin 的活跃分支，API 兼容性高，且明确支持 Laravel 10/11 + PHP 8.2+。迁移不是“重装”，而是渐进替换：
- 先卸载：
composer remove encore/laravel-admin - 安装：
composer require dcat/laravel-admin:"2.*"，并设"minimum-stability": "dev"（临时） - 删掉
public/vendor/laravel-admin目录，再运行php artisan admin:publish --force - 全局搜索替换命名空间：
Dcat\Admin\Controllers→Dcat\Admin\Http\Controllers，Dcat\Admin\Auth→Dcat\Admin\Http\Auth - 表格代码中，把
$grid->responsive()改成$grid->showColumnSelector()；$grid->collection()改为监听Grid\Events\Fetched::class - 语言包从
resources/lang/zh-CN移到resources/lang/zh_CN，菜单翻译单独提至menus.php
容易被忽略的兼容性断点
无论选哪条路，以下三点常被跳过，导致上线后才发现问题：
-
config/admin.php里的'database' => ['connection' => '...']必须和.env中的默认连接名一致，否则admin:install会静默使用mysql而非你配置的legacy_db - 所有自定义 Form 字段（如
Form::text('title')）在 Dcat Admin 中仍可用，但底层已改用 Blade 组件 —— 若你曾手动 extend 过Encore\Admin\Form\Field，需重写为Dcat\Admin\Form\Field子类 -
admin_users表的密码字段仍是 bcrypt，但 Dcat Admin 新增了admin_settings表，首次php artisan migrate后必须进后台「系统设置」补全基础配置，否则部分插件（如富文本）无法加载
