Laravel 迁移报错 SQLSTATE[42000] 1071 指定键太长怎么修复

核心结论：在 AppServiceProvider.php 的 boot 方法中添加 Schema::defaultStringLength(191) 可解决 767 bytes 或 1000 bytes 的键长度限制问题，该方案适用于 Laravel 5.4 至 Laravel 12 多个版本。

原因分析

该错误的完整报错信息为：SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes。问题根源在于 Laravel 5.4 之后默认使用 utf8mb4 字符集，而 utf8mb4 每个字符最多占用 4 字节。当创建唯一索引时，默认字符串长度为 255 字符，255 × 4 = 1020 字节，超过了 MySQL 5.7.7 以下版本的最大键长度 767 字节限制。根据 2021 年 12 月 15 日发布的技术分析，如果使用的 MySQL 数据库版本高于 5.7 则不会报错，低于该版本就会出现此错误。

解决方案

方案一：设置默认字符串长度（推荐）

在 app/Providers/AppServiceProvider.php 文件的 boot 方法中添加以下代码：

use Illuminate\Support\Facades\Schema;

public function boot()
{
    Schema::defaultStringLength(191);
}

该方案来自 2025 年 10 月 23 日的 Laravel 12 修复记录，191 字符 × 4 字节 = 764 字节，低于 767 字节限制。2025 年 8 月 22 日的测试数据显示，此方法在 Windows 环境下同样有效，可解决 max key length is 1000 bytes 的变体错误。

方案二：修改数据库字符集配置

修改 config/database.php 文件，找到 mysql 配置项，将字符集从 utf8mb4 改为 utf8：

'charset' => 'utf8',
'collation' => 'utf8_unicode_ci',

该方案来自 2023 年 2 月 6 日的记录，但会降低字符集支持能力，不推荐用于需要存储表情符号等特殊字符的项目。

方案三：针对特定扩展的调整

安装 laravel-permission 扩展后遇到迁移错误时，需在 app/Providers/AuthServiceProvider.php 的 boot 方法中添加 Schema::defaultStringLength(125)。2022 年 5 月 7 日的记录显示，该扩展的 permissions_name_guard_name_unique 联合索引对长度更敏感，125 字符可确保兼容性。

注意事项

第一，执行迁移前需确保引入正确的命名空间。2021 年 7 月 1 日的用户反馈显示，未添加 use Illuminate\Support\Facades\Schema 会导致 Class 'App\Providers\Schema' not found 错误。第二，如果已生成部分表，需先删除数据库中已存在的表再重新迁移。2024 年 12 月 4 日的 Laravel 11 安装记录提到，出现 Table 'users' already exists 错误时需清理数据库后重试。第三，不同 Laravel 版本的文件路径可能不同，Laravel 5.4-5.6 使用 AppServiceProvider，而 Laravel 11-12 需确认配置文件位置。第四，MySQL 版本低于 5.7.7 时此问题必现，2018 年 7 月 18 日的记录表明该问题多年未在框架层面修复，需手动处理。

参考来源

来源：CSDN 博客 - Laravel 5.4 因特殊字段太长导致 migrations 报错的解决（2026 年 4 月 5 日）

来源：CSDN 博客 - Laravel 12 修复记录（2025 年 10 月 23 日）

来源：CSDN 博客 - 安装 laravel-permission 后迁移报错解决方案（2022 年 5 月 7 日）

来源：CSDN 博客 - Laravel 5.5 报错 1071 技术分析与解决（2021 年 12 月 15 日）