纯JS/AJAX与PHP异步文件上传失败问题求助（需无页面刷新）

问题现象 #

• 按钮设为type="button"（异步模式）：点击后JS提示框正常弹出，但文件无法上传，PHP端未生成记录$_FILES的var_export文件；
• 不设置按钮type（同步模式）：表单正常提交并刷新页面，文件上传成功，PHP端生成对应记录文件；
• 页面加载时$_FILES未定义的警告属于预期现象。

核心排查点与修复方案 #

1. 检查AJAX请求的FormData构造 #

异步上传文件必须用FormData封装表单数据，绝对不能手动设置Content-Type——浏览器会自动处理为multipart/form-data并添加正确的边界符，手动设置会导致后端无法解析文件。

错误示例（常见坑）：

// 错误：手动设置Content-Type导致请求格式异常
xhr.setRequestHeader('Content-Type', 'multipart/form-data');

正确写法：

function uploadFile() {
  const form = document.getElementById('upload-form');
  const formData = new FormData(form);

  const xhr = new XMLHttpRequest();
  xhr.open('POST', 'upload.php', true);

  // 不要添加任何Content-Type相关的请求头
  xhr.onload = function() {
    xhr.status === 200 ? alert('上传完成') : alert('上传失败');
  };

  xhr.send(formData);
}

2. 确认表单enctype属性 #

表单必须声明enctype="multipart/form-data"，否则即使同步能传，异步请求也无法携带文件：

<form id="upload-form" enctype="multipart/form-data">
  <input type="file" name="upload-file">
  <button type="button" onclick="uploadFile()">异步上传</button>
</form>

3. 排查PHP端接收逻辑 #

确保PHP脚本正确处理$_FILES，且文件写入路径有权限：

<?php
// 先判断是否有文件上传再处理
if (!empty($_FILES['upload-file'])) {
  // 记录$_FILES到文件（确保路径可写）
  file_put_contents('files_log.txt', var_export($_FILES, true) . PHP_EOL, FILE_APPEND);
  
  // 示例：移动上传文件到目标目录
  $targetDir = 'uploads/';
  // 确保目录存在
  if (!is_dir($targetDir)) mkdir($targetDir, 0755, true);
  $targetFile = $targetDir . basename($_FILES['upload-file']['name']);
  move_uploaded_file($_FILES['upload-file']['tmp_name'], $targetFile);
  
  echo '上传成功';
} else {
  echo '无有效文件上传';
}
?>

• 执行chmod 755 uploads确保上传目录有写入权限；
• 检查files_log.txt的权限，确保PHP进程能写入该文件。

4. 用开发者工具调试请求 #

打开浏览器F12开发者工具的「网络」面板，查看AJAX请求的：

• 状态码：是否为200，若为404/500需排查路径或PHP报错；
• 请求头：确认Content-Type是multipart/form-data; boundary=xxx格式；
• 响应内容：查看PHP返回的具体信息，定位后端是否有报错。

也可以在JS中添加错误监听：

xhr.onerror = function() {
  console.error('请求发生网络错误');
};

xhr.onreadystatechange = function() {
  if (xhr.readyState === 4) {
    console.log('响应状态:', xhr.status);
    console.log('响应内容:', xhr.responseText);
  }
};

5. 确认事件绑定正确性 #

避免内联onclick的潜在问题，改用事件监听确保函数触发：

document.querySelector('button[type="button"]').addEventListener('click', uploadFile);

总结 #

最常见的问题是未正确使用FormData或手动设置Content-Type导致请求格式错误，其次是表单enctype缺失、PHP端权限不足。通过浏览器网络面板可以快速定位请求是否正常发送、数据是否正确传递。

内容的提问来源于stack exchange，提问作者P. James Norris