Docker中Laravel事务异常需五步排查：一、确认数据库引擎为InnoDB且Laravel连接配置正确；二、启用Xdebug并验证远程调试链路；三、将Laravel日志绑定STDERR以实时捕获事务异常；四、用Telescope可视化追踪事务生命周期；五、通过保存点分段验证事务执行边界。
如果您在Docker环境中运行Laravel应用时遇到事务未按预期提交或回滚的问题，则可能是由于容器内数据库连接隔离、日志不可见、Xdebug未生效或事务上下文丢失所致。以下是解决此问题的步骤：
一、验证数据库事务支持与引擎配置
MySQL或PostgreSQL容器必须使用支持事务的存储引擎（如InnoDB），且Laravel连接配置需启用持久连接与严格模式，否则事务可能静默失效。
1、进入数据库容器并检查当前表引擎：
docker-compose exec db mysql -u root -p${DB_PASSWORD} ${DB_DATABASE} -e "SHOW CREATE TABLE users;"
2、确认输出中包含 ENGINE=InnoDB；若为 MyISAM，则需重建表：
ALTER TABLE users ENGINE=InnoDB;
3、检查Laravel .env 中 DB_CONNECTION 配置是否指向正确服务名（如 db），且 DB_HOST 设置为 db（Docker内部服务别名，非 localhost）。
二、启用并验证Xdebug远程调试链路
Xdebug是定位事务异常中断位置的关键工具，必须确保其在PHP容器中启用、端口可路由、且VSCode能成功连接。
1、确认 docker-compose.yml 中 app 服务已暴露 9001 端口：
ports: - "9001:9001"
2、在容器内验证xdebug扩展已加载：
docker-compose exec app php -m | grep xdebug
3、执行 php -i | grep "xdebug.mode"，输出应为 debug,develop；若为空，需检查 xdebug.ini 是否被正确挂载并生效。
4、在事务闭包起始处添加断点并触发请求，观察VSCode是否捕获调试会话；若无响应，检查宿主机防火墙及 xdebug.client_host=host.docker.internal 设置是否匹配Windows/macOS Docker Desktop环境。
三、强制事务日志输出至容器标准流
默认情况下，DB::transaction() 内部异常不会自动写入 docker logs，需将Laravel日志通道与STDERR绑定，使事务失败堆栈实时可见。
1、修改 config/logging.php，确保 stack 渠道包含 single 且 ignore_exceptions 设为 false：
'ignore_exceptions' => false,
2、在 .env 中设置 LOG_CHANNEL=stack，并执行 docker-compose exec app php artisan config:clear
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
3、覆盖PHP服务启动命令，在 docker-compose.yml 的 app 服务中添加：
command: sh -c "touch storage/logs/laravel.log && tail -f storage/logs/laravel.log > /proc/1/fd/2 & exec docker-php-entrypoint php-fpm"
4、复现事务失败场景后，立即运行 docker logs laravel-app，确认输出中包含 PDOException 或 QueryException 及完整SQL与回溯路径。
四、使用Telescope捕获事务生命周期事件
Laravel Telescope可在容器中记录每一次 transaction.begin、transaction.commit 和 transaction.rollback 事件，提供可视化事务追踪能力。
1、在Docker环境下安装Telescope：
docker-compose exec app composer require laravel/telescope --dev
2、发布资源并迁移：
docker-compose exec app php artisan telescope:install
docker-compose exec app php artisan migrate
3、确保 TELESCOPE_ENABLED=true 且 APP_ENV=local（或手动设为 true）出现在 .env 中
4、访问 http://localhost:8000/telescope/entries?tag=transaction，筛选出所有事务相关条目，重点检查 duration_ms 字段是否为0或超长，以及 commit/rollback 状态是否缺失。
五、注入事务保存点进行分段验证
当需判断事务中某子操作是否实际影响数据库，可在关键节点插入 savepoint 并手动 rollbackTo，结合日志交叉验证执行边界。
1、在事务闭包内插入显式保存点：
$sp = DB::savepoint();
2、在疑似失败操作前添加日志：
Log::info('Before risky operation', ['savepoint' => $sp]);
3、捕获异常后执行部分回滚：
DB::rollbackTo($sp);
Log::warning('Rolled back to savepoint', ['savepoint' => $sp]);
4、检查 docker logs 输出是否同时出现 info 与 warning 日志，若 warning 缺失，说明异常未被捕获或未进入 catch 块，需检查 try/catch 范围或异常类型是否被忽略。
