直接运行 composer require phpoffice/phpspreadsheet 即可安装，PHP 7.4+ 无需额外操作；低版本需确认 Composer 使用的 PHP 版本匹配；国内访问慢可切换阿里云镜像；使用前必须正确引入 vendor/autoload.php；读取 .xls 文件需改用 Xls Reader；处理大文件应启用只读模式、指定工作表、批量写入和缓存。
Composer 安装 phpoffice/phpspreadsheet 的正确命令
直接运行 composer require phpoffice/phpspreadsheet 即可，不需要加 @stable 或指定版本（最新版已默认稳定）。如果你的项目用了 PHP 7.4+，无需额外操作；若仍在用 PHP 7.2 或 7.3，需确认 Composer 加载的 PHP 版本是否匹配——常见错误是终端里 php -v 显示 8.1，但 Composer 走的是系统默认旧版 PHP，导致安装失败或依赖解析异常。
安装时可能卡在 Loading composer repositories with package information，这不是库的问题，而是 Packagist 国内访问慢。临时解决办法是切换镜像：composer config -g repo.packagist composer https://packagist.phpcomposer.com（注意：该镜像已停用，推荐改用 https://packagist.org 配合代理，或使用阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/）。
require 后为什么 vendor/autoload.php 包含不了类？
最常被忽略的是没在脚本开头正确引入自动加载文件。PHPSpreadsheet 不提供全局函数，所有类都必须通过 require 'vendor/autoload.php'; 加载，且这行代码必须出现在任何 new \PhpOffice\PhpSpreadsheet\* 实例化之前。
容易出错的点：
立即学习“PHP免费学习笔记（深入）”；
- 路径写错，比如写成
require './autoload.php';（少写了vendor/） - 用
include替代require，出错时不报致命错误，后续类找不到却静默失败 - CLI 运行时工作目录不是项目根目录，
vendor/autoload.php相对路径失效 → 改用__DIR__ . '/vendor/autoload.php'
PhpSpreadsheet\IOFactory 读 Excel 文件时提示 “Could not open … for reading”
这个错误和 PHPSpreadsheet 本身关系不大，90% 是文件路径或权限问题。重点检查三件事：
- 传给
IOFactory::load()的路径是否为绝对路径或相对于当前执行脚本的正确相对路径（不是相对于 web root） - 文件是否存在、是否可读：
is_readable($path)应返回true - 如果是上传后的临时文件，确认没被
move_uploaded_file()移走或$_FILES临时目录已被清空
另外注意：PHPSpreadsheet 默认不支持 .xls（Excel 2003），只支持 .xlsx、.ods、.csv 等。如果强行传入 .xls 文件，会抛出 PhpOffice\PhpSpreadsheet\Exception，错误信息里带 Unsupported file type —— 此时要换用 PhpOffice\PhpSpreadsheet\Reader\Xls 类，或统一转成 xlsx 再处理。
内存溢出或导出大文件卡死？别硬扛，得调配置
PHPSpreadsheet 默认把整张表加载进内存，10 万行 × 50 列就很容易触发 Allowed memory size exhausted。不能只靠 ini_set('memory_limit', '-1') 硬撑，得从读写方式入手：
- 读大文件：用
setReadDataOnly(true)跳过样式、公式解析；用setLoadSheetsOnly(['Sheet1'])只读指定表 - 写大文件：避免逐单元格
$sheet->setCellValue()，改用fromArray()批量写入二维数组 - 终极方案：启用缓存，例如
$cache = PhpOffice\PhpSpreadsheet\Settings::setCache([/* 缓存驱动 */])，推荐MemoryGZip或ICache（需额外装ext-apcu）
还有个隐藏坑：Windows 下用 fopen 写 .xlsx 文件时，若路径含中文或空格，save() 可能静默失败。建议统一用英文路径 + tmpfile() 中转再重命名。
