Laravel-Excel 导出时出现 Undefined variable 错误的解决方案

问题背景

在使用 Laravel-Excel 进行数据导出时，开发者可能会遇到一个常见的错误："Undefined variable: sheetExport"。这个错误通常发生在使用队列导出功能时，特别是在处理多工作表导出的场景中。

错误原因分析

该错误的根本原因在于 QueueExport.php 文件中 handle 方法的实现逻辑。当开发者尝试使用 WithMultipleSheets 接口实现多工作表导出时，如果 sheets() 方法返回的数组为空或者格式不正确，就会导致变量未定义的错误。

具体来说，在以下代码段中：

$writer->write($sheetExport, $this->temporaryFile, $this->writerType);

$sheetExport 变量是在 foreach 循环中定义的局部变量，但在循环外部被引用，这显然是一个编程错误。

解决方案

1. 检查 sheets() 方法实现

首先确保你的导出类中 sheets() 方法正确实现了 WithMultipleSheets 接口，并且返回了有效的 Sheet 对象数组。例如：

public function sheets(): array
{
    return [
        new FirstSheetExport(),
        new SecondSheetExport(),
    ];
}

2. 升级 Laravel-Excel 版本

最新版本的 Laravel-Excel 已经修复了这个问题，增加了更明确的异常处理。建议升级到最新稳定版。

3. 临时解决方案

如果暂时无法升级，可以创建一个自定义的 QueueExport 类来覆盖原始实现：

namespace App\Overrides;

use Maatwebsite\Excel\Jobs\QueueExport as BaseQueueExport;

class QueueExport extends BaseQueueExport
{
    public function handle(Writer $writer)
    {
        (new LocalizeJob($this->export))->handle($this, function () use ($writer) {
            $writer->open($this->export);

            $sheetExports = [$this->export];
            if ($this->export instanceof WithMultipleSheets) {
                $sheetExports = $this->export->sheets();
            }

            foreach ($sheetExports as $sheetIndex => $sheetExport) {
                $sheet = $writer->addNewSheet($sheetIndex);
                $sheet->open($sheetExport);
            }

            $writer->write($sheetExports, $this->temporaryFile, $this->writerType);
        });
    }
}

然后在服务提供者中替换原始实现：

$this->app->bind(
    \Maatwebsite\Excel\Jobs\QueueExport::class,
    \App\Overrides\QueueExport::class
);

最佳实践建议

1. 始终验证导出类：在使用队列导出前，先测试同步导出是否正常工作
2. 实现完善的错误处理：在导出类中添加适当的异常处理逻辑
3. 监控队列任务：设置队列失败通知，及时发现导出问题
4. 保持依赖更新：定期更新 Laravel-Excel 到最新版本

总结

这个错误提醒我们在使用队列处理复杂导出任务时需要特别注意变量作用域和接口实现。通过正确实现 WithMultipleSheets 接口和保持组件更新，可以有效避免此类问题的发生。对于关键业务场景的导出功能，建议增加额外的测试用例来验证多工作表导出的正确性。