本文详解为何直接在 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 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 等字段声明。掌握这一模式，你就能在不依赖后端代理的前提下，安全、高效地实现前端视频智能压缩与直传。
