CSV导入失败首要检查分隔符是否匹配，常见问题包括分号、制表符或全角逗号导致fgetcsv解析错误；其次排查BOM头引发字段名异常；再确认是否流式读取避免内存溢出；最后确保每行日志带行号便于定位错误。
laravel-admin 导入失败时先看 CSV 字段分隔符是否匹配
laravel-admin 本身不带 CSV 导入能力，你看到的“导入”功能大概率是自己写的控制器或用了第三方包（比如 maatwebsite/excel），但默认解析逻辑往往只认逗号 ,。如果用户从 Excel 另存为 CSV 或用 Windows 记事本导出，实际可能是分号 ;、制表符 \t，甚至全角逗号——fgetcsv() 会直接把整行当一列读进来，后续 array_combine($header, $row) 就崩了。
实操建议：
- 用
head -n 1 your_file.csv | od -c（Linux/macOS）或 VS Code 以十六进制打开，确认首行真实分隔符 - 若为分号，
fgetcsv($handle, 0, ';')必须显式传第三个参数 - 若用
maatwebsite/excel，得在配置里补上'csv' => ['delimiter' => ';']，否则它按默认逗号硬解 - 别信文件扩展名——
.csv后缀 ≠ 逗号分隔，本质看内容
中文字段名或数据乱码？先清 BOM 再定编码
Windows 记事本保存的 UTF-8 CSV 默认带 BOM（\xEF\xBB\xBF），会导致第一列字段名开头多三个不可见字节，$header[0] 变成 "\xEF\xBB\xBFid"，后面所有 $data['id'] 都取不到值；更糟的是，如果服务器 locale 没设对，mb_convert_encoding() 也会失效。
实操建议：
- 读文件前先
$firstLine = fgets($handle); $firstLine = ltrim($firstLine, "\xEF\xBB\xBF");，再用str_getcsv($firstLine)提表头 - 统一用
mb_convert_encoding($rowItem, 'UTF-8', 'GBK')转码，别依赖iconv()（它遇到非法字符直接报错） - 避免在
config/app.php里设'locale' => 'zh-CN'，改用运行时setlocale(LC_ALL, 'zh_CN.UTF-8') - 测试时用
bin/hexdump -C file.csv | head看开头是不是ef bb bf
导入中途卡死或报内存溢出？不是文件大，是读法错了
laravel-admin 常见错误是把整个 CSV 用 file_get_contents() + array_map('str_getcsv', ...) 一次性加载——万行 CSV 在 PHP 8.2 下轻松吃掉 512MB 内存，超时或 OOM 是必然结果。哪怕你加了 ini_set('memory_limit', '-1')，也挡不住底层字符串复制的开销。
实操建议：
- 必须用
fopen()+fgetcsv()流式读，每行只占几 KB，10 万行也稳定在 2MB 内 - 别在循环里调
YourModel::create()，攒够 500 行再DB::table()->insert()批量写入 - 如果用了
maatwebsite/excel，确认导入类实现了WithChunkReading，且chunkSize()设为 500，否则它还是全读进内存 - 上传大文件前，检查
php.ini的upload_max_filesize和post_max_size是否 ≥ 文件体积
插入报错但不知道哪行出问题？日志里必须带原始行号和内容
常见报错如 SQLSTATE[HY000]: General error: 1366 Incorrect integer value 或 Undefined index: email，只告诉你失败，不告诉你第几行、原始数据长啥样。线上环境根本没法定位——你不可能让运营同学手动翻到第 8427 行去查少没少逗号。
实操建议：
- 每次
fgetcsv()后立刻记录当前行号：$lineNumber++ - 插入前做
$logData = array_merge(['row_number' => $lineNumber], $row)，出错时写进日志或 DB 错误表 - 别用
try/catch包整个 while 循环——那样一错就停，应该单行 try，失败只跳过该行并记日志 - 验证逻辑要前置：检查
count($row) !== count($header)，直接标为“列数不匹配”，比等 SQL 报错快得多
真正难的不是读 CSV，是让每一步失败都可追溯。字段映射错、空值没过滤、时间格式不对——这些不会导致脚本崩溃，但会让数据静默污染。上线前拿一份含典型脏数据的样本跑一遍，比写十遍文档都管用。
