本文详解 Laravel 迁移机制的核心逻辑：php artisan migrate 及其变体（如 migrate:fresh）并非仅运行你“手动创建”的迁移文件，而是扫描 database/migrations/ 目录下所有符合命名规范的 PHP 文件（含框架自动生成的默认迁移），并依据时间戳顺序统一执行；理解这一机制是避免“莫名执行未编写迁移”“索引过长报错”等高频问题的关键。
本文详解 laravel 迁移机制的核心逻辑：`php artisan migrate` 及其变体（如 `migrate:fresh`）并非仅运行你“手动创建”的迁移文件，而是扫描 `database/migrations/` 目录下**所有符合命名规范的 php 文件**（含框架自动生成的默认迁移），并依据时间戳顺序统一执行；理解这一机制是避免“莫名执行未编写迁移”“索引过长报错”等高频问题的关键。
在 Laravel 项目中，当你执行 php artisan migrate:fresh 却意外触发了 2019_12_14_000001_create_personal_access_tokens_table 这一迁移——而你并未手动创建它——这并非 Bug，而是 Laravel 迁移系统设计使然。该文件是 Laravel 9+（或安装了 laravel/sanctum / laravel/passport 等认证包）时由框架自动发布的标准迁移，用于创建 personal_access_tokens 表以支持 API Token 认证。它通常位于 vendor/laravel/framework/src/Illuminate/Foundation/Providers/ 或通过 php artisan vendor:publish --tag=migrations 命令被复制到你的 database/migrations/ 目录中。
✅ 为什么它会被执行？
Laravel 的 migrate:fresh 命令会：
- 清空当前数据库中所有业务表（跳过 migrations 和 failed_jobs）；
- 递归扫描 database/migrations/ 下所有 .php 文件，只要文件名匹配 YYYY_MM_DD_HHIISS_description.php 格式（时间戳 + 下划线 + 描述），即视为有效迁移；
- 按文件名前缀时间戳升序排序后，全部执行其 up() 方法，无论来源是开发者手写、make:migration 生成，还是框架/包自动发布。
⚠️ 你遇到的 SQLSTATE[42000]: Specified key was too long 错误，正是该迁移中为 (tokenable_type, tokenable_id) 创建联合索引时，在 MySQL 旧版本（如 5.7 默认 utf8mb4 字符集下）超出 1000 字节限制所致——这是典型“环境不兼容”问题，而非迁移本身错误。
? 正确处理步骤（非简单删除）：
确认文件位置：
检查 database/migrations/2019_12_14_000001_create_personal_access_tokens_table.php 是否真实存在。若存在，说明它已被发布到项目中（即使你没主动运行 vendor:publish，某些安装流程会自动触发）。-
修复索引长度问题（推荐）：
不要直接删除该迁移（否则将丢失 API Token 功能）。打开该文件，在 up() 方法中调整字段长度以适配 MySQL 限制：public function up(Blueprint $table) { Schema::create('personal_access_tokens', function (Blueprint $table) { $table->id(); $table->morphs('tokenable'); // 自动创建 tokenable_type (VARCHAR(255)) 和 tokenable_id (BIGINT UNSIGNED) $table->string('name'); $table->string('token', 64)->unique(); // token 字段已足够短 $table->text('abilities')->nullable(); $table->timestamp('last_used_at')->nullable(); $table->timestamp('expires_at')->nullable(); $table->timestamps(); // ✅ 关键修复：显式限制 tokenable_type 长度，避免联合索引超长 $table->index(['tokenable_type', 'tokenable_id']); }); }同时，在 AppServiceProvider 的 boot() 方法中全局设置默认字符串长度（Laravel 5.8+ 推荐方案）：
use Illuminate\Support\Facades\Schema; public function boot() { Schema::defaultStringLength(191); // 替换为 128 或 191，适配 utf8mb4 索引限制 } -
刷新自动加载与执行：
composer dump-autoload # 重建类映射，确保新修改被识别 php artisan migrate:fresh # 现在将安全执行全部迁移（含修复后的 personal_access_tokens）
? 重要原则与避坑指南：
- ❌ 禁止手动删迁移文件：除非你完全弃用对应功能（如彻底不用 Sanctum），否则删除将导致认证模块异常，且破坏团队协作一致性。
- ✅ 优先修复而非绕过：migrate:fresh 是开发环境利器，但应配合正确的字符集配置（MySQL 8.0+ 推荐启用 innodb_large_prefix=ON）和 Laravel 的 defaultStringLength 设置。
- ? 排查迁移来源：使用 php artisan migrate:status 查看所有待执行/已执行迁移及其状态；用 ls database/migrations/ 快速定位可疑文件。
- ? 生产环境零容忍：migrate:fresh 仅限本地开发。线上必须使用 migrate + 严格审核的增量迁移，并配合数据库备份。
掌握迁移的“全量扫描+时间戳排序”机制，你就能从容应对框架自带迁移、第三方包迁移及自定义迁移的共存管理，真正实现数据库结构的可预测、可复现、可协作演进。
