先说那个「CSV 只有表头」的故障。代码大致是:查询结果拼进一个字符串,用 file_put_contents() 写到 export.csv,然后把路径返回给前端下载。本地是 Windows,Apache 用管理员账号跑,写进了当前目录;线上是 Linux,FPM 的 worker 以 www-data 运行,file_put_contents() 返回了 false,但代码没检查返回值,接口照样回了「导出成功」,用户下到的是一个之前留下的空文件。表头是模板里写死的,数据一行都没有。
第二个故障更直接:把整个上传文件 file_get_contents() 读进内存再处理。memory_limit 是 128M,文件一大就 fatal。PHP 的致命错误不会抛异常,请求直接中断,前端看到的是 500 或者一个被截断的响应。
这两个故障的共同点:代码语法都没问题,错在对「文件」这套东西的假设。路径不是普通字符串,读写不是无代价的,权限不是代码能绕过的,文件名也不是所有系统都用同一种编码。这篇按这四条展开,最后给一个边读边写、内存占用固定的导出实现。
www-data、/var/www、chmod 的段落仍按 Linux 部署说明,Windows 无法验证。相对路径按谁算
这是 PHP 文件问题里最常见的一条。相对路径不是相对当前 PHP 文件,而是相对进程的当前工作目录。FPM 下这个目录通常是 PHP 安装时指定的,或者 FPM 配置里的 chdir;CLI 下则是你执行命令时所在的目录。同一段代码,CLI 跑和网页跑,可能读写到两个完全不同的文件。
所以项目里应当遵守一条规则:所有路径都从 __DIR__(当前文件所在目录)或配置里的绝对根目录出发,不要写 ./data/cache 这种。需要展示或记录时,用 getcwd() 打印当前工作目录,一眼就能看出问题。realpath() 能把 .. 和符号链接解析成绝对路径,但文件不存在时它返回 false,别直接拿结果拼接。
<?php
// 不推荐:跟随进程工作目录
$log = './storage/app.log';
// 推荐:以当前文件为锚点
$log = __DIR__ . '/../storage/app.log';
// 排查时把这两行打出来
var_dump(getcwd(), realpath($log));
「跑什么、看到什么算通过」:在 CLI 里先 cd 到项目根跑一次,再 cd /tmp 跑一次,如果两次 getcwd() 不同而文件内容写到了不同位置,就复现了这个问题。改成 __DIR__ 之后,两次输出应当指向同一个文件。
路径还有一个安全面:只要路径里有用户输入,就必须防目录穿越。用户传 ../../etc/passwd 时,光过滤 .. 不够,编码、反斜杠、多余斜杠都能绕过。稳的做法是先用 basename() 把路径压成一个文件名,再拼到固定目录;或者解析出绝对路径后检查它是否仍在允许的根目录之内。
分隔符也别自己发明规则。PHP 在 Windows 上接受正斜杠,Linux 只认正斜杠;反斜杠在 PHP 字符串里还是转义符,写 "C:\data\new" 会把 \n 解释成换行。拼路径统一用 /,需要展示给 Windows 用户时再用 DIRECTORY_SEPARATOR 或 str_replace() 转换。盘符、网络映射盘这类东西不要写进代码,它们应该来自配置。
还有一个比「路径算错」更隐蔽的问题:权限检查的结果会被 PHP 缓存。同一个请求里先 is_writable() 再改权限,第二次判断仍是旧值,因为 stat 系列函数缓存了文件状态。改完权限、删完文件、重命名之后,如果要立刻再查,先调用 clearstatcache()。这类缓存是为了减少系统调用,单请求里读写同一文件很多次时确实省时间,但排查时经常让人怀疑人生。
三套读写接口,代价完全不同
PHP 操作文件有三层接口,很多人混着用,出事时说不清数据在哪。
整文件接口
file_get_contents()、file_put_contents()。一行搞定,但会把整个文件读进内存或先在内存里拼好再写。适合配置文件、几 MB 以内的文本。
流接口
fopen() 配 fread()、fwrite()、fgets()。自己控制每次读多少,内存占用只跟缓冲区有关,适合日志、CSV、上传下载。
第三层是 SplFileObject,把文件包成可遍历对象,适合按行处理;它底层仍是流,只是写法更面向对象。三层最终都落到同一套系统调用,差别在于「谁来决定一次搬多少字节」。
还有一个容易忽略的点:file_put_contents() 默认不是原子写。它先打开、再写入、再关闭,进程在中途被杀,目标文件就可能是半截。要原子替换,得自己写临时文件再改名,后面会讲。
流接口最怕忘记关闭句柄。FPM 的 worker 是常驻进程,请求结束后 PHP 会回收本次请求打开的资源,所以单个请求泄漏通常不会跨请求累积;但一个请求里循环打开几千个文件不关,仍然会撞到进程级的文件描述符上限,报的错误是 Too many open files,看起来像文件系统坏了。批量处理时把 fopen() 放在循环内、fclose() 放在循环末尾,异常路径用 finally 兜住。
<?php
$data = ['id' => 1, 'name' => '科设'];
// 整文件写:简单,但内容全在内存里
file_put_contents(__DIR__ . '/config.json', json_encode($data, JSON_UNESCAPED_UNICODE));
「跑什么、看到什么算通过」:把 file_put_contents() 的返回值打印出来,成功时是写入字节数,失败时是 false。很多人只看文件「好像生成了」,不看返回值,权限问题时就会误判。
大文件只能流式处理
判断标准很简单:文件大小可能超过 memory_limit 的十分之一,就别整文件读。导出 CSV 是典型场景,几十万行放进数组,再加上 json_encode() 的副本,128M 很快就满。
正确做法是打开一个输出流,边查边写,每批处理完就释放。注意 fputcsv() 会自己处理引号和换行,别手工拼字符串。查询端也要分批,用 LIMIT 翻页或者游标,别一次 fetchAll()。
<?php
$out = fopen(__DIR__ . '/export.csv', 'wb');
if ($out === false) {
throw new RuntimeException('无法创建导出文件');
}
fputcsv($out, ['订单号', '金额', '状态'], ',', '"', '\\');
$pdo = new PDO($dsn, $user, $pass, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$stmt = $pdo->query('SELECT id, amount, status FROM orders ORDER BY id');
while ($row = $stmt->fetch(PDO::FETCH_NUM)) {
fputcsv($out, $row, ',', '"', '\\');
}
fclose($out);
「跑什么、看到什么算通过」:造 50 万行假数据,把 memory_limit 设成 64M 再跑。整文件写法会在中途 fatal,流式写法应当正常结束,并且用 memory_get_peak_usage(true) 打印峰值,数值不随行数线性增长。
把量级摊开看更清楚。假设每行 80 字节,50 万行是 40MB;先 fetchAll() 成数组,PDO 会把每列再包成字符串,内存至少翻一倍;再拼成一个字符串写出去,又是一份副本。三道叠加,128M 的 memory_limit 很容易到顶。流式写法里,同一时刻只有一行数据和几十 KB 的数据库缓冲,峰值基本是常数。判断要不要改,不用等线上 fatal:本地把行数放大十倍,看峰值内存是不是跟着线性涨,涨就说明有整批数据驻留。
流式导出还有一个容易漏的收尾:fclose() 失败、查询中途异常、客户端断开,都会留下半个文件。既然写了临时文件加 rename,就把异常路径也包进去,失败时删掉临时文件;成功改名之后,才算这次导出真的完成。数据库连接、语句对象该释放的释放,长事务还会占着锁,别为了导出把线上写入拖住。
下载场景还有一层:如果文件已经生成在磁盘上,别读进内存再 echo,用 readfile(),它按块输出。输出前关掉输出缓冲,避免整个响应被 PHP 攒在内存里;大文件还要考虑 set_time_limit(0),否则脚本会在默认 30 秒时被砍断,用户拿到半个文件。
临时文件与原子替换
「先写临时文件,再改名到目标」是文件系统里少数既简单又可靠的模式。它保证读的人要么看到完整的旧文件,要么看到完整的新文件,不会读到写了一半的内容。配置缓存、导出文件、上传落盘都适用。
三个细节决定它是否真的可靠。第一,临时文件必须和目标在同一个目录或同一个文件系统,跨文件系统的 rename() 会退化成复制加删除,不再原子。第二,flush 和关闭的顺序要在目标平台实测:本机 Windows 11 + PHP 8.3.36 上是先 fflush()、句柄仍打开时 rename() 就返回 true 并覆盖成功;第二次 rename 失败只是因为临时文件已被改名移走(系统找不到指定的文件),不是因为句柄。第三,覆盖行为同样要在目标平台验证,Linux 上通常是原子的,Windows 上本机实测可以覆盖。
<?php
$target = __DIR__ . '/cache/orders.json';
$tmp = $target . '.tmp.' . bin2hex(random_bytes(4));
if (file_put_contents($tmp, $json) === false) {
throw new RuntimeException('临时文件写入失败');
}
if (!rename($tmp, $target)) {
@unlink($tmp);
throw new RuntimeException('替换失败');
}
临时目录用 sys_get_temp_dir() 取,不要写死 /tmp。需要「进程结束自动删除」的文件用 tmpfile(),它返回一个句柄,关闭即删;但它的路径不可见,不能拿去给外部程序读。tempnam() 会创建文件并返回路径,注意它也可能落在系统临时目录,和目标的文件系统不一定相同。
flock(),那是下一篇「多进程与文件锁」的内容。权限:Web 进程不是你的终端
在终端里 touch 能建文件,不代表 FPM 能。CLI 用的是你的账号,FPM worker 用的是 www-data(Debian/Ubuntu)或 nginx(部分系统),两者对目录的写权限是分开算的。判断权限别猜,跑一次:
<?php
$dir = __DIR__ . '/storage';
var_dump(is_dir($dir), is_writable($dir), fileowner($dir), posix_geteuid());
「跑什么、看到什么算通过」:is_writable() 返回 true 才说明当前进程能写。注意 PHP 会缓存文件状态,改完权限后同一个请求里再查可能还是旧结果,必要时 clearstatcache()。
目录权限常见配置是目录 0755、需要写的目录 0775 且属组包含 Web 用户,文件 0644。不要用 0777 糊过去,那等于让同机任何账号都能改你的代码。另一个坑是 umask:PHP 创建文件的最终权限是「你给的模式减去 umask」,0666 在 umask 022 下实际是 0644,需要精确控制时用 chmod() 再确认一次。
上传目录还有一条硬规则:不要给执行权限,最好放在 Web 根目录之外,下载时由 PHP 读出再输出。这样即使有人传了 .php 文件,也不会被当成脚本执行。
容器部署会多一层。容器里的进程 UID 和宿主机挂载卷的属主可能对不上,宿主机上明明是 www-data 可写,容器里却是只读。遇到这种情况先看容器实际以哪个 UID 运行,再决定是改卷的属主,还是在镜像里固定用户。启用了 SELinux 或 AppArmor 的机器还有额外的标签和策略,ls -l 看到的权限位正确也不代表能写,日志里会有 Permission denied 而权限位看起来没问题,这时要查审计日志而不是反复 chmod。
编码:三处编码要对齐
文件名和文件内容涉及三种编码,任意两个不一致就会出乱码:文件字节本身的编码、文件系统/压缩包使用的文件名编码、以及浏览器或终端显示时的编码。Linux 的文件系统按字节存名字,本身不管编码;Windows 和 ZIP 传统上用本地代码页,中文常见 GBK。
内容层面,UTF-8 应当是默认。读外部文件时先探测,再转换:mb_detect_encoding() 不可靠但聊胜于无,已知是 GBK 就直接 mb_convert_encoding($s, 'UTF-8', 'GBK')。写 CSV 给 Excel 用时,BOM 是个现实问题:带 BOM 的 UTF-8 在 Excel 里能正确识别中文,但某些程序会把 BOM 当成第一个字段的一部分。要么统一约定,要么在读取端剥掉。
BOM 是文件开头那三个字节 EF BB BF,肉眼看不见。判断一个文件有没有 BOM,读前三个字节比较即可;剥掉时按字节截断,别用 ltrim() 的字符集参数:
<?php
$bom = "\xEF\xBB\xBF";
$content = strncmp($content, $bom, 3) === 0 ? substr($content, 3) : $content;
ltrim($content, "\xEF\xBB\xBF") 看起来也能去掉,但它会把开头任意一个属于这三个字节的字符都删掉,可能多删数据。更麻烦的是内容本身不是 UTF-8 的情况:一个 GBK 文件用 UTF-8 的函数去截取,可能把汉字切成半个,后面所有内容都乱。处理顺序应当是先确定编码、转成 UTF-8,再做字符串操作,不要反过来。
文件名层面,导出 ZIP 时如果压缩包里有中文名,用 ZipArchive 要留意它是按字节写名字的,接收方解压可能乱码。跨平台交付时,最稳的是文件名只用 ASCII,中文放进内容或清单文件里。
\r。用 fgetcsv() 一般能处理,自己 explode("\n") 就要手动 rtrim($line, "\r")。现象、真实原因、第一步查什么
文件问题的现象离原因通常很远,先按这张表分流,再动代码。
| 你看到的现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 导出文件只有表头,或下载到旧文件 | 写入失败但没检查返回值,接口仍然返回成功 | 打印 file_put_contents() 返回值与 is_writable() |
| 本地能写,线上报权限错误 | CLI 用户与 FPM 用户不同,目录属主或权限不对 | posix_geteuid()、fileowner()、目录权限位 |
| 文件写到了意想不到的目录 | 相对路径按进程工作目录解析 | getcwd() 与 realpath() 的实际值 |
| 大文件处理时报内存耗尽 | 整文件读入内存,或一次性 fetchAll() | memory_get_peak_usage(true);改用流和分批查询 |
| 下载到一半中断,文件不完整 | 脚本超时、输出缓冲、客户端断开 | 看 max_execution_time、connection_aborted()、日志里的超时记录 |
| 中文文件名解压后乱码 | 压缩包按本地代码页写名,解压端按 UTF-8 读 | 用十六进制查看压缩包内的文件名字节 |
| 改名时报权限或占用 | 目标仍被自己的句柄或其他进程占用 | 确认流已 fclose();Windows 上用句柄工具查占用 |
| 同一个请求里权限判断结果不对 | PHP 缓存了文件状态 | 改权限后调用 clearstatcache() 再查 |
边界与代价
- 流式读写换来了代码复杂度。要自己管句柄、异常路径上也要关闭。用
try/finally包住,别指望脚本结束一定释放。 - 原子替换只保证「看到完整文件」,不保证掉电后数据还在。要抗掉电得让文件系统真正落盘,PHP 没有直接的 fsync 接口,通常靠数据库或对象存储解决。
- 文件锁、权限、编码都是平台相关的。同一套代码在 Windows 和 Linux 上行为可能不同,跨平台项目必须两边各测一次。
- 把文件放在 Web 根目录下最省事,也最危险。上传目录尤其要移出去,或者至少禁止脚本执行。
- PHP 的文件函数大多返回
false而不是抛异常。项目里要么统一封装成抛异常,要么每处都检查,不能一半一半。
当天能自己验证的练习
- 在 CLI 里从两个不同目录执行同一段写相对路径的脚本,打印
getcwd()和落盘位置,再把路径改成__DIR__对比。 - 把
memory_limit设为64M,分别用file_get_contents()和fopen()加循环处理一个 200MB 文件,记录峰值内存。 - 写一个「临时文件加 rename」的配置写入函数,故意在写入后不
fclose(),在 Windows 上看 rename 是否失败,再改回来。 - 用
is_writable()、fileowner()、posix_geteuid()写一个权限自检页,分别在 CLI 和 FPM 下访问,记录差异。 - 生成一个含中文文件名的 ZIP,分别用系统解压工具和 PHP 的
ZipArchive解压,观察文件名是否一致。
小结
三句话:相对路径按进程工作目录算,项目里一律从 __DIR__ 或配置的绝对根出发;大文件用流、分批查询,别让整个文件进内存;写完先落到同目录临时文件,关闭后再 rename,权限和编码都要在目标平台上实测。
文件能可靠读写了,下一步是把数据从本机搬到别的机器:调用第三方接口、建立 TCP 连接、处理超时与重试。下一篇讲 PHP 的网络通信,重点是一个「偶发超时后重试,结果扣了两次款」的真实场景。