做后台管理系统这事儿劝退过不少人。业务需求一天三变今天加列表明天加导出后天又要多一层角色权限每一件都是“看着不难、拆开全是一堆细节”的活。EasyAdmin 是一款基于 ThinkPHP6 和 Layui 快速开发的后台管理系统我第一次接触的时候最大的感受就是它把后台项目里最磨人的基础工程提前做好了。你要做的只是在上面补齐自己的业务模块。这套系统适合谁如果你经常做企业后台、外包项目、内部运营系统或者你刚学完 ThinkPHP6 想找一个能玩明白项目那它非常对路。它解决的核心问题不是“代码写不出来”而是“重复造轮子”管理员、角色、菜单、权限、日志、系统配置、附件上传这些后台项目躲不掉的东西全都给你整理成了一套可管理的功能模块。下面我就从技术选型、功能结构、实操搭建和常见坑位四个方面把整条路完整盘一遍。1. 技术选型为什么是 ThinkPHP6 Layui很多人在后台项目选型时第一个念头是“前后端分离才高级”我不这么看。后台管理系统是典型的“内部效率工具”优先级是交付速度、维护成本、稳定性和开发者的舒适度而不是极致的交互体验。EasyAdmin 选择 ThinkPHP6 加 Layui本质上是选中了一条“低心智负担、高产出效率”的技术路线。1.1 ThinkPHP6 对业务开发真正有用的几个点ThinkPHP6 是 PHP 圈子里很成熟的一个 MVC 框架官方文档齐全社区里踩坑记录也多。它的多应用模式对后台系统特别友好你可以把后台和管理端拆成admin和index两个应用也可以额外建一个api应用处理小程序或手机端接口。这一点比老式单应用写法清爽得多。框架内置的 ORM 模型、验证器、中间件、依赖注入容器已经覆盖了日常开发八成以上的需求。举个例子新增文章时我要校验 title 是否必填、cover 是否 URL 安全不需要自己在控制器里写一堆 if-else只要建一个验证器类?php namespace app\admin\validate; use think\Validate; class ArticleValidate extends Validate { protected $rule [ title require|max:50, cover require, status in:0,1, ]; protected $message [ title.require 标题不能为空, title.max 标题最多50个字符, cover.require 封面图不能为空, ]; }然后在控制器里调用$validate-check($data)即可。这套机制对快速交付来说足够用而且代码位置固定后期接手的人很容易找。再加上 Composer 生态引入第三方库也就是一条命令的事。1.2 Layui 在后台场景里的真实手感Layui 曾被一些人吐槽“不够现代化”但如果真的用它在后台管理系统里写几个页面你会承认它很顺手。它不用 Node、不用 Webpack、不用配置一堆开发服务器直接把静态文件放到 public 目录下页面里通过 link 和 script 引进来就能跑。尤其是 Layui 的表格、表单、弹层、日期选择器后台管理页面的高频组件基本全覆盖。比如做一个列表页只需要渲染一个 tabletable.render({ elem: #articleTable, url: /admin/article/lists, page: true, cols: [[ { field: id, title: ID, width: 80 }, { field: title, title: 标题, minWidth: 200 }, { field: status, title: 状态, width: 100, templet: function (d) { return d.status 1 ? 显示 : 隐藏; } } ]] });前端不需要构建后端返回一个符合格式的 JSON 就行。对于大部分时候只有一两个后端开发者的小团队来说这能省掉大量联调时间。EasyAdmin 在这个基础上还封装了一些通用方法列表接口的返回格式基本固定为code / msg / count / data四要素前端 table.render 拿到就能直接渲染。1.3 为什么这套组合比前后端分离更适合大多数后台项目前后端分离本身没错但要看场景。企业内部后台往往没有非常高的并发诉求也不需要多端复用同一套 API这时候硬上 Vue 或 React反而要处理跨域、Token 刷新、接口文档、前端部署、权限路由这些额外工作。最后一算项目还没写业务光脚手架就折腾了大半时间。EasyAdmin 的做法是“服务端渲染 Layui 组件”页面由一个控制器方法直接输出另一个方法专门返回 JSON 给表格和弹窗用。权限校验直接在服务端中间件里完成不需要前端偷偷藏路由。如果以后真要开放小程序接口单独开一个api应用就行后台管理这半边不需要推翻重写。这套“按需拆分”的思路比一开始就设计成前后端分离务实得多。2. EasyAdmin 的功能地图与目录结构了解一套框架不能光看它能不能跑而是要看它的模块边界在哪里、目录约定长什么样、权限体系如何串起来。这样你做二次开发的时候才知道什么东西该改哪里什么东西不能乱动。2.1 开箱即用的核心模块拆解EasyAdmin 默认提供的基础模块大致包括以下这些覆盖后台系统最常见的通用需求后台管理员管理管理登录后台的账号分配状态、角色支持重置密码。角色管理创建角色给角色分配可访问的菜单和操作节点。菜单规则管理维护左侧菜单和权限节点可以拖拽排序、设置为隐藏。系统配置后台界面直接读写配置项比如网站名称、上传设置、开关状态。操作日志记录登录、增删改等关键行为方便追溯问题。附件管理统一管理上传的图片和文件记录附件来源与所属业务。个人中心修改自己的资料和密码。这些模块如果自己写每一个都不难但合起来工作量相当可观。EasyAdmin 的价值就在把这些东西变成一套标准化的起点你不需要每次新建项目都把管理员表和角色表重新设计一遍。2.2 目录结构与代码组织逻辑我手头这套 EasyAdmin 的目录结构大致是下面的样子和其它 ThinkPHP6 项目相比最大的特点是应用层按admin独立切分├── app │ ├── admin │ │ ├── controller # 后台控制器 │ │ ├── model # 模型 │ │ ├── validate # 验证器 │ │ └── view # 模板文件 │ └── api # 可选接口应用 ├── config │ ├── admin.php # 后台相关配置 │ └── app.php # 多应用配置 ├── public │ ├── static # Layui 等前端静态资源 │ └── storage # 上传文件目录 ├── route │ └── app.php # 路由规则 ├── runtime # 运行时缓存 └── .env # 数据库等环境配置理解这个目录的关键在于“控制器对应模板”。app/admin/controller/Article.php里的index()方法默认对应app/admin/view/article/index.html不需要手写路由转发规则ThinkPHP6 的自动路由已经处理好了。这种约定式组织结构新成员接手项目时能很快定位到对应页面和逻辑。2.3 权限系统是怎么串起来的EasyAdmin 的权限模型是经典的“用户-角色-节点”一个管理员属于一个或多个角色角色绑定一组权限节点权限节点对应后台的菜单和操作按钮。比如 A 角色只分配了“文章列表”和“文章编辑”两个节点那么 A 账号访问“文章删除”对应的 URL 时就会被服务端拦截。这个流程做成文字很简单落到代码里就是在后台应用的公共控制器里加一个鉴权逻辑protected function authorize() { // 获取当前登录管理员对应的角色节点集合 $nodes $this-getUserNodes($this-uid); // 当前请求的 URL 对应节点规则 $current strtolower(request()-controller()) . / . strtolower(request()-action()); if (!in_array($current, $nodes, true)) { throw new \Exception(抱歉您没有该操作权限); } }实际项目中 EasyAdmin 还有更多细节比如 URL 大小写转换、排除公共方法、超级管理员直接放行等。但核心思路就是上面这段。这也是很多新手最容易忽略的地方建了菜单却忘了给角色勾选节点结果按钮能看见、点击却永远“无权限”。3. 实操从安装到快速生成一个“文章管理”模块光看架构不过瘾我们来完整跑一遍。下面的操作以本地开发环境为例目标是从空系统开始手工做一个标准的“文章管理”模块包括列表、新增、编辑、删除和权限挂载。3.1 环境准备与安装步骤推荐环境版本是 PHP 7.4 或 PHP 8.0、MySQL 5.7 以上、Composer 2.x、Nginx 或 Apache。注意 ThinkPHP6 要求 PHP 版本不低于 7.2.5但我在生产环境踩过一些扩展兼容问题所以建议至少用 7.4。安装分五步把 EasyAdmin 源码解压到项目目录或者用 Git 拉取到 Web 根目录。执行composer install安装依赖。复制.example.env为.env填入数据库连接信息。导入项目根目录下提供的 SQL 文件初始化数据表。配置 Web 服务器把站点根目录指向public访问后台域名。如果使用 Nginx伪静态规则要写成这样否则路由会全部 404location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php?s$1 last; } }Apache 环境下则放.htaccess内容大致是IfModule mod_rewrite.c Options FollowSymlinks -Multiviews RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ index.php?s$1 [QSA,PT,L] /IfModule安装完成后访问后台地址用初始化账号登录默认密码一般都在 README 里登录后第一件事是改密码。3.2 建表与生成模型新建一张文章表字段不需要太复杂够演示就行CREATE TABLE article ( id int(11) unsigned NOT NULL AUTO_INCREMENT, title varchar(100) NOT NULL DEFAULT , cover varchar(255) NOT NULL DEFAULT , content text, status tinyint(1) NOT NULL DEFAULT 1, create_time int(11) NOT NULL DEFAULT 0, update_time int(11) NOT NULL DEFAULT 0, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;然后使用 ThinkPHP6 命令行生成模型和控制器php think make:model admin/Article php think make:controller admin/Article --plain--plain参数表示生成空控制器不套用默认的增删改查模板。因为 EasyAdmin 已经把公共逻辑放在了基础控制器里我们自己的控制器只需要继承那个基类。如果框架版本的命令参数名称有差异可以用php think help查看一下这一步不影响整体流程。3.3 控制器和列表接口怎么写文章管理列表页需要两个动作一个渲染模板一个返回表格数据。控制器代码如下?php namespace app\admin\controller; use app\admin\model\Article; use app\admin\validate\ArticleValidate; use think\facade\View; class Article extends Base { public function index() { return View::fetch(); } public function lists() { $keyword request()-get(keyword, ); $status request()-get(status, ); $where []; if ($keyword ! ) { $where[] [title, like, % . $keyword . %]; } if ($status ! ) { $where[] [status, , $status]; } $list Article::where($where) -paginate([...]) -toArray(); return json([ code 0, msg , count $list[total], data $list[data], ]); } }这里最核心的一点是返回格式必须兼容 Layui table。code固定为 0 表示成功count放总记录数data放当前页数据。如果后端没按这个格式返回前端表格就会一直转圈或者显示“未获取到数据”。3.4 视图模板和表单页的快速拼装列表页app/admin/view/article/index.html里主要写一个table容器和一段渲染脚本table idarticleTable lay-filterarticleTable/table script layui.use([table, form], function () { var table layui.table; table.render({ elem: #articleTable, url: /admin/article/lists, page: true, limit: 15, cols: [[ { field: id, title: ID, width: 80, sort: true }, { field: title, title: 标题, minWidth: 200 }, { field: cover, title: 封面, width: 120, templet: function (d) { return img src d.cover stylewidth:40px;height:40px;object-fit:cover;; } }, { field: status, title: 状态, width: 100, templet: function (d) { return d.status 1 ? span classlayui-badge layui-bg-green显示/span : span classlayui-badge layui-bg-gray隐藏/span; } }, { title: 操作, width: 160, toolbar: #articleToolbar } ]] }); }); /script新增、编辑页面直接把表单拉出来提交时用 layui form 监听再把表单值 POST 给保存接口。需要注意的是表单里如果有开关或下拉框要用form.render()重新渲染一次否则新加载的动态选项不会生效。3.5 把模块挂到菜单和权限树里模块代码写完不算完还得让它出现在后台菜单里并分配权限。登录后台后到“菜单管理”新增顶级菜单或子菜单填写菜单名称和访问地址。地址一般填admin/article/index这种规则路径注意不要填成伪静态 URL。如果图省事要手工插数据库参考下面这种格式INSERT INTO system_menu (title, url, pid, sort, status) VALUES (文章管理, admin/article/index, 5, 1, 1);插入后还要编辑对应的角色给“文章管理”节点打勾。每次新增控制器方法比如article/delete、article/edit也需要把对应节点补进菜单或权限规则表否则这个动作默认不在授权范围内。实际开发中很多人会忘记这一步结果就是按钮点击报“无权限”。4. 二次开发的常见问题与排查实录EasyAdmin 整体好用但不代表没有坑。以下问题我基本都踩过或帮别人排查过整理成一套排查思路能省不少 debug 时间。4.1 列表接口返回了数据表格却一直是空白这是最常见的问题而且十次里有八次是返回格式不对。Layui table 对 JSON 的字段要求是严格的必须包含code、msg、count、data四个字段。很多新手直接把模型查询结果返回出来了类似[{ id: 1, title: 测试文章 }]前端拿不到data和count自然渲染不出来。还有的情况是控制器里先输出了调试信息比如echo 123;导致返回的不是纯 JSON表格也会失败。排查方法很简单浏览器打开列表接口地址看返回内容是否合法再对照 table.render 里的 col 字段是否和后端字段一致。4.2 权限控制形同虚设或者全部提示无权限权限问题分两个极端。一种是所有请求都能随便访问说明权限鉴权没有生效优先检查后台应用的公共控制器里有没有调用 authorize 相关方法另一种是明明给角色打了勾但还是提示无权限这时候重点排查 URL 规则大小写和节点标识是否一致。我在实际项目里遇到过非常隐蔽的问题菜单权限节点里存的是Admin/Article/index而框架里的request()-controller()返回的是经过小写转换后的article两边大小写不一致导致匹配不上。后来统一在节点规则里全部使用全小写加斜杠格式问题才消失。所以维护节点时一定要定好规范。4.3 上传文件失败或图片回显路径不对上传问题通常集中在两个地方PHP 配置和网站根目录。先看php.ini里的upload_max_filesize、post_max_size是否够大再看上传目录是否有写入权限。EasyAdmin 这类系统一般把上传文件放在public/storage下只要 Web 服务器配置了根目录为public就能通过http://你的域名/storage/xxx.png访问。如果你用 Nginx根目录指错了指向public的上一层所有上传图片都会 403。局域网二次开发时还容易忽略跨域问题后台页面通过 IP 访问图片回显地址却拼接成了localhost需要检查服务器配置里request()-domain()的取值来源。4.4 常见问题速查表现象可能原因处理办法列表页一直显示加载中返回 JSON 格式不正确或接口报错直接浏览器访问接口检查返回内容确保包含 code/count/data新增保存提示成功但列表没有数据模型字段过滤或create_time未写入检查表字段是否有自动写入时间模型是否设置autoWriteTimestamp删除按钮无权限权限节点没添加或者角色未勾选到菜单管理补一个删除节点并给对应角色授权修改密码后登录不了密码加密方式与验证逻辑不一致确认使用框架统一的密码加密方法不要手动改库模板修改后前端不生效浏览器缓存或模板缓存强制刷新浏览器必要时清理runtime目录上传大文件失败PHP 上传限制太小调整upload_max_filesize和post_max_size重启服务页面布局乱掉的现象也遇到过几次基本是 Layui 版本号冲突。EasyAdmin 自带的静态资源用了固定版本后来我为了引入第三方组件又加载了一个新版本 Layui导致样式错乱。这个问题排查了半天最后把多余引入删掉就好了。后台项目里一定要保证全站只有一套 Layui 资源不要混用版本。5. 快速开发后台什么该省什么不该省回到 EasyAdmin 这套东西我觉得它最值得学习的不是代码而是“分层舍弃”的思路。业务代码可以快速堆但权限、日志、上传这些安全底线不能省页面交互可以朴素但列表查询和表单校验必须稳。它把所有后台系统的公共部分沉淀成了默认规则新业务只需要往里面填内容这种“约定优于配置”的理念比某个具体功能更值钱。我个人的习惯是拿到这类快速开发框架之后先别急着写业务而是花半天把菜单、角色、权限、日志、配置这些模块全部点一遍搞明白每个表之间什么关系。等真正需要二次开发的时候心里就有了一张完整地图。后续再做新模块我基本就是建表、写模型、写控制器、套模板、挂菜单这五个步骤一个中型模块一上午就能交付。如果你也经常被后台需求淹没不妨用这样的框架把基础工程沉淀下来把时间留给真正有业务价值的逻辑上。
