PHP实现文件上传进度实时显示方案

Evan

发布时间：2026-10-14| 4人浏览过

原创

针对Web开发中常见的文件上传场景，本文介绍了如何通过PHP内置的Session上传进度监控功能，配合前端AJAX请求，实现文件上传进度的实时显示与反馈。

原理概述

PHP提供了 session.upload_progress 机制，允许在会话（Session）中存储文件上传的进度信息。当开启此功能后，PHP会在处理上传时自动将已处理的字节数等信息写入当前用户的 Session 数据中。前端通过定期向服务器发送非上传类的请求（通常是AJAX），读取该Session数据，从而计算出当前的上传百分比。

环境准备与配置

在使用该功能前，必须确保PHP环境正确启用了相关配置。通常这些选项位于 php.ini 文件中：

session.upload_progress.enabled = On：启用上传进度监控。
session.upload_progress.cleanup = On：上传完成后清理进度数据，节省内存。
session.upload_progress.prefix = "upload_"：Session变量名的前缀。
session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"：触发进度记录的表单字段名。
session.upload_progress.freq = "1KB"：更新进度的频率。

实现步骤

第1步：获取配置参数

首先，通过PHP函数获取配置文件中的前缀和字段名称，以便后续生成正确的隐藏字段和查询键值。这在代码中通过 ini_get() 实现：

$prefix = ini_get('session.upload_progress.prefix');
$name   = ini_get('session.upload_progress.name');
$key    = $prefix . $name;

第2步：构建上传表单

创建HTML表单，注意必须设置 enctype="multipart/form-data"。最关键的是添加一个隐藏的输入框，其 name 属性必须严格匹配配置中的 $name 值，这样PHP才能识别这是我们要监控的上传会话：

<form action="index.php" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="<?php echo $name; ?>" value="test">
  <input type="file" name="file"><br>
  <input type="submit" value="提交">
  <input type="button" value="获取信息" onclick="getUploadInfo()">
</form>

第3步：后端逻辑处理

后端脚本需同时处理两种请求：

文件上传请求：正常接收文件，并通过输出JavaScript变量告知前端当前处于“进行中”或“已完成”状态。
进度查询请求：当用户点击“获取信息”时，返回当前Session中的进度JSON数据。

核心PHP代码如下：

<?php
$prefix = ini_get('session.upload_progress.prefix');
$name   = ini_get('session.upload_progress.name');
$key    = $prefix . $name;
session_start();

if (isset($_POST['get_info'])) {
  // 提取查询标识符
  $logo = $prefix . $_POST['logo'];
  // 检查Session中是否存在进度数据并返回JSON
  if (isset($_SESSION[$logo])) {
      exit(json_encode($_SESSION[$logo]));
  } else {
      exit('{}');
  }
} elseif (!empty($_FILES)) {
  // 如果是文件上传请求，标记上传完成标志
  echo '<script>var finashed = true;</script>';
}
?>

第4步：前端轮询与进度计算

使用 jQuery 发起 AJAX POST 请求获取进度。通过比较 bytes_processed（已处理字节）与 content_length（总字节数）来计算百分比：

<script src="jquery.js"></script>
<script>
var sto = null;
function getUploadInfo()
{
  $.post("index.php", {"get_info": 1, "logo": "test"}, function(data)
  {
    try {
      data = JSON.parse(data);
      if (data.bytes_processed && data.content_length) {
          var progress = parseInt(parseInt(data.bytes_processed) * 100 / parseInt(data.content_length));
          document.getElementById("show_info_div").innerHTML = progress + "%";
      }
    } catch(e) { console.log(e); }
    
    // 持续轮询，除非上传真正结束
    if (!window.finashed) {
        setTimeout(getUploadInfo, 1000);
    }
  });
}

// 监听上传完成后的全局变量
if (typeof(finashed) !== "undefined") {
    document.getElementById("show_info_div").innerHTML = "100.00% (上传成功！)";
}
</script>

第5步：结果显示

在页面预留 id="show_info_div" 的区域用于动态插入计算的进度文本，实现用户可见的反馈。

注意事项与排错

文件大小限制：请根据服务器性能调整 php.ini 中的 upload_max_filesize 和 post_max_size。过大的文件（如GB级）可能导致超时或内存溢出，建议测试时使用适中大小的文件。
安全性：session.upload_progress 的数据存储在Server端Session中，只要保持默认配置，不存在显著的安全泄露风险。
兼容性：该功能依赖 PHP 5.4+ 版本及标准 Session 处理程序。