React项目中Wavesurfer.js读取Firebase Storage音频遇CORS问题

问题背景 #

在React应用中使用Wavesurfer.js从Firebase Storage获取音频文件时遭遇CORS问题：原生HTML5 <audio>标签可正常播放同一份音频，无CORS报错，但Wavesurfer.js加载该音频时触发CORS错误（本地加载音频文件正常）。

错误信息 #

Access to fetch at 'https://firebasestorage.googleapis.com/...' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

已完成配置 #

已设置Firebase Storage规则允许读取权限，且HTML5音频播放无异常：

service firebase.storage {
  match /b/{bucket}/o {
    match /{allPaths=**} {
      allow read;
      allow write: if request.auth != null &&
                   request.resource.size < 10 * 1024 * 1024 &&
                   request.headers.origin == 'http://localhost:3000';
    }
  }
}

尝试在Wavesurfer的XHR配置中添加mode: 'cors'，问题仍未解决：

useEffect(() => {
  waveSurferRef.current = WaveSurfer.create({
    container: containerRef.current,
    waveColor: ["#eadfff", "#024bff"],
    progressColor: ["#024bff"],
    cursorColor: "#024bff",
    xhr: {
      cache: "default",
      mode: "cors",
      method: "GET",
      credentials: "include",
      headers: [
        { key: "cache-control", value: "no-cache" },
        { key: "pragma", value: "no-cache" },
      ],
    },
    responsive: true,
    height: 50,
    normalize: true,
    barMinHeight: 100,
    partialRender: true,
  })
})

核心疑问 #

1. 即便Firebase Storage规则配置正确，Wavesurfer.js获取音频的方式是否存在特殊点导致CORS问题？
2. Wavesurfer.js与Firebase Storage结合使用时，是否有额外注意事项或配置要求？
3. React应用中使用Wavesurfer.js加载音频，有哪些兼容CORS的解决方案或最佳实践？

解决方案 #

1. 理解请求差异 #

HTML5 <audio>标签加载跨域资源时，部分浏览器采用简单请求模式，无需严格CORS校验；但Wavesurfer.js通过fetch/XMLHttpRequest读取音频二进制数据绘制波形，属于非简单请求，会触发OPTIONS预检请求，要求服务器返回正确的Access-Control-Allow-Origin等响应头。

注意：Firebase Storage的权限规则和CORS配置是两个独立模块——规则控制资源访问权限，CORS配置控制跨域请求的响应头。你之前仅配置了权限规则，未正确设置CORS策略。

2. 配置Firebase Storage的CORS策略 #

通过gsutil工具给存储桶设置CORS配置：

1. 创建cors.json文件：

[
  {
    "origin": ["http://localhost:3000"],
    "method": ["GET"],
    "maxAgeSeconds": 3600,
    "responseHeader": ["Content-Type", "Authorization"]
  }
]

2. 执行命令上传配置（需安装Google Cloud SDK）：

gsutil cors set cors.json gs://<你的存储桶名称>

3. 调整Wavesurfer.js的XHR配置 #

移除不必要的credentials: "include"——公开读取的Firebase资源无需携带凭证，该配置会触发额外CORS校验：

useEffect(() => {
  waveSurferRef.current = WaveSurfer.create({
    container: containerRef.current,
    waveColor: ["#eadfff", "#024bff"],
    progressColor: ["#024bff"],
    cursorColor: "#024bff",
    xhr: {
      cache: "default",
      mode: "cors",
      method: "GET",
      headers: [
        { key: "cache-control", value: "no-cache" },
        { key: "pragma", value: "no-cache" },
      ],
    },
    responsive: true,
    height: 50,
    normalize: true,
    barMinHeight: 100,
    partialRender: true,
  })
})

4. 备选方案：使用签名URL #

若CORS配置仍有问题，可生成Firebase Storage签名URL加载音频，签名URL自带权限，无需依赖CORS配置：

import { getStorage, ref, getDownloadURL } from "firebase/storage";

const getSignedAudioUrl = async (audioPath) => {
  const storage = getStorage();
  const audioRef = ref(storage, audioPath);
  const url = await getDownloadURL(audioRef);
  return url;
};

useEffect(() => {
  const loadAudio = async () => {
    const audioUrl = await getSignedAudioUrl("path/to/your/audio.mp3");
    waveSurferRef.current.load(audioUrl);
  };
  loadAudio();
}, []);

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