PHPackages                             businessg/laravel-excel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF &amp; Document Generation](/categories/documents)
4. /
5. businessg/laravel-excel

ActiveLibrary[PDF &amp; Document Generation](/categories/documents)

businessg/laravel-excel
=======================

Excel 同步/异步智能配置导入导出组件，为 Laravel 框架提供强大的 Excel 处理能力,支持无限极列头配置,页码、列头、列样式配置。

v1.0.1-beta.1(3d ago)06↓100%MITPHPPHP &gt;=8.1CI failing

Since Mar 9Pushed todayCompare

[ Source](https://github.com/businessg/laravel-excel)[ Packagist](https://packagist.org/packages/businessg/laravel-excel)[ RSS](/packages/businessg-laravel-excel/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (18)Versions (4)Used By (0)

businessg/laravel-excel
=======================

[](#businessglaravel-excel)

Laravel 框架的 Excel 同步/异步导入导出组件。基于 [businessg/base-excel](https://github.com/businessg/base-excel) 核心库，提供开箱即用的 HTTP 接口自动注册、CLI 命令、进度追踪、消息推送、数据库日志。

---

目录
--

[](#目录)

- [1. 环境要求与安装](#1-%E7%8E%AF%E5%A2%83%E8%A6%81%E6%B1%82%E4%B8%8E%E5%AE%89%E8%A3%85)
- [2. 配置参考](#2-%E9%85%8D%E7%BD%AE%E5%8F%82%E8%80%83)
    - [2.1 excel.php — 组件核心配置](#21-excelphp--%E7%BB%84%E4%BB%B6%E6%A0%B8%E5%BF%83%E9%85%8D%E7%BD%AE)
    - [2.2 excel\_business.php — 业务配置](#22-excel_businessphp--%E4%B8%9A%E5%8A%A1%E9%85%8D%E7%BD%AE)
        - [导出配置项说明](#%E5%AF%BC%E5%87%BA%E9%85%8D%E7%BD%AE%E9%A1%B9%E8%AF%B4%E6%98%8E)
        - [导入配置项说明](#%E5%AF%BC%E5%85%A5%E9%85%8D%E7%BD%AE%E9%A1%B9%E8%AF%B4%E6%98%8E)
- [3. API 接口参考](#3-api-%E6%8E%A5%E5%8F%A3%E5%8F%82%E8%80%83)
- [4. 实现一个「导出」完整流程](#4-%E5%AE%9E%E7%8E%B0%E4%B8%80%E4%B8%AA%E5%AF%BC%E5%87%BA%E5%AE%8C%E6%95%B4%E6%B5%81%E7%A8%8B)
- [5. 实现一个「导入」完整流程](#5-%E5%AE%9E%E7%8E%B0%E4%B8%80%E4%B8%AA%E5%AF%BC%E5%85%A5%E5%AE%8C%E6%95%B4%E6%B5%81%E7%A8%8B)
- [6. 异步导入导出与队列配置](#6-%E5%BC%82%E6%AD%A5%E5%AF%BC%E5%85%A5%E5%AF%BC%E5%87%BA%E4%B8%8E%E9%98%9F%E5%88%97%E9%85%8D%E7%BD%AE)
- [7. 配置类字段与样式参考](#7-%E9%85%8D%E7%BD%AE%E7%B1%BB%E5%AD%97%E6%AE%B5%E4%B8%8E%E6%A0%B7%E5%BC%8F%E5%8F%82%E8%80%83)
    - [7.1 ExportConfig — 导出配置类](#71-exportconfig--%E5%AF%BC%E5%87%BA%E9%85%8D%E7%BD%AE%E7%B1%BB)
    - [7.2 导出 Sheet](#72-%E5%AF%BC%E5%87%BA-sheet)
    - [7.3 导出 Column](#73-%E5%AF%BC%E5%87%BA-column)
    - [7.4 Style — 单元格样式](#74-style--%E5%8D%95%E5%85%83%E6%A0%BC%E6%A0%B7%E5%BC%8F)
    - [7.5 SheetStyle — Sheet 级样式](#75-sheetstyle--sheet-%E7%BA%A7%E6%A0%B7%E5%BC%8F)
    - [7.6 ImportConfig — 导入配置类](#76-importconfig--%E5%AF%BC%E5%85%A5%E9%85%8D%E7%BD%AE%E7%B1%BB)
    - [7.7 导入 Sheet](#77-%E5%AF%BC%E5%85%A5-sheet)
    - [7.8 导入 Column](#78-%E5%AF%BC%E5%85%A5-column)
- [8. 流程图](#8-%E6%B5%81%E7%A8%8B%E5%9B%BE)
- [9. 内置 Demo 配置](#9-%E5%86%85%E7%BD%AE-demo-%E9%85%8D%E7%BD%AE)

---

1. 环境要求与安装
----------

[](#1-环境要求与安装)

### 1.1 环境要求

[](#11-环境要求)

依赖版本说明PHP&gt;= 8.1Laravel10.x / 11.x / 12.xSwoole / Roadrunner可选仅异步队列 Worker 运行时需要Redis 服务任意版本需运行中，用于进度存储和消息队列MySQL5.7+仅 `dbLog.enabled=true` 时需要### 1.2 PHP 扩展

[](#12-php-扩展)

以下 PHP 扩展必须安装并启用：

```
# xlswriter — Excel 读写核心驱动
pecl install xlswriter
# 安装后在 php.ini 中添加：extension=xlswriter

# redis — 进度追踪和消息队列依赖
pecl install redis
# 安装后在 php.ini 中添加：extension=redis

# mbstring — 字符串处理（通常已内置）
# 如未启用：apt install php-mbstring 或 yum install php-mbstring
```

验证扩展已安装：

```
php -m | grep -E "xlswriter|redis|mbstring"
# 应输出：
# mbstring
# redis
# xlswriter
```

### 1.3 安装

[](#13-安装)

```
composer require businessg/laravel-excel
```

> 包已配置 Laravel Package Auto-Discovery，`ExcelServiceProvider` 自动注册，无需手动添加。

### 1.4 依赖组件说明

[](#14-依赖组件说明)

以下 Composer 包由组件自动引入，无需手动安装。但部分包需要**确认配置已正确**：

依赖包用途需要的配置`businessg/base-excel`核心库（自动安装）无`illuminate/filesystem`导出文件存储确认 `config/filesystems.php` 中有对应的 disk（默认 `local`）`illuminate/redis`进度追踪、消息队列确认 `config/database.php` 中 `redis` 连接配置正确`illuminate/queue`异步导入导出确认 `config/queue.php` 中有可用连接（推荐 `redis`）`illuminate/database`数据库日志仅 `dbLog.enabled=true` 时需要`league/flysystem`文件系统抽象层（base-excel 依赖）无需额外配置`ramsey/uuid`生成任务 token无**重点检查项：**

**1) Filesystem（文件系统）**

导出文件默认存储到 `local` 磁盘。确认 `config/filesystems.php` 中配置：

```
'disks' => [
    'local' => [
        'driver' => 'local',
        'root'   => storage_path('app'),
    ],
],
```

> 如需存储到 OSS/S3 等云存储，安装对应 Flysystem 适配器并修改 `excel.php` 的 `drivers.xlswriter.disk`。

**2) Redis**

确认 `config/database.php` 中 Redis 配置可连接：

```
'redis' => [
    'client' => env('REDIS_CLIENT', 'phpredis'), // 推荐 phpredis（即 ext-redis）
    'default' => [
        'host'     => env('REDIS_HOST', '127.0.0.1'),
        'password' => env('REDIS_PASSWORD', null),
        'port'     => env('REDIS_PORT', 6379),
        'database' => env('REDIS_DB', 0),
    ],
],
```

**3) Queue（异步模式需要）**

使用异步导入导出时，确认队列连接：

```
// config/queue.php
'connections' => [
    'redis' => [
        'driver'      => 'redis',
        'connection'  => 'default',
        'queue'       => 'default',
        'retry_after' => 90,
    ],
],
```

### 1.5 发布配置文件

[](#15-发布配置文件)

```
php artisan vendor:publish --tag=excel-config
```

生成：

- `config/excel.php` — 组件核心配置
- `config/excel_business.php` — 业务导入导出配置

### 1.6 数据库迁移

[](#16-数据库迁移)

启用数据库日志（`dbLog.enabled = true`）时执行：

```
php artisan migrate
```

创建 `excel_log` 表。建表 SQL 如下（也可手动执行）：

```
CREATE TABLE `excel_log` (
    `id`              bigint unsigned NOT NULL AUTO_INCREMENT,
    `token`           varchar(64)  NOT NULL DEFAULT ''  COMMENT '唯一标识',
    `type`            enum('export','import') NOT NULL DEFAULT 'export' COMMENT '类型',
    `config_class`    varchar(250) NOT NULL DEFAULT ''  COMMENT '配置类名',
    `config`          json         DEFAULT NULL         COMMENT '序列化的配置信息',
    `service_name`    varchar(20)  NOT NULL DEFAULT ''  COMMENT '服务名称',
    `sheet_progress`  json         DEFAULT NULL         COMMENT '各 Sheet 进度',
    `progress`        json         DEFAULT NULL         COMMENT '总进度',
    `status`          tinyint unsigned NOT NULL DEFAULT '1' COMMENT '1待处理 2处理中 3处理完成 4失败 5输出中 6完成',
    `data`            json         NOT NULL             COMMENT '结果数据（如文件路径）',
    `remark`          varchar(500) NOT NULL DEFAULT '',
    `url`             varchar(300) NOT NULL DEFAULT ''  COMMENT '导入文件地址',
    `created_at`      timestamp    NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at`      timestamp    NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uniq_token` (`token`)
) ENGINE=InnoDB COMMENT='导入导出日志';
```

---

2. 配置参考
-------

[](#2-配置参考)

### 2.1 excel.php — 组件核心配置

[](#21-excelphp--组件核心配置)

```
