stream_copy_to_stream 短写怎么配置或排查

PHP 里用 stream_copy_to_stream() 复制上传流、临时流或文件流时，返回值比预期小，通常先不要改成 fwrite() 循环。这个返回值是“本次实际复制的字节数”，小于预期可能只是源流已经被前面的读取动作推进了；只有返回严格等于 false，才是函数报告失败。排查时把源流位置、length、offset 和目标流状态一起记录，定位会快很多。

先把“短写”拆成三个结果

stream_copy_to_stream($from, $to, $length, $offset) 的语义是从源流当前位置，或指定的源流偏移处，最多复制 length 个字节。PHP 8 起 length 可以传 null，代表复制剩余内容。它返回实际复制的字节数，失败时返回 false。

因此要分别看三种结果：返回 false 是失败；返回小于固定 length 的整数，可能是源流剩余数据不足；返回整数但目标文件内容不符合预期，则要检查目标打开模式、过滤器和写入位置。不要用松散比较把 0、false 和字符串混在一起。

最常见的原因是源流已经被读过

这个函数不会自动把源流指针移回开头。比如先读取了文件头，再调用复制，复制的就是剩余部分；对网络请求体这类不可 seek 流，事后也不能可靠地回到开头。能 seek 的文件或 php://temp 流，可以在复制前显式重置：

这里的 fseek() 只适用于支持定位的流。上传请求体、管道或某些远程包装器可能不支持回退；这时应该在第一次读取时就决定由一个组件完整消费，或者先写入可 seek 的临时流，再交给后续逻辑复制。

固定 length 时，别把“剩余不足”当成 API 故障

需要复制固定大小时，把期望值写出来并进行严格比较。例如源流只剩 640 字节，调用时传入 1024，返回 640 并不等于函数一定异常；它说明本次最多只能拿到剩余数据。若业务要求必须得到 1024 字节，就应该把它作为不完整输入处理。

用最小诊断代码锁定边界

排查时可以用 php://temp 构造一个不依赖真实文件的可 seek 流。关键不是盯着一条日志，而是同时输出复制前后的 ftell()、调用参数和返回值。若复制前位置已经是 5，复制结果从第 6 个字节开始，就能确认问题来自读取位置而不是“写少了”。

 $before, 'copied' => $copied, 'after' => $after]);
} finally {
    // 临时流也要显式关闭，避免诊断代码掩盖资源泄漏。
    fclose($from);
    fclose($to);
}

如果必须从开头复制，先对可定位的源流执行 rewind($from) 或 fseek($from, 0, SEEK_SET)，再调用函数。offset 是复制起点参数，不应被当作“自动重置所有状态”的开关；不可定位的流则要调整数据消费顺序。

常见问题

length 传 0 会复制全部内容吗？

不会把 0 当成“全部”。需要复制剩余内容时使用 PHP 8+ 支持的 null，并确认源流当前位置正确。

返回 0 就一定失败吗？

不一定。返回值为整数时表示复制了 0 字节，可能是源流已在 EOF；失败要用 === false 判断。

offset=0 能让源流回到开头吗？

不要依赖它完成重置。对可 seek 流先显式 rewind()，对不可 seek 流则从读取流程上避免重复消费。

这类问题的稳定排查顺序是：先看返回值类型，再看复制前源流位置，然后核对 length 与业务期望，最后检查目标流模式和关闭时机。把“实际复制了多少”与“业务必须得到多少”分开，短写就不再是模糊现象。