React中CKEditor 5结合Laravel图片上传失败问题排查

是否需要安装Laravel相关包？ #

不需要额外安装特定的Laravel包，你已经能成功将图片保存到指定路径，说明基础的文件上传逻辑已经正常工作。问题大概率出在前后端数据交互的格式、权限或配置细节上。

排查步骤： #

• 检查后端返回的JSON格式是否符合CKEditor要求
  CKEditor 5的CKFinder上传接口强制要求返回包含特定字段的JSON：

  • uploaded: 布尔值，必须为true表示上传成功
  • url: 图片可访问的完整URL（比如http://your-domain/storage/xxx.jpg）
    正确返回示例：

  {
    "uploaded": true,
    "url": "http://your-app.com/storage/images/20240520.jpg"
  }
  

  如果后端返回的格式缺失这两个字段，或者字段名错误，前端会直接判定上传失败。

• 确认图片URL的可访问性
  后端保存图片后，要确保前端能正常访问该URL：

  1. 如果图片存在storage/app/public目录下，必须先创建软链接：

     php artisan storage:link
     

     这样才能通过/storage/xxx.jpg的路径访问到文件。
  2. 检查服务器的文件权限，确保存储目录有可读权限。

• 排查跨域问题
  如果React项目和Laravel后端不在同一域名下，需配置Laravel的CORS：

  1. 修改config/cors.php，允许前端域名的请求：

     return [
         'paths' => ['api/*'],
         'allowed_methods' => ['*'],
         'allowed_origins' => ['http://your-react-app-domain'],
         'allowed_headers' => ['*'],
     ];
     

  2. 确保\App\Http\Middleware\HandleCors::class已加入app/Http/Kernel.php的api中间件组。

• 检查前端CKEditor的请求配置

  1. 确认uploadUrl路径是否正确，避免拼写错误或多余的斜杠。
  2. 如果Laravel开启了CSRF保护，必须在请求头中携带CSRF令牌：

     ClassicEditor.create(document.querySelector('#editor'), {
         ckfinder: {
             uploadUrl: '/api/upload',
             headers: {
                 'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content')
             }
         }
     })
     

• 确认后端返回的HTTP状态码
  后端返回响应时必须使用200 OK状态码，CKEditor会根据状态码结合返回内容判断上传结果。示例代码：

  return response()->json([
      'uploaded' => true,
      'url' => asset('storage/images/' . $filename)
  ], 200);
  

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