如何在前端使用 Cloudinary API 上传时动态调整视频质量-js教程-PHP中文网

如何在前端使用 Cloudinary API 上传时动态调整视频质量

本文详解为何直接在 Cloudinary 上传 URL 后拼接 q_20 会导致 404 和 CORS 错误，并说明正确做法：通过 transformation 参数在请求体中指定质量压缩，而非修改 API 路径。

本文详解为何直接在 cloudinary 上传 url 后拼接 `q_20` 会导致 404 和 cors 错误，并说明正确做法：通过 `transformation` 参数在请求体中指定质量压缩，而非修改 api 路径。

Cloudinary 的上传 API 端点是严格固定的，例如 https://api.cloudinary.com/v1_1/{cloud_name}/video/upload。在 URL 路径末尾添加 /q_20 并非合法路由——它会被服务器识别为不存在的资源路径，因此返回 404 Not Found；同时，因浏览器拦截了无效跨域请求，还会附带 CORS error 提示。这不是权限或配置问题，而是根本性的 URL 构造错误。

✅ 正确方式：使用 Incoming Transformation（上传时转换），将质量参数作为 transformation 字段放入请求体（FormData）。该参数支持所有标准变换标识符（如 q_20、q_auto、w_640,h_360,c_limit 等），Cloudinary 会在文件保存前自动执行压缩与转码。

以下是在 React 前端（如 useEffect 或事件处理器中）上传并压缩视频的完整示例：

PigX UI 前端开发

PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。

下载

const uploadToCloudinary = async (file: File, type: 'img' | 'video') => {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('upload_preset', 'your_upload_preset'); // 必填！需提前在 Cloudinary 控制台创建
  formData.append('transformation', type === 'video' ? 'q_20' : 'q_80'); // ✅ 正确传参位置
  formData.append('resource_type', type === 'img' ? 'image' : 'video');

  try {
    const res = await fetch(
      `https://api.cloudinary.com/v1_1/${CLOUD_NAME}/${type === 'img' ? 'image' : 'video'}/upload`,
      {
        method: 'POST',
        body: formData,
      }
    );
    const data = await res.json();
    if (!res.ok) throw new Error(data.error?.message || 'Upload failed');
    return data; // 包含 secure_url、public_id 等
  } catch (err) {
    console.error('Cloudinary upload error:', err);
    throw err;
  }
};

⚠️ 关键注意事项：

必须配置 upload_preset：这是无签名上传（前端直传）的安全凭证，需在 Cloudinary 控制台 → Settings → Upload → Upload presets 中启用“Unsigned”类型并复制其名称。
transformation 是字符串，非对象：直接传 'q_20' 或链式 'q_20,w_720,c_scale' 即可，无需 JSON 序列化。
免费版限制：视频单文件上限为 100MB。若原始视频超限，仅调低质量（q_）可能不够，建议组合使用分辨率缩放（如 w_640,h_360,c_limit）进一步减小体积。
避免敏感信息泄露：切勿在前端硬编码 API Key；upload_preset 是安全的无密钥机制，但需确保其未开启“Allow anonymous uploads”以外的高风险选项。

总结：Cloudinary 的上传路径不可自定义扩展，所有预处理逻辑必须通过 FormData 的 transformation、quality、width 等字段声明。掌握这一模式，你就能在不依赖后端代理的前提下，安全、高效地实现前端视频智能压缩与直传。