ThinkPHP数据导入失败主因是文件解析、内存控制、数据库写入或环境适配问题，需先区分“读不进”或“写不出”，再依环节针对性解决。
ThinkPHP数据导入失败，通常不是代码写错，而是卡在文件解析、内存控制、数据库写入或环境适配这些环节。关键要分清是“读不进”还是“写不出”，再针对性突破。
Excel文件解析失败：格式、扩展名与加载方式
上传后报错如“Could not open file”或静默失败，大概率是解析器不兼容或路径处理出错。
- PhpSpreadsheet默认全量加载.xlsx，10万行就可能OOM；百万行直接崩溃。不要在Web请求中用它读大文件
- Spout是更优选择：内存恒定3～5MB，但只支持.xlsx和.csv，不支持.xls。前端必须校验后缀，否则解析失败且无明确提示
- 别直接传$_FILES['file']['tmp_name']给IOFactory::load()——临时路径可能被TP清理、含中文或权限不足。应先move_uploaded_file()到runtime/upload/下，再用绝对路径读取
- Linux服务器注意大小写：upload.xlsx ≠ Upload.xlsx，命名空间和文件名必须完全一致
内存溢出或超时：必须脱离Web生命周期
页面卡死、504 Gateway Timeout、Fatal error: Allowed memory size exhausted，说明还在用同步Web请求处理大批量数据。
- 禁用Web超时限制：上传成功后，立即生成任务ID，把文件路径写入Redis队列，由CLI进程消费
- 执行命令分离处理：php think import:worker --task_id=abc123，该命令不走Nginx/Apache，不受max_execution_time和memory_limit影响
- 流式读取+分片写入：用Spout逐行遍历，每1000行调一次Db::name('table')->insertAll($batch)，之后清空数组并执行gc_collect_cycles()
- 避免ORM开销：不要在循环里new模型实例，改用Db::raw()构造INSERT语句，跳过验证、事件、自动时间戳等中间层
数据库写入中断：连接、事务与索引拖慢
日志显示SQL执行一半就停了，或报错“MySQL server has gone away”“Lock wait timeout exceeded”，多与数据库层配置有关。
立即学习“PHP免费学习笔记（深入）”；
- 关闭SQL日志：导入前执行\think\facade\Db::listen(function() {})，彻底屏蔽日志记录
- 临时禁用约束：导入开始前运行Db::execute('SET UNIQUE_CHECKS=0; SET FOREIGN_KEY_CHECKS=0;')，完成后恢复。注意：禁用期间严禁并发写入
- 事务粒度要小：不要用Db::transaction包裹全部百万行，而应在每个1000行批次后commit一次
- 检查MySQL连接状态：PDO异常message若为“Connection refused”，先确认mysqld是否运行；若为“has gone away”，需调高wait_timeout和max_allowed_packet
配置与环境陷阱：常被忽略的硬性条件
本地能跑，上线就失败？多数问题藏在环境细节里。
- Spout依赖php_zip扩展：Windows用户检查php.ini中extension=zip是否启用（去掉分号）；Linux用php -m | grep zip确认
- MySQL 8.0认证插件不兼容：报错“caching_sha2_password cannot be loaded”时，执行ALTER USER 'user'@'%' IDENTIFIED WITH mysql_native_password BY 'pwd'
- ThinkPHP配置未生效：.env文件必须放在项目根目录（和think命令同级），且APP_DEBUG=true才加载环境变量；用dump(env('DB_HOST'))验证是否读取成功
- 主键字段不匹配：Db::table('user')->find(123)默认查WHERE id = 123，若表主键是uid，需显式指定->pk('uid')
