不能直接用 composer create-project 安装 laravel-admin，需先创建 laravel 应用再通过 composer require 引入；须严格匹配 laravel 与 laravel-admin 版本（如 v2.3.x 支持 laravel 9–10，v3.0+ 仅支持 laravel 11+）；安装后必须依次执行 vendor:publish、admin:install，并检查数据库配置及目录权限。
不能直接用 composer create-project 安装 laravel-admin，它不是独立项目，而是 Laravel 的扩展包。 你得先有 Laravel 应用，再通过 composer require 引入它——否则会报错 laravel-admin requires laravel/framework ^10.0（或对应版本）这类依赖冲突，根本走不下去。
确认 Laravel 版本与 laravel-admin 兼容性
laravel-admin 每个大版本只支持特定范围的 Laravel。比如：v2.3.x 支持 Laravel 9–10，v3.0+ 只支持 Laravel 11+。装错版本轻则命令报错，重则路由不加载、页面白屏。
- 运行
php artisan --version查当前 Laravel 版本 - 查官方 GitHub 的
README.md或composer.json中"require": {"laravel/framework": "..."}字段 - 别信第三方教程写的“最新版通用”，v2 和 v3 的配置方式、路由注册、前端构建全都不一样
执行 composer require 时的关键参数
laravel-admin 安装过程会自动发布资源（config、migrations、assets），但默认不强制覆盖已存在文件。一旦你之前装过又卸载不干净，后续 php artisan admin:install 就会卡住或报 Class 'Encore\Admin\Form' not found。
- 推荐加
--with-all-dependencies避免子依赖冲突：composer require encore/laravel-admin:"2.3.*" --with-all-dependencies - 如果提示
zlib_decode(): data error，是 Composer 缓存损坏，先运行composer clear-cache - Windows 下若卡在
Installing encore/laravel-admin (2.3.0)超过 2 分钟，大概率是 asset 发布失败，关掉杀毒软件重试
安装后必须跑的三步命令（缺一不可）
只执行 composer require 不等于装完。laravel-admin 的核心逻辑藏在 service provider、配置文件和数据库迁移里，漏一步就进不了后台。
- 运行
php artisan vendor:publish --provider="Encore\Admin\ServiceProvider"—— 这步才把 config/admin.php 和资源拷过去 - 运行
php artisan admin:install—— 创建数据表、生成初始管理员、发布前端静态资源（会自动执行npm install & npm run dev，确保 Node.js 已安装） - 手动检查
config/admin.php中'database' => ['connection' => ...]是否指向你实际用的数据库连接名（默认mysql，但你可能叫admin_db）
最常被跳过的其实是权限问题：Linux/macOS 下 storage/ 和 bootstrap/cache/ 目录没写权限，admin:install 表面成功，实际 migration 失败、登录页 500；Windows 用户则容易忽略 public/vendor/laravel-admin 目录是否真实生成——它不靠软链，必须物理存在，否则 CSS/JS 全 404。
