10分钟搭建管理后台：laravel-admin实战入门

每次接手新项目，业务逻辑还没写完，管理后台的需求就排上了日程------用户列表、内容审核、数据统计、权限配置，一个都不能少。

手动从零写后台的体验大家都懂：建控制器、写路由、画 Blade 模板、配分页、做表单验证、搞增删改查......整套流程走下来，两天时间就没了，而且每个模块的 UI 风格还参差不齐。

laravel-admin 正是为了解决这个问题而生。这个拥有 1.1 万星的开源项目，让你只需数据模型就位，几乎不用写前端代码，就能生成带分页、搜索、导出、权限管理的 CRUD 后台。

本文带你从零开始，亲手搭建一个商品管理后台。跟着操作，你将得到一个可直接投入生产使用的管理系统。

环境准备

开始前确认环境满足要求：

PHP >= 7.0（推荐 PHP 8.x）
Laravel 5.5 或以上版本（推荐 Laravel 10/11）
Fileinfo PHP 扩展（大部分发行版默认已启用）
已安装 Composer 和 MySQL/SQLite

还没有 Laravel 项目的，先创建一个：

bash 复制代码

composer create-project --prefer-dist laravel/laravel admin-demo

创建完成后，检查 .env 文件中的数据库连接配置是否正确，laravel-admin 会在数据库中创建管理权限表。

三步完成安装

第一步：安装依赖

进入 Laravel 项目目录，执行：

bash 复制代码

composer require encore/laravel-admin

这一步拉取 laravel-admin 及其依赖。它底层基于 AdminLTE 后台模板，但封装成了 Laravel 友好的方式，用 PHP 代码就能定义后台页面。

第二步：发布资源文件

bash 复制代码

php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider"

运行后，项目根目录会生成 config/admin.php。这是核心配置入口，可修改安装目录（默认 admin）、数据库连接、后台标题等参数，一般保持默认即可。

第三步：执行安装迁移

bash 复制代码

php artisan admin:install

这条命令完成两件事：

在数据库创建 5 张管理后台表（admin_users、admin_roles、admin_permissions 等）
插入默认超级管理员账号，用户名和密码都是 admin

访问 http://localhost:8000/admin/，用 admin/admin 登录，后台主界面就呈现在眼前了。

这三步对应 Laravel 包的标准安装模式：安装 PHP 依赖 → 发布配置文件和资源 → 执行数据库迁移。熟悉这个模式后，安装任何 Laravel 第三方包都不会迷路。

实战：搭建商品管理后台

后台框架就绪后，我们进入真实业务场景------商品管理，包含增删改查、分类筛选和图片上传功能。

1. 创建数据表和模型

bash 复制代码

php artisan make:model Product -m

-m 参数同时生成迁移文件。打开 database/migrations/xxx_create_products_table.php，写入字段定义：

php 复制代码

public function up()
{
    Schema::create('products', function (Blueprint $table) {
        $table->id();
        $table->string('name', 100)->comment('商品名称');
        $table->decimal('price', 10, 2)->default(0)->comment('价格');
        $table->integer('stock')->default(0)->comment('库存');
        $table->tinyInteger('status')->default(1)->comment('状态：1上架 0下架');
        $table->string('image')->nullable()->comment('商品图片');
        $table->timestamps();
    });
}

执行迁移：

bash 复制代码

php artisan migrate

2. 生成后台控制器

bash 复制代码

php artisan admin:make ProductController --model=App\\Models\\Product

这是 laravel-admin 的核心能力------根据 Eloquent Model 自动生成后台控制器骨架。打开 app/Admin/Controllers/ProductController.php，核心代码如下：

php 复制代码

use Encore\Admin\Form;
use Encore\Admin\Grid;
use Encore\Admin\Show;

class ProductController extends Controller
{
    public function grid()
    {
        $grid = new Grid(new Product());

        $grid->column('id', 'ID')->sortable();
        $grid->column('name', '商品名称');
        $grid->column('price', '价格')->sortable();
        $grid->column('stock', '库存');
        $grid->column('status', '状态')->using([0 => '下架', 1 => '上架'])->label([
            0 => 'danger', 1 => 'success'
        ]);
        $grid->column('image', '图片')->image('', 50, 50);
        $grid->column('created_at', '创建时间')->sortable();

        return $grid;
    }

    protected function form()
    {
        $form = new Form(new Product());

        $form->text('name', '商品名称')->rules('required|max:100');
        $form->decimal('price', '价格')->default(0);
        $form->number('stock', '库存')->default(0);
        $form->switch('status', '状态')->default(1);
        $form->image('image', '商品图片');

        return $form;
    }
}

grid() 定义列表页展示的列，form() 定义新增/编辑页的表单元素。无需手写 HTML/JS，laravel-admin 自动渲染成美观的表格和表单。

3. 注册路由

打开 app/Admin/routes.php，添加：

php 复制代码

$router->resource('products', ProductController::class);

4. 添加菜单入口

登录后台 → 左侧菜单「Admin」→「Menu」→ 新建菜单项：

标题：商品管理
URI：/products
图标：选 fa-shopping-cart 等合适的图标

保存后刷新页面，左侧出现「商品管理」菜单。点击进入，即可对商品进行增删改查操作。

踩坑提醒

Q1：访问 /admin 报 500 错误？

确认 storage 和 bootstrap/cache 目录有写入权限：

bash 复制代码

chmod -R 775 storage bootstrap/cache

同时检查 config/admin.php 中的 route.prefix 是否与访问路径一致。

Q2：上传图片报 "disk not configured"？

确保 .env 中配置了 FILESYSTEM_DISK=public，并执行过 php artisan storage:link 创建符号链接。

Q3：中文显示乱码？

数据库和数据表字符集需要是 utf8mb4：

sql 复制代码

CREATE DATABASE demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Q4：PHP 版本太高报依赖冲突？

老版本对 PHP 8.2+ 兼容性欠佳，可指定版本：

bash 复制代码

composer require encore/laravel-admin:"^1.8"

Q5：表单字段太多页面卡顿？

用 grid->paginate(20) 限制每页条数，或给常查询的字段加数据库索引。

总结

今天的操作路径清晰明了：

安装（3 条命令）→ 建表+模型 → 生成后台控制器（1 条命令）→ 配置路由和菜单 → 完整可用

laravel-admin 的核心价值在于：将后台开发中重复、机械的部分（列表、分页、搜索、表单、权限）抽象为配置式 API，让你专注业务逻辑本身。赶交付、做内部工具、带新手团队时，它都是优秀的生产力工具。

后续可探索方向：

权限管理：创建不同角色（运营、审核员、管理员），给菜单和数据加行级权限控制
扩展包：官方提供媒体管理器、定时任务、Redis 管理、富文本编辑器等插件
自定义页面 ：用 Content 和 Row/Column 组件搭建数据看板
API 后台：配合 Laravel Sanctum，改造为前后端分离架构