执行 php artisan migrate 前须确认数据库配置生效：清缓存（config:clear）、验证 config('database.connections.mysql')、检查 DB_HOST（尤其 Docker 环境）；migrate 仅执行未运行迁移，migrate:fresh 会清库重建，禁用于生产；迁移失败易致 migrations 表状态不一致，应查 batch 连续性并手动修复或回滚。
运行 php artisan migrate 前必须确认数据库配置已生效
很多人执行迁移失败，第一反应是命令写错了，其实八成是 .env 里的 DB_DATABASE、DB_USERNAME 或 DB_PASSWORD 没配对，或者改了 .env 但没清缓存。
实操建议：
-
php artisan config:clear必须跑一次，否则.env变更不生效（Laravel 会缓存配置） - 用
php artisan tinker进去敲config('database.connections.mysql')，直接看读到的数据库连接参数是不是你预期的 - 如果用的是 Docker 或远程 MySQL，记得检查
DB_HOST是不是写成了localhost——容器内它连的是自己，不是宿主机
migrate 和 migrate:fresh 的行为差异很关键
php artisan migrate 只跑没执行过的迁移文件，靠 migrations 表记录；而 php artisan migrate:fresh 会先删库再重建，适合本地开发重置，但生产环境绝对禁用。
常见错误现象：
- 执行
migrate报错SQLSTATE[HY000]: General error: 1005 Can't create table，大概率是外键依赖的表还没建，顺序乱了——迁移文件名时间戳决定顺序，别手动改 - 误在测试环境跑了
migrate:fresh，结果清掉了测试数据，因为它的默认行为就是DROP TABLE IF EXISTS - 想回退但只跑了一次
migrate:rollback，发现只撤了一个批次——它默认只撤最后一个batch，要全撤得加--step=100
带参数运行迁移时，--path 和 --realpath 别混用
当你把迁移文件放在非默认路径（比如 database/migrations/tenant），要用 --path 指定相对路径；但如果用了符号链接或 Composer autoload 路径映射，就得换 --realpath。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
使用场景和坑：
-
php artisan migrate --path=database/migrations/tenant：路径是相对于项目根目录的，且必须存在该子目录 -
php artisan migrate --realpath：告诉 Artisan 直接读取文件系统真实路径，绕过 Laravel 的路径解析逻辑，适合 vendor 包里自带的迁移 - 两个参数不能同时用，否则
--path会被忽略，Artisan 会报Option --path cannot be used with --realpath - CI 环境里如果用
--path，确保该路径在构建镜像时已存在，否则静默跳过，不报错也不执行
迁移失败后，migrations 表状态可能卡住
迁移中途出错（比如字段类型写错、索引名重复），Laravel 不会自动清理 migrations 表里的记录。下次再跑，它以为这个文件已经执行过，直接跳过，导致结构和代码不一致。
怎么判断和修复：
- 查
migrations表，看最后几条记录的batch字段是否连续；断掉的地方就是卡点 - 手动删掉对应
id的行，再重新跑migrate（仅限开发环境） - 更安全的做法是先
php artisan migrate:rollback --step=1，它会按 batch 回滚，比手删表稳妥 - 如果迁移里写了
DB::statement()或原生 SQL，失败后不会自动事务回滚，表可能处于半创建状态——这种迁移最好拆成两步，先建表再改结构
事情说清了就结束。迁移脚本本身不复杂，但数据库状态、配置缓存、路径解析、事务边界这四块最容易串在一起出问题，调的时候别只盯着命令输没输对。
