Laravel Excel多工作表导入异常：仅执行首个Import类问题排查

版本信息 #

• PHP - 7.4.33
• Laravel - 6.20.44
• maatwebsite/excel - 3.1.56

问题描述 #

使用WithMultipleSheets导入Excel多工作表时，所有工作表的数据都仅被首个Import类ZoneRuleImport处理，ZonePriceImport未生效。

代码示例 #

调用代码 #

$import = new CarrierPriceRuleImport($ruleId, $length);

Excel::import($import, $file);

CarrierPriceRuleImport类 #

class CarrierPriceRuleImport implements WithMultipleSheets, SkipsUnknownSheets
{
    protected $ruleId, $length;

    public function __construct($ruleId, $length = 5)
    {
        $this->ruleId = $ruleId;
        $this->length = $length;
    }

    public function sheets(): array
    {
        return [
            0 => new ZoneRuleImport($this->ruleId, $this->length),
            1 => new ZonePriceImport($this->ruleId),
        ];
    }

    public function onUnknownSheet($sheetName)
    {
        dump($sheetName);
    }
}

Excel文件说明 #

Excel包含两个工作表，名称分别为「区域规则」、「区域价格」。

运行情况 #

所有工作表的数据均通过ZoneRuleImport处理，ZonePriceImport未执行，也未触发onUnknownSheet方法。

问题原因及解决方案 #

核心原因 #

代码中使用数字索引绑定工作表与Import类，数字索引依赖于工作表在Excel中的顺序，若实际工作表顺序与预期不符（或内部索引识别异常），会导致绑定失效；另外数字索引的匹配逻辑在部分场景下存在兼容性问题。

解决方案 #

将sheets()方法中的数字索引替换为工作表的实际名称，直接通过名称绑定对应Import类，避免顺序依赖：

public function sheets(): array
{
    return [
        '区域规则' => new ZoneRuleImport($this->ruleId, $this->length),
        '区域价格' => new ZonePriceImport($this->ruleId),
    ];
}

额外排查点 #

1. 确认ZoneRuleImport和ZonePriceImport均正确实现了导入所需接口（如ToCollection、ToModel），且核心处理方法（如collection()）编写正常；
2. 清除Laravel缓存，避免旧代码缓存影响：

php artisan cache:clear
php artisan config:clear

3. 检查Excel文件是否存在隐藏工作表，或工作表名称存在空格/特殊字符，导致名称匹配失败。

内容的提问来源于stack exchange，提问作者WeiCheng