PHP stream_filter_append 怎样增量转换大文件

处理几百 MB 的文本时，直接使用 file_get_contents() 再转换，峰值内存会随着文件增长；更稳妥的做法是把过滤器挂到输出流，让数据在复制过程中按块转换。PHP 的 stream_filter_append() 负责把过滤器加入流的过滤器链，STREAM_FILTER_WRITE 决定转换发生在写出方向。

官方手册：https://www.php.net/manual/en/function.stream-filter-append.php

用输出过滤器把转换放进复制链

下面的示例把 UTF-8 文本写成 GB18030。转换发生在写入目标文件时，stream_copy_to_stream() 只负责持续搬运剩余数据，因此没有创建整文件字符串。

这个方向的判断很重要：过滤器挂在 $target 上并指定写模式，输入仍保持原编码，输出文件才接收转换后的字节。过滤器名称中的输入、输出编码必须与真实文件一致，不能把“文件扩展名”当成编码依据。

读过滤器与写过滤器的边界

stream_filter_append() 默认会根据打开模式选择读链或写链，但在迁移脚本中最好显式传入模式。读过滤器适合让后续 PHP 代码直接消费转换后的文本；写过滤器适合把转换结果落到新文件、响应流或压缩流。

官方手册还特别说明，读写各挂一个过滤器时会创建两个实例，不能把一次调用的返回值当成双向控制句柄。若要移除过滤器，也应保留对应返回资源；单纯关闭流通常更适合一次性转换任务。

大文件转换的内存和结果检查

“增量”并不等于可以忽略错误。至少检查三层：输入和输出是否打开、过滤器是否创建、复制是否返回 false。复制字节数是字节而非字符，中文文件不能拿它直接当行数或字符数。

如果只是转换本地大文本，stream_copy_to_stream() 是简洁选择；如果需要逐行校验、统计坏行或按业务规则替换内容，则应使用 fread() 循环，把小块交给处理函数，再写入目标流。这样可以控制业务缓冲区，但要注意多字节字符可能跨块，不能简单按字节截断 UTF-8 字符。

哪些场景不适合直接追加编码过滤器

第一，JPEG、ZIP 等二进制内容不应进行字符集转换；第二，输入编码未知或一份文件混有多种编码时，过滤器无法替你判断每个字节的语义；第三，需要原地覆盖且同时依赖随机定位时，另写临时文件、完成校验后再替换通常更安全。远程 socket 还要考虑超时、半关闭和复制提前结束，不能只看“已经写出了一部分”。

生产迁移可以先记录源文件大小、目标文件大小和错误计数，再抽取少量文本做人工核对。这个检查属于业务验收，不要用“复制成功”替代“内容编码正确”。

常见问题

stream_filter_append 返回 false 怎么办？

先确认传入的是有效流，再确认过滤器名称存在；使用 convert.iconv.* 时还要确认 PHP 启用了 iconv 支持。

为什么指定了 READ 但输出文件仍未转换？

READ 只作用于从该流读出的数据。如果目标是转换后写盘，应把过滤器挂到输出流并使用 STREAM_FILTER_WRITE。

stream_copy_to_stream 会一次性占用整文件内存吗？

它面向流复制，返回复制的字节数；相比先读取全文再转换，它适合把处理保持在流链路中，但下游过滤器自身仍可能保留少量内部缓冲。