Cloudinary & Astro

Cloudinary 是一个图片和视频平台，也是一个无头数字资产管理器（DAM），可以让你托管资产并通过其内容分发网络（CDN）进行交付。

通过 Cloudinary 进行交付时，你还可以访问其转换 API，从而能够使用背景移除、动态裁剪和调整大小以及生成式 AI 等工具来编辑你的资产。

在 Astro 中使用 Cloudinary

Cloudinary 支持多种 SDK，可以根据你的 Astro 环境选择使用。

Cloudinary Astro SDK 提供了原生的 Astro 组件，包括图片、视频和上传组件，以及一个可用于 Astro 内容集合的内容加载器。

另外，Cloudinary 的 Node.js SDK 和 JavaScript SDK 都可以用来为你的图片生成 URL。Node.js SDK 还可以向 Cloudinary API 发出请求，包括上传资产、请求资源和运行内容分析。

先决条件

一个已有的 Astro 项目
一个 Cloudinary 账户

安装 Astro Cloudinary

通过运行适合你的包管理器的命令来安装 Cloudinary Astro SDK

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

配置你的账户

在你的项目根目录下创建一个新的 .env 文件，并添加你的 Cloudinary 凭据

PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

// Only needed if using CldUploadWidget or cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

使用 Cloudinary 图片

通过将图片数据（例如 src、width、alt）传递给 <CldImage> 组件，在 .astro 组件中添加图片。这将自动优化你的图片，并让你能够访问转换 API。

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>

更多信息请参阅 Cloudinary 的 <CldImage> 文档。

使用 Cloudinary 视频

要在你的 .astro 组件中添加视频，请添加 <CldVideoPlayer> 并传递相应的属性。该组件将使用 Cloudinary 视频播放器自动优化和嵌入你的视频。

---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
/>

更多信息请参阅 Cloudinary 的 <CldVideoPlayer> 文档。

启用 Cloudinary 上传

要在你的网站或应用的 UI 中启用文件上传，请添加 <CldUploadWidget>，它将嵌入 Cloudinary 上传小部件。

以下示例通过传递一个无签名的上传预设来创建一个允许未签名上传的小部件

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>

对于签名上传，你可以在 Astro Cloudinary 文档中找到指南和示例。

更多信息请参阅 Cloudinary 的 <CldUploadWidget> 文档。

Cloudinary 内容加载器

Cloudinary Astro SDK 提供了 cldAssetsLoader 内容加载器，用于为内容集合加载 Cloudinary 资产。

要加载图片或视频集合，请设置 loader: cldAssetsLoader ({})，如果需要，可以带上 folder 参数

import { defineCollection } from 'astro:content';
import { cldAssetsLoader } from 'astro-cloudinary/loaders';

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Folder>' // Optional, without loads root directory
    })
  }),
}

然后，你可以使用 getCollection() 或 getEntry() 查询函数从你的集合中选择一个或多个图片或视频。

更多信息请参阅 Cloudinary 的 cldAssetsLoader 文档。

生成 Cloudinary 图片 URL

Astro Cloudinary SDK 提供了一个 getCldOgImageUrl() 辅助函数，用于生成和使用你的图片 URL。当需要使用 URL 而不是组件来显示图片时，可以使用此函数。

一个常见的 URL 用途是用于社交媒体卡片的 <meta> 标签中的 Open Graph 图片。与组件一样，这个辅助函数让你能够访问 Cloudinary 的转换功能，为你的任何页面创建动态、独特的社交卡片。

以下示例展示了社交媒体卡片所需的 <meta> 标签，使用 getCldOgImageUrl() 生成 Open Graph 图片

---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<Public ID>' });
---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Twitter Title>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />

在 Cloudinary 文档中查找 Cloudinary 社交媒体卡片模板。

更多信息请参阅 Cloudinary 的 getCldOgImageUrl() 文档。

在 Node.js 中使用 Cloudinary

对于更复杂的资产管理、上传或分析，你可以在 Astro Node.js 环境中使用 Cloudinary Node.js SDK。

通过运行适合你的包管理器的命令来安装 Cloudinary Node.js SDK

npm install cloudinary

pnpm add cloudinary

yarn add cloudinary

在你的 .env 文件中添加以下环境变量

PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

通过在你的 Astro 组件的代码块之间添加以下代码，用一个新的 Cloudinary 实例来配置你的账户

---
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---

这将让你能够访问所有的 Cloudinary API，从而与你的图片、视频和其他支持的文件进行交互。

await cloudinary.uploader.upload('./path/to/file');

学习如何使用 Cloudinary Node.js SDK 和 Astro Forms 上传文件。