README

把 rockys/ex-admin-ui、rockys/ex-admin-laravel、hisune/echarts-php 三个上游包 fork 合并，并集成本项目自研的 Laravel 兼容层（plugin/laravel），打包为一个 composer 包。

源码托管在 Gitee：https://gitee.com/zhong-chuanhao/ex-admin-laravel.git 命名空间沿用上游约定（ExAdmin\Ui\、ExAdmin\laravel\、Hisune\EchartsPHP\）与本包兼容层（plugin\laravel\），单包内多 PSR-4 共存。

为什么用这个包

一个命令装好整套后台：composer require zhong-chuanhao/ex-admin-laravel 即可获得 ex-admin 核心 + Laravel 适配 + 图表 + 你的兼容层，无需逐个 require rockys 各包。
可自由定制：上游源码已 fork 进本包，后续可直接修改底层（保持与上游同步由你自行维护）。
离线可用：兼容层插件源码随包发布，安装时无需联网从官网下载插件。

目录结构（包内）

ex-admin-laravel/
├── composer.json            # 单包元信息（多 PSR-4 + 两个 provider）
├── .env.example             # 配置示例
├── src-ui/                  # fork: rockys/ex-admin-ui（命名空间 ExAdmin\Ui\）
├── src-laravel/             # fork: rockys/ex-admin-laravel（命名空间 ExAdmin\laravel\）
├── src-echarts/             # fork: hisune/echarts-php（命名空间 Hisune\EchartsPHP\）
├── src/                     # 本包兼容层 plugin/laravel（命名空间 plugin\laravel\）
│   ├── ServiceProvider.php  # 兼容层服务提供者（发布插件目录、加载迁移）
│   ├── config.php           # 配置（token.key 读取 env('EX_ADMIN_TOKEN_KEY')）
│   ├── database/migrations/ # 后台表迁移
│   ├── database/seeders/    # AdminSeeder
│   └── ...                  # 控制器/模型/中间件/lang/views 等
└── resources/exadmin/       # 前端构建产物（Ant Design Vue 静态资源）

在目标 Laravel 项目中使用

1. 配置 composer 源

编辑目标项目的 composer.json，在根节点加入 repositories 并锁定稳定版（必须，否则 vcs 源的 dev 分支会被 minimum-stability 卡住，导致解析失败）：

"repositories": [
    {
        "type": "vcs",
        "url": "https://gitee.com/zhong-chuanhao/ex-admin-laravel.git"
    }
],
"minimum-stability": "stable",
"prefer-stable": true

2. 安装包

# ⚠️ Windows cmd 下 ^ 是转义符会被吞掉，必须把约束用引号包住，否则 composer 当成精确版本 1.0 报错
composer require "zhong-chuanhao/ex-admin-laravel:^1.0"

# 或直接锁具体版本（最稳，推荐）
composer require "zhong-chuanhao/ex-admin-laravel:1.0.15"

PowerShell / bash 下 ^1.0 不用加引号；只有 Windows cmd 必须加引号。

Laravel 会自动发现并注册两个服务提供者（无需手动改 config/app.php）：

plugin\laravel\ServiceProvider（兼容层，先）
ExAdmin\laravel\AdminServiceProvider（上游 Laravel 适配，后）

3. 配置数据库（关键，别漏）

Laravel 13 新建项目默认 DB_CONNECTION=sqlite（.env 里 DB_DATABASE=laravel3 是 sqlite 文件路径），必须改成 MySQL，否则 admin:install 在建表时抛 SQLiteDatabaseDoesNotExistException，流程中断并误报"请删除 laravel 目录"警告。

编辑目标项目 .env：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel2
DB_USERNAME=root
DB_PASSWORD=root

提前在 MySQL 建好空库 laravel2（字符集 utf8mb4）。

然后清配置缓存让 .env 生效：

php artisan config:clear

4. 安装后台（建表 + 种子 + 软链）

php artisan admin:install

该命令已内置离线流程，自动完成：发布前端资源 → public/exadmin、发布兼容层插件目录 → plugin/laravel、加载插件、执行迁移（建 admin_users 等表）、填充初始管理员、建立 storage:link。 不要加 --force（v1.0.15 起默认强制加载已发布目录，不再需要 --force；旧版本不带 --force 会卡在"请删除 laravel 目录"警告）。看到 [OK] install success 即成功。

可选：自定义管理员账号密码

php artisan admin:install --username=admin --password=yourpassword --force

5. 访问后台

默认路由前缀 admin，启动服务后访问 http://你的域名/admin：

php artisan serve
# 浏览器打开 http://127.0.0.1:8000/admin

默认管理员凭据见 plugin/laravel/database/seeders/AdminSeeder.php（用户名 admin / 密码 admin，如不一致以该文件 run() 为准）。

6. 常见问题排查

现象	原因	解决
`requires ... 1.0 (exact version match)`	cmd 下 `^1.0` 被吞成 `1.0`	约束加引号 `"...:^1.0"` 或锁版本 `:1.0.15`
`admin:install` 报"请删除插件目录下的laravel目录"且无表	`.env` 仍是 sqlite 默认，建表异常中断流程	改 `.env` 为 mysql + `php artisan config:clear` 后重跑
`Some tags were ignored because of a version mismatch`	包的 composer.json 写了手写 `version` 字段（已修复，v1.0.11+ 无此问题）	升级到最新 tag
`Class "App\Exceptions\Handler" not found`	Laravel 13 移除该类（已修复 v1.0.8）	升级到最新 tag
Symfony `getContentType()` undefined	Laravel 13 Symfony 8 移除该方法（已修复 v1.0.9）	升级到最新 tag

依赖说明

本包已合并以下上游依赖，目标项目无需再单独 require：

rockys/ex-admin-ui（核心 UI / 插件机制）
rockys/ex-admin-laravel（Laravel 适配）
hisune/echarts-php（图表）

其余运行时依赖（symfony 系列、phpspreadsheet、guzzle、qiniu/oss 云存储、illuminate/support）由 composer 自动安装。

发布本包到 Packagist（维护者操作，源码托管于 Gitee）

将本目录推送到 Gitee 公开仓库 https://gitee.com/zhong-chuanhao/ex-admin-laravel.git。
打版本 tag 并推送：
```
git tag v1.0.0
git push origin v1.0.0
```
登录 https://packagist.org/packages/submit ，填入上面的 Gitee 仓库 URL 即可（Packagist 支持任意公开 Git 源）。
Gitee 无官方 Packagist webhook，需在 Packagist 对应包页面点 Update 手动刷新，或在 Gitee 仓库「管理 → WebHooks」添加指向 https://packagist.org/api/github?username=<packagist用户名> 的 POST 钩子。

维护者改包 / 发版完整流程请看同目录 UPDATE.md（含版本历史、修改点对照表、发布检查清单）。

注意事项

上游源码已 fork 进 src-ui/、src-laravel/、src-echarts/，如需同步上游更新，请手动 merge 上游仓库。
token.key 默认读取 env('EX_ADMIN_TOKEN_KEY')，请务必替换为自己的随机密钥。
本包兼容层 plugin/laravel 的 namespace 保持原样（plugin\laravel\），便于与现有 Laravel 项目配置一致。
禁止在 composer.json 手写 version 字段，版本号只通过 git tag 声明（否则 Composer 报 version mismatch 警告）。

zhong-chuanhao / ex-admin-laravel

Maintainers

Package info

Statistics

Security