# Node.js SDK（传统）
npm install cloudinary
 
# Cloudinary 2.0 前端 SDK（推荐）
npm install @cloudinary/url-gen
 
# React SDK
npm install @cloudinary/react
 
# Next.js SDK
npm install @cloudinary/next
 
# Vue SDK
npm install @cloudinary/vue
 
# Angular SDK
npm install @cloudinary/angular

// Node.js SDK 配置
import { v2 as cloudinary } from 'cloudinary';
 
cloudinary.config({
  cloud_name: 'your_cloud_name',
  api_key: 'your_api_key',
  api_secret: 'your_api_secret',
  secure: true
});
 
// Cloudinary 2.0 SDK 配置
import { Cloudinary } from '@cloudinary/url-gen';
 
const cld = new Cloudinary({
  cloud: { cloudName: 'your_cloud_name' },
  url: { secure: true }
});

import { Cloudinary } from '@cloudinary/url-gen';
import { fill } from '@cloudinary/url-gen/actions/resize';
import { format, quality } from '@cloudinary/url-gen/qualifiers';
import { autoGravity } from '@cloudinary/url-gen/qualifiers/gravity';
 
const cld = new Cloudinary({ cloud: { cloudName: 'demo' } });
 
const img = cld
  .image('sample')
  .resize(fill().width(400).height(300).gravity(autoGravity()))
  .format(format('auto'))
  .quality(quality('auto'));
 
console.log(img.toURL());
// https://res.cloudinary.com/demo/image/upload/c_fill,w_400,h_300,g_auto,f_auto,q_auto/sample

import { Cloudinary } from '@cloudinary/url-gen';
import { AdvancedImage, responsive, lazyload, placeholder } from '@cloudinary/react';
import { fill } from '@cloudinary/url-gen/actions/resize';
import { format, quality } from '@cloudinary/url-gen/qualifiers';
 
const cld = new Cloudinary({ cloud: { cloudName: 'demo' } });
 
function App() {
  const img = cld
    .image('sample')
    .resize(fill().width(800).height(600))
    .format(format('auto'))
    .quality(quality('auto'));
 
  return (
    <AdvancedImage
      cldImg={img}
      plugins={[responsive(), lazyload(), placeholder()]}
      alt="Sample image"
    />
  );
}

// 完整的上传和处理流程
import { v2 as cloudinary } from 'cloudinary';
 
// 1. 上传
const uploadResult = await cloudinary.uploader.upload('local-image.jpg', {
  public_id: 'products/product-001',
  folder: 'my-app',
  transformation: { width: 2000, height: 2000, crop: 'limit' },
  eager: [
    { width: 800, height: 600, crop: 'fill', format: 'webp', quality: 'auto' },
    { width: 400, height: 400, crop: 'thumb', gravity: 'face', format: 'auto' },
    { width: 200, height: 200, crop: 'thumb', format: 'auto', quality: 60 }
  ],
  context: { alt: 'Product photo', caption: 'Summer collection 2026' },
  tags: ['product', 'summer-2026']
});
 
console.log('Uploaded:', uploadResult.secure_url);
 
// 2. 生成变换 URL
const url = cloudinary.url('my-app/products/product-001', {
  width: 800,
  height: 600,
  crop: 'fill',
  gravity: 'auto',
  format: 'auto',
  quality: 'auto',
  effect: 'sharpen'
});
 
// 3. 获取资源信息
const info = await cloudinary.api.resource('my-app/products/product-001');
console.log('Size:', info.bytes, 'Format:', info.format);

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
        pathname: '/your_cloud_name/**'
      }
    ]
  }
}
 
// 使用 @cloudinary/next
import { CldImage } from '@cloudinary/next';
 
export default function ProductPage({ product }) {
  return (
    <CldImage
      src={`products/${product.id}`}
      width={800}
      height={600}
      crop="fill"
      gravity="auto"
      format="auto"
      quality="auto"
      alt={product.name}
    />
  );
}

# .env.local
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloud_name
# API Key/Secret 仅服务端使用
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# GitHub Actions: 媒体资源自动化
name: Media Pipeline
on: [push]
jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: node scripts/sync-media.js
        env:
          CLOUDINARY_API_KEY: ${{ secrets.CLOUDINARY_API_KEY }}
          CLOUDINARY_API_SECRET: ${{ secrets.CLOUDINARY_API_SECRET }}
          CLOUDINARY_CLOUD_NAME: ${{ secrets.CLOUDINARY_CLOUD_NAME }}

// 命名变换配置
await cloudinary.api.create_transformation('product_thumb', {
  width: 400, height: 400, crop: 'thumb', gravity: 'auto',
  format: 'auto', quality: 'auto'
});
 
// 使用命名变换
const url = cloudinary.url('product-001', {
  transformation: 'product_thumb'
});

// 签名 URL 示例
const signedUrl = cloudinary.url('private-image', {
  sign_url: true,
  type: 'authenticated',
  width: 800
});
 
// 上传签名
const signature = cloudinary.utils.api_sign_request(
  { timestamp: Math.round(Date.now() / 1000), folder: 'uploads' },
  cloudinary.config().api_secret
);

// 推荐：自动格式 + 自动质量
const img = cld.image('sample')
  .format(format('auto'))
  .quality(quality('auto'));
 
// URL 方式
// f_auto,q_auto

// Eager transformations：上传时预生成
await cloudinary.uploader.upload('image.jpg', {
  eager: [
    { width: 1200, format: 'auto', quality: 'auto' },
    { width: 800, format: 'auto', quality: 'auto' },
    { width: 400, format: 'webp', quality: 80 }
  ]
});

<!-- 启用 Client Hints 让服务端自动适配 DPR -->
<img
  src="https://res.cloudinary.com/demo/image/upload/w_auto:100,dpr_auto/f_auto/sample.jpg"
  sizes="100vw"
/>

<AdvancedImage
  cldImg={cld.image('sample')
    .resize(fill().width(800))
    .format(format('auto'))
    .quality(quality('auto'))}
  plugins={[responsive(), lazyload(), placeholder({ mode: 'blur' })]}
  alt="Responsive image"
/>

// 问题：变换消耗信用额度，大规模使用成本高
// 解决：预生成变换、使用命名变换、合理缓存
 
// 命名变换（只计数一次）
await cloudinary.api.create_transformation('standard_thumb', {
  width: 400, height: 400, crop: 'fill', format: 'auto', quality: 'auto'
});

// 错误：API Secret 暴露到前端
const cloudinary = new Cloudinary({
  cloud: { cloudName: 'demo', apiKey: '...', apiSecret: '...' }  // ❌
});
 
// 正确：前端只用 cloudName，敏感操作用服务端 SDK
const cloudinary = new Cloudinary({
  cloud: { cloudName: 'demo' }  // ✅
});