PHP图片上传失败排查：move_uploaded_file无法移入uploads目录

API 探路者

2026-8-6

XAMPP环境下图片上传失败原因排查

在XAMPP的htdocs目录下实现图片上传功能，已遵循move_uploaded_file使用规范，但图片无法移动到当前目录下的uploads文件夹，代码如下：

<?php 
   if(isset($_POST['submit'])){
      $allowed_ext = array('png', 'jpg', 'jpeg', 'gif');

      if(!empty($_FILES['upload']['name'])){
        print_r($_FILES);
        $file_name = $_FILES['upload']['name'];
        $file_size = $_FILES['upload']['size'];
        $file_tmp = $_FILES['upload']['tmp_name'];
        $target_dir = "uploads/{$file_name}";

        // Get file ext
        $file_ext = explode('.', $file_name);
        $file_ext = strtolower(end($file_ext));

        // Validate file ext
        if(in_array($file_ext, $allowed_ext)) {
            // verify size
            if($file_size <= 1000000) { // 1000000 bytes = 1MB
              // Upload file
              move_uploaded_file($file_tmp, $target_dir);
              $message = '<p style="color: green;">File uploaded!</p>';
            } else {
                $message = '<p style="color: red;">File to large</p>';
            }
        } else {
          $message = '<p style="color: red;">Invalid file type</p>';
        }
      } else {
        $message = '<p style="color: red;">Please choose a file</p>';
      }
   }
?>


<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Upload</title>
</head>
<body>
    <?php echo $message ?? null; ?>
    <form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="POST" enctype="multipart/form-data">
    Select image to upload:
    <input type="file" name="upload" />
    <input type="submit" value="submit" name="submit" />
</form>
</body>
</html>

可能的原因及解决方法：

uploads目录不存在：move_uploaded_file不会自动创建目标目录，先确认当前脚本所在目录下是否有uploads文件夹，没有的话手动创建，或者在代码中添加创建逻辑：
```
if(!is_dir('uploads')) {
    mkdir('uploads', 0755, true);
}
```
目录权限不足：
- Windows系统：右键uploads文件夹，设置「读写」权限，确保Apache进程能写入。
- Linux/macOS系统：执行命令chmod -R 0755 /path/to/htdocs/your-project/uploads，赋予目录可读可写可执行权限。

未检查move_uploaded_file执行结果：当前代码不管移动是否成功都提示上传成功，修改代码增加结果判断，同时输出错误信息：

if(move_uploaded_file($file_tmp, $target_dir)) {
    $message = '<p style="color: green;">File uploaded!</p>';
} else {
    $message = '<p style="color: red;">Failed to move file!</p>';
    print_r(error_get_last()); // 查看具体错误详情
}

文件名问题：
- 若uploads目录已有同名文件，且权限不允许覆盖，会导致移动失败；
- 文件名含特殊字符（中文、空格、特殊符号）可能引发路径解析错误，建议重命名文件：
```
$file_name = uniqid('upload_', true) . '.' . $file_ext; // 生成唯一文件名
$target_dir = "uploads/{$file_name}";
```
PHP配置限制：
- 打开php.ini文件（XAMPP控制面板中Apache模块的「Config」→「PHP (php.ini)」），检查upload_max_filesize和post_max_size是否大于你要上传的文件大小，比如设置为2M；
- 确认file_uploads设置为On，若为Off则文件上传功能被禁用；
- 查看$_FILES['upload']['error']的值，对应错误码可快速定位问题：
  - 1：文件大小超过upload_max_filesize限制
  - 2：文件大小超过表单中MAX_FILE_SIZE设置的值
  - 3：文件仅部分被上传
  - 4：没有选择上传文件
  - 6：找不到临时目录
  - 7：文件写入失败
路径解析错误：相对路径可能因脚本执行位置导致解析错误，改用绝对路径测试：
```
$target_dir = __DIR__ . "/uploads/{$file_name}"; // __DIR__代表当前脚本所在目录的绝对路径
```

内容的提问来源于stack exchange，提问作者Kurt Math