vichuploaderbundle 在 symfony 5.4 中实现图片自动存储，核心是通过实体注解绑定上传行为、yaml 配置 mapping（如 uri_prefix、upload_destination、namer）、使用 vichimagetype 表单类型及 vich_uploader_asset twig 函数安全展示图片。
在 Symfony 5.4 中使用 VichUploaderBundle 实现图片文件自动存储，核心是把“上传行为”从控制器逻辑中剥离，交由 Bundle 自动接管：实体变更触发文件移动、表单提交即完成保存、路径与 URL 生成全托管。
配置适配器与映射关系
VichUploaderBundle 不直接处理存储，而是依赖 Doctrine 实体字段的注解来绑定上传行为。你需要先定义一个 mapping 名称（如 product_image），再在 config/packages/vich_uploader.yaml 中配置它：
-
uri_prefix：对外访问图片的 URL 前缀，例如
/uploads/products -
upload_destination：服务器上的物理路径，推荐用
%kernel.project_dir%/public/uploads/products -
namer：控制文件名生成方式，
vich_uploader.namer_uniqid可避免重名，也可自定义服务实现日期+哈希等逻辑 -
inject_on_load 设为
false，避免每次 hydrate 实体都去读取文件系统
实体中声明上传字段
在 Product 实体里添加一个普通字符串字段（如 $imageName）用于存文件名，并用 @Vich\UploadableField 注解绑定上传行为：
- 注解中的
mapping必须和 YAML 配置里的 mapping 名称一致（如"product_image"） - 同时加
@ORM\Column(type="string", nullable=true)，让 Doctrine 知道该字段要持久化到数据库 - 别忘了加
@Vich\Uploadable类注解，启用自动时间戳更新能力
表单与控制器零额外编码
创建表单时，对上传字段使用 VichImageType::class（不是 FileType）：
- 表单会自动渲染
<input type="file">，并正确设置enctype="multipart/form-data" - 提交后，Bundle 在
preSubmit和postPersist事件中自动调用move()，把临时文件移到upload_destination - 控制器只需正常处理
$form->handleRequest($request)和$em->flush()，无需手动处理$_FILES或move_uploaded_file
模板中安全展示图片
不要拼接路径，而是用 Bundle 提供的 Twig 函数：
-
{{ vich_uploader_asset(product, 'imageFile') }}返回完整 URL，如/uploads/products/abc123.jpg - 若配合 LiipImagineBundle，可链式调用缩略图：
{{ vich_uploader_asset(product, 'imageFile') | imagine_filter('admin_thumbnail') }} - 确保 Nginx/Apache 已配置
public/uploads目录可被 Web 直接访问（不走 PHP 路由）
