配置API Platform文件上传时添加#[Vich\Uploadable]仍报错的解决

下面针对你遇到的问题，列出几种常见原因及对应的解决步骤：

1. API Platform资源未配置上传支持 #

仅添加Vich注解不足以让API Platform识别该实体支持上传操作，必须在MediaObject类的#[ApiResource]注解中明确配置支持文件上传的POST操作：

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Symfony\Controller\FileUploadController;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
        new Post(
            uriTemplate: '/media_objects',
            controller: FileUploadController::class,
            deserialize: false,
            openapiContext: [
                'requestBody' => [
                    'content' => [
                        'multipart/form-data' => [
                            'schema' => [
                                'type' => 'object',
                                'properties' => [
                                    'file' => [
                                        'type' => 'string',
                                        'format' => 'binary'
                                    ]
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        )
    ]
)]
#[Vich\Uploadable]
class MediaObject
{
    #[Vich\UploadableField(mapping: 'media_object', fileNameProperty: 'fileName')]
    public ?File $file = null;

    #[ORM\Column(nullable: true)]
    public ?string $fileName = null;

    // 其他字段与方法...
}

核心是通过Post操作指定FileUploadController、设置deserialize: false，并在openapiContext中定义multipart/form-data的请求结构。

2. VichUploaderBundle映射配置不匹配 #

即使使用attribute模式，也需要确保config/packages/vich_uploader.yaml中的映射名称与实体注解完全一致：

vich_uploader:
    db_driver: orm
    storage: filesystem
    mappings:
        media_object:
            uri_prefix: /media
            upload_destination: '%kernel.project_dir%/public/media'

注意实体中#[Vich\UploadableField(mapping: 'media_object')]的mapping参数，必须和yaml里的映射名称完全对应。

3. Symfony缓存未更新 #

注解配置变更后，旧缓存可能导致新配置未被识别，执行缓存清除命令：

php bin/console cache:clear

生产环境需追加--env=prod参数。

4. 请求格式错误 #

确保curl请求使用multipart/form-data格式，且参数名与实体中的file字段一致：

curl -X POST -H "Content-Type: multipart/form-data" -F "file=@/本地文件路径/xxx.jpg" http://localhost/api/media_objects

如果参数名不是file，API Platform无法识别上传的文件。

5. 实体缺少必要的更新逻辑（可选但建议） #

VichUploaderBundle依赖更新时间字段触发上传后的实体更新，建议添加相关字段与方法：

#[ORM\Column(type: 'datetime_immutable', nullable: true)]
public ?\DateTimeImmutable $updatedAt = null;

public function setFile(?File $file = null): void
{
    $this->file = $file;
    if (null !== $file) {
        $this->updatedAt = new \DateTimeImmutable();
    }
}

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