Symfony框架下如何实现请求上传图片的分层目录存储

别自己瞎写文件名转数字取模的逻辑，那套方案分布不均匀、冲突率高，后续扩容迁移成本极大，Symfony生态有成熟的规范实现，直接用就行。

一、底层依赖选择 #

Symfony 官方推荐使用 league/flysystem-bundle 作为文件存储抽象层，安装命令：

composer require league/flysystem-bundle

这个组件屏蔽了本地存储、对象存储的底层差异，支持自动递归创建多级目录，不需要手动写目录创建、权限判断的重复逻辑，后续要把图片从本地迁到OSS、S3这类存储服务，不需要改业务代码，换个适配器就行。

二、分片路径生成规则 #

生产环境通用的两层分片逻辑完全能满足百万级图片的存储需求，不会出现单目录文件过多的性能问题，规则如下：

• 放弃用原始文件名做路径计算的思路，避免重名、分布倾斜问题
• 对上传文件的实际内容计算MD5哈希值，用这个哈希值作为文件的唯一标识
• 取哈希值前2位作为一级目录名，第3-4位作为二级目录名，完整哈希加文件后缀作为最终文件名
  这个方案的目录分布是完全均匀的：总共会生成256个一级目录，每个一级目录下256个二级目录，合计65536个二级目录，就算存200万张图片，平均每个二级目录下也就30个左右文件，远低于文件系统单目录性能阈值。而且相同内容的文件哈希值一致，天然支持重复文件去重。

举个路径例子：如果文件内容哈希是f3d25a881bc9763e2a.jpg，最终存储路径就是private/f3/d2/f3d25a881bc9763e2a.jpg，和你给的示例结构完全匹配。

可以在项目里写个简单的路径生成服务：

// src/Service/ImagePathGenerator.php
namespace App\Service;

use Symfony\Component\HttpFoundation\File\UploadedFile;

class ImagePathGenerator
{
    public function generate(UploadedFile $uploadedFile): string
    {
        $fileHash = md5_file($uploadedFile->getRealPath());
        $extension = $uploadedFile->guessExtension() ?: 'jpg';
        $level1Dir = substr($fileHash, 0, 2);
        $level2Dir = substr($fileHash, 2, 2);

        return sprintf(
            '%s/%s/%s.%s',
            $level1Dir,
            $level2Dir,
            $fileHash,
            $extension
        );
    }
}

三、Symfony 内的配置和使用 #

先配置私有图片存储盘，编辑config/packages/flysystem.yaml：

flysystem:
    storages:
        private_image_storage:
            adapter: 'local'
            options:
                directory: '%kernel.project_dir%/private'

上传逻辑里直接注入依赖调用就行，不需要额外处理目录创建：

// 控制器上传逻辑片段
public function uploadPostImage(
    UploadedFile $image,
    ImagePathGenerator $pathGenerator,
    FilesystemOperator $privateImageStorage
): Response
{
    $relativePath = $pathGenerator->generate($image);
    $stream = fopen($image->getRealPath(), 'r');
    $privateImageStorage->writeStream($relativePath, $stream);
    fclose($stream);

    // 数据库存$relativePath即可，不需要额外存冗余的路径前缀
    // ...... 业务逻辑
}

四、为什么不推荐文件名取模方案 #

• 原始文件名重复率极高，比如大量用户上传微信图片_2024xxx.jpg、screenshot.png这类默认命名的文件，转数字后很容易集中在少数模值对应的目录，完全起不到分片效果
• 中文、特殊字符文件名转数字的逻辑如果处理不当，很容易出现路径计算错误、文件覆盖问题
• 取模的目录总数是固定的，后续如果文件量超预期要拆分目录，所有历史文件的路径都要重新计算，数据迁移成本极高

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