ThinkPHP中高效读写CSV需安装league/csv包（如v9.15.0），手动引入Reader/Writer类，用createFromStream处理BOM，导出时注入UTF-8 BOM头，并调用getRecords()获取记录集，避免foreach直接遍历Reader实例。
如果您在 ThinkPHP 项目中需要高效读写 CSV 文件，但发现原生处理易出乱码、跳行或解析失败，则很可能是未正确引入或配置 league/csv 包。以下是针对 ThinkPHP 环境安装与适配该包的具体操作步骤：
一、通过 Composer 安装 league/csv 包
League CSV 是一个独立的 Composer 包，无需额外安装 Composer 本身，只需确保项目根目录下已存在 composer.json 并可执行 composer 命令。安装过程需明确指定版本兼容性，避免与 PHP 或 ThinkPHP 版本冲突。
1、进入 ThinkPHP 项目根目录（即包含 thinkphp 和 vendor 目录的路径）。
2、执行命令安装 v9.x 兼容版本（推荐 v9.15.0，已验证支持 PHP 8.2+）：
composer require league/csv:^9.15
立即学习“PHP免费学习笔记（深入）”；
3、若提示 autoload 冲突或类找不到，请确认 vendor/autoload.php 已在入口文件（如 public/index.php）或控制器中被正确引入。
二、在 ThinkPHP 中手动引入并初始化 Reader/Writer
ThinkPHP 默认不自动加载第三方命名空间，需显式声明 use 语句，并确保 autoloader 已生效。此步骤绕过框架封装层，直接调用 league/csv 原生 API，保障对 BOM、换行符、分隔符等细节的完全控制。
1、在控制器方法顶部添加命名空间引用：
use League\Csv\Reader;
use League\Csv\Writer;
2、在方法体内创建 Reader 实例时，必须使用 createFromStream() 而非 createFromPath()，以支持 BOM 清理和流式控制。
3、打开文件后先检测并跳过 UTF-8 BOM：
$fp = fopen('data.csv', 'r');
if (fread($fp, 3) === "\xEF\xBB\xBF") { } else { fseek($fp, 0); }
4、传入已定位的流对象构建 Reader：
$reader = Reader::createFromStream($fp);
$reader->setDelimiter(',');
$reader->setEnclosure('"');
三、解决 ThinkPHP 下中文导出 Excel 乱码问题
直接输出 UTF-8 编码 CSV 到浏览器，Excel 默认无法识别，表现为方块或空格；根本原因是缺少 UTF-8 BOM 头标识。此问题与 ThinkPHP 的 header 输出机制强相关，需在写入内容前强制注入 BOM 字节。
1、使用 Writer 创建实例：
$writer = Writer::createFromPath('php://output', 'w');
2、立即写入 BOM 头（不可省略且必须在第一行）：
fwrite($writer->getCsvDocument()->getStream(), "\xEF\xBB\xBF");
3、设置输出头，声明为 Excel 兼容类型：
header('Content-Type: application/vnd.ms-excel');
header('Content-Disposition: attachment; filename="export_' . date('YmdHis') . '.csv"');
4、写入数据前统一转码为 UTF-8：
$row = array_map(function ($v) { return mb_convert_encoding($v, 'UTF-8', 'auto'); }, $data);
$writer->insertOne($row);
四、集成 laracsv 封装包实现模型一键导出
laracsv 是基于 league/csv 构建的 ThinkPHP 友好扩展，提供模型字段映射、钩子回调、自定义标题等能力，适合快速交付场景。其底层仍依赖 league/csv，因此必须先完成步骤一的安装。
1、执行命令安装 laracsv：
composer require "laracsv/laravel-csv"
2、在控制器中引入封装类：
use Laracsv\Export;
3、实例化并绑定 Eloquent 模型（ThinkPHP 6 可使用 think\Model 实例或数组集合）：
$export = new Export();
$users = \app\model\User::select();
4、构建导出结构并启用 BOM 支持：
$export->build($users, ['email', 'nickname' => '昵称', 'create_time' => '注册时间']);
$export->beforeEach(function ($user) { $user->create_time = date('Y-m-d H:i:s', strtotime($user->create_time)); });
5、调用 download() 前手动注入 BOM（laracsv 默认不加）：
$writer = $export->getWriter();
fwrite($writer->getCsvDocument()->getStream(), "\xEF\xBB\xBF");
$export->download('users_export.csv');
五、修复常见报错：Invalid argument supplied for foreach() 或空数组
该错误多出现在 v9+ 版本中，因 Reader 默认返回只读迭代器对象，未调用 getRecords() 或 setOffset() 即直接 foreach，导致内部资源未激活。ThinkPHP 的异常捕获机制会将此类逻辑错误转为 500，需从调用链源头修正。
1、禁止直接对 Reader 实例使用 foreach：
// 错误写法：
foreach ($reader as $row) { ... }
2、必须显式获取记录集：
$records = $reader->getRecords();
foreach ($records as $row) { ... }
3、若需跳过首行（标题行），须先调用：
$reader->setOffset(1);
4、检查文件是否为空或权限不足：
if (!$reader->count()) { throw new \Exception('CSV 文件为空或无法读取'); }
