PHP fpassthru() 函数详解

词源分解

fpassthru() 由三部分组成：

• f：代表"file"（文件），PHP文件系统函数的通用前缀

• pass：意为"传递"

• thru：是"through"的缩写形式，表示"通过"

组合含义为"将文件内容传递通过（到输出）"

功能

fpassthru() 从打开文件的当前位置开始读取所有数据直到文件末尾(EOF)，并将结果直接写入输出缓冲区（如浏览器或CLI）。它特别适合处理大文件，因为不会将整个文件加载到内存中。

语法结构

int|false fpassthru(resource $file)

参数详解

参数	类型	必需	描述
$file	resource	是	要读取的文件指针，必须是通过fopen()或fsockopen()成功打开且未被关闭的资源23

返回值

• ‌成功时‌：返回从文件读取并传递到输出的字符数

• ‌失败时‌：返回false（如文件指针无效或读取错误）

函数示例与输出

示例1：基本文件输出

$file = fopen("test.txt", "r");
// 跳过第一行
fgets($file); 
// 输出剩余内容
echo fpassthru($file);
fclose($file);

假设test.txt内容：

第一行内容
第二行内容
最后一行

‌输出‌：

第二行内容
最后一行
24  // 表示传递了24个字符:ml-citation{ref="2,3" data="citationList"}

示例2：二进制文件处理

$file = fopen("image.jpg", "rb"); // 注意'b'二进制模式
header("Content-Type: image/jpeg");
fpassthru($file);
fclose($file);

‌输出‌：直接显示JPEG图像

能否直接输出

fpassthru()‌能直接输出内容‌到输出缓冲区，无需额外调用echo或print。这是它与fread()等函数的关键区别。

重要特性补充

1. ‌二进制模式‌：Windows系统处理二进制文件时，必须在fopen()模式中包含'b'（如"rb"）

2. ‌指针位置‌：若已写入文件，需先调用rewind()重置指针位置

3. ‌性能优势‌：相比file_get_contents()+echo的组合，fpassthru()内存效率更高，适合大文件

4. ‌网络流支持‌：可处理http://或ftp://等网络流

5. ‌输出控制‌：常与ob_start()/ob_end_clean()配合使用管理输出缓冲

与readfile()对比

特性	fpassthru()	readfile()
文件打开方式	需预先fopen()	直接传文件名
指针控制	可从任意位置开始	总是从头开始
适用场景	需要分段处理时	简单输出整个文件时

错误处理建议

$file = fopen("data.log", "r");
if (fpassthru($file) === false) {
    $error = error_get_last();
    echo "输出失败: " . $error['message'];
}
fclose($file);