laravel-admin安装前需确保laravel项目正常运行，重点检查.env配置、php≥8.1及扩展启用、目录权限设为755且属主www，再通过宝塔终端执行composer require encore/laravel-admin "2.3.*"安装。
宝塔里装 laravel-admin 前，先确认 Laravel 能跑通
laravel-admin 是个 Laravel 扩展包，不是独立应用。它依赖 Laravel 项目已能正常响应请求 —— 如果你连 php artisan serve 都报错，或宝塔里访问首页就 500，别急着装 admin，先解决基础环境问题。
重点检查三件事：
-
APP_ENV=production和APP_DEBUG=false必须写在服务器上的.env里（不是本地的） - PHP 版本 ≥ 8.1，且已启用
openssl、pdo、mbstring、tokenizer、xml、ctype、json、zip扩展（宝塔「PHP 管理」→「安装扩展」里勾选） -
storage/和bootstrap/cache/目录权限设为 755，并属主为www（宝塔文件管理器右键 → 权限 → 勾选“同时修改子目录和文件”）
用 composer require 安装 encore/laravel-admin
别用 git clone 或手动复制 vendor，也别在本地装完再上传 —— 宝塔终端里直接进项目根目录执行命令最稳。
操作步骤：
- 通过宝塔「终端」进入项目目录：
cd /www/wwwroot/your-site.com - 执行安装命令：
composer require encore/laravel-admin "2.3.*"（推荐锁版本，避免 Laravel 11+ 下新版不兼容） - 如果提示
composer: command not found，说明宝塔没装 Composer，先运行curl -sS https://getcomposer.org/installer | php && mv composer.phar /usr/local/bin/composer - 若卡在
Loading composer repositories，加国内镜像：composer config -g repo.packagist composer https://packagist.phpcomposer.com
发布资源 + 运行 install 命令时的典型报错
php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider" 和 php artisan admin:install 这两步最容易失败，常见现象和解法如下：
- 报错
SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long→ 在app/Providers/AppServiceProvider.php的boot()方法里加：Schema::defaultStringLength(191);，并use Illuminate\Support\Facades\Schema; - 报错
Class 'Encore\Admin\Encore' not found→ 检查是否漏了composer dump-autoload，或config/app.php里没注册服务提供者（新版 Laravel 通常自动发现，但低版本需手动加） - 执行
admin:install卡住或无反应 → 先清缓存：php artisan config:clear && php artisan cache:clear，再重试；如仍失败，换用php artisan admin:install --force - 安装后访问
/admin显示 404 → 确认 Nginx 伪静态已选「Laravel 5」，且网站「运行目录」设为/public（不是项目根目录）
登录页打不开、CSS/JS 加载失败、中文不生效
装完只是第一步，前端资源和语言配置常被忽略：
- 登录页空白或样式错乱 → 进入项目根目录执行：
php artisan vendor:publish --tag=laravel-admin-assets，再运行php artisan admin:publish（部分版本需要） - 默认是英文界面 → 修改
config/admin.php中的'locale' => 'zh-CN'，并确保系统已安装中文语言包（php artisan lang:publish zh-CN不是必须，但可补全） - 登录后跳转到
/admin/dashboard报 403 或白屏 → 检查app/Http/Middleware/VerifyCsrfToken.php是否把/admin/*加进了$except数组（生产环境建议保留 CSRF，优先排查 session 配置） - 图片上传失败或预览 404 → 运行
php artisan storage:link，并确认宝塔里public/storage是软链接，指向../storage/app/public
真正麻烦的不是装不上，而是装完后路由能进、页面渲染一半、控制台报一堆 404 —— 这类问题八成出在资源路径或 Nginx 配置上，别硬刷，先看浏览器 Network 面板里哪个 URL 返回了 404，再反向定位是链接没生成、软链断了，还是伪静态规则漏了 ^/admin/ 开头的请求。
