ThinkPHP导入Excel上传环境配置及新手安装教程

先说几个核心判断：在ThinkPHP框架中实现Excel导入功能，前提是必须把上传环境的底层配置彻底搞清楚。很多初学者刚接触时就卡在“文件找不到”或者页面直接白屏报错，问题根源在哪里？其实并不在于Excel文件本身的解析逻辑，而在于上传路径设置、目录权限、文件验证规则这些基础配置没有配置正确。

简单来说，上传环境的正确配置，才是打通整个导入流程的真正门槛。

确认PHP与Composer环境可用

打开终端，进入你的ThinkPHP项目根目录——就是那个包含composer.json和think文件的文件夹。

先执行一条php -v命令，确认PHP版本号达到7.4或更高。如果版本低于这个要求，PhpSpreadsheet的最新版本将无法正常运行，直接会报出Class not found错误，导致前期工作全部白费。

接着运行composer --version，确保能够正常输出Composer版本号。如果系统提示“command not found”，说明Composer没有正确安装或者没有被添加到系统PATH环境变量中，需要先回去把Composer安装配置好。

【千万不要跳过这步】项目根目录下必须存在vendor/autoload.php这个文件。这是Composer自动加载的入口文件，ThinkPHP6需要依靠它来识别和加载PhpSpreadsheet的相关类。

安装phpspreadsheet依赖包

在项目根目录下执行以下命令：

composer require phpoffice/phpspreadsheet

等待终端输出类似“Installing phpoffice/phpspreadsheet (v2.2.2)”这样的提示信息，就表示安装成功了。安装完成后，检查一下vendor/phpoffice/phpspreadsheet目录是否已经生成，同时确认composer.json文件中是否增加了"phpoffice/phpspreadsheet": "^2.2"这一行依赖配置。

如果遇到Class 'PhpOffice\PhpSpreadsheet\IOFactory' not found这个错误，百分之九十的原因是因为你没有执行composer dump-autoload命令——补上这条命令重新加载一下自动加载配置就可以了。

配置上传目录与权限

ThinkPHP默认情况下并没有开放runtime/upload目录的写入权限，你需要手动创建该目录并设置相应的权限：

在项目根目录执行：mkdir -p runtime/upload（Windows系统下使用md runtime\upload命令）。

Linux或macOS用户：执行chmod 755 runtime/upload命令。Windows用户可以跳过这一步，但需要确认该目录没有被设置为只读属性。

【关键路径说明】上传后的文件必须保存到ThinkPHP框架能够正常读取的路径下。例如runtime/upload/这个目录。千万不要把文件存到public/uploads/之后还用file_get_contents()强行读取——框架会直接拦截这种操作，因为非runtime目录下的文件访问是不被框架认可的。

编写上传接口并验证文件类型

到了编写接口这一步，整个流程就变得清晰多了。核心操作只需要四步：

第一步，接收上传的文件对象；第二步，校验文件扩展名是否为xlsx或xls；第三步，将文件安全移动到runtime/upload目录；第四步，返回完整的文件路径，供后续读取解析使用。

文件类型校验绝对不能只依赖$_FILES['file']['type']这个字段，因为它的值太容易被人为伪造了。必须使用pathinfo($file->getOriginalName(), PATHINFO_EXTENSION)来获取真实的文件后缀名，并且严格限制只允许xlsx或xls这两种格式。

移动文件时，必须使用$file->move('runtime/upload/')这个方法。不要自己手动调用copy()或者move_uploaded_file()去处理临时路径——ThinkPHP的File对象已经封装好了完善的安全处理逻辑，直接使用它提供的方法就够了。

如果$file->move()方法返回false，立即使用$file->getError()方法查询具体的错误原因。最常见的情况就是runtime/upload目录不存在，或者该目录没有正确的写入权限。请记住，这一步如果出了问题，后面的所有解析操作都将无法进行。