Cloudinary 和 Astro

Cloudinary 是一个图片和视频平台以及无头数字资源管理器 (DAM)，可让你托管资源并从其内容交付网络 (CDN) 交付它们。

¥Cloudinary is an image and video platform and headless Digital Asset Manager (DAM) that lets you host assets and deliver them from their content delivery network (CDN).

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

¥When delivering from Cloudinary, you additionally get access to their Transformation API, giving you the ability to edit your assets with tools like background removal, dynamic cropping and resizing, and generative AI.

在 Astro 中使用 Cloudinary

¥Using Cloudinary in Astro

Cloudinary 支持多种 SDK，可根据 Astro 环境使用。

¥Cloudinary supports a wide variety of SDKs that can be used depending on your Astro environment.

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

¥The Cloudinary Astro SDK provides native Astro components, including image, video, and upload components, as well as a content loader that can be used with Astro content collections.

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

¥Alternatively, both the Cloudinary Node.js SDK and JavaScript SDK can be used to generate URLs for your images. The Node.js SDK can additionally make requests to the Cloudinary API including uploading assets, requesting resources, and running content analysis.

先决条件

¥Prerequisites

现有的 Astro 项目
Cloudinary 账户

安装 Astro Cloudinary

¥Installing Astro Cloudinary

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

¥Install the Cloudinary Astro SDK by running the appropriate command for your package manager:

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

配置你的账户

¥Configuring your account

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

¥Create a new .env file in the root of your project and add your Cloudinary credentials:

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 图片

¥Using Cloudinary images

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

¥Add images in .astro components by passing image data (e.g. src, width, alt) to the <CldImage> component. This will automatically optimize your image and give you access to the Transformations API.

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

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

¥See Cloudinary’s <CldImage> documentation for more information.

使用 Cloudinary 视频

¥Using Cloudinary videos

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

¥To add video to your .astro components, add the <CldVideoPlayer> and pass the appropriate properties. This component will automatically optimize and embed your video using the Cloudinary Video Player.

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

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

¥See Cloudinary’s <CldVideoPlayer> documentation for more information.

启用 Cloudinary 上传

¥Enabling Cloudinary uploads

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

¥To enable file uploading in your website or app’s UI, add the <CldUploadWidget> which will embed the Cloudinary Upload Widget.

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

¥The following example creates a widget to allow unsigned uploads by passing an unsigned Upload Preset:

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

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

¥For signed uploads, you can find a guide and example on the Astro Cloudinary docs.

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

¥See Cloudinary’s <CldUploadWidget> documentation for more information.

Cloudinary 内容加载器

¥Cloudinary content loader

Cloudinary Astro SDK 提供了 cldAssetsLoader 内容加载器来加载 Cloudinary 资源以进行内容集合。

¥The Cloudinary Astro SDK provides the cldAssetsLoader content loader to load Cloudinary assets for content collections.

要加载图片或视频集合，请根据需要将 loader: cldAssetsLoader ({}) 设置为 folder：

¥To load a collection of images or videos, set loader: cldAssetsLoader ({}) with a folder, if required:

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() 查询函数从你的收藏中选择一个或多个图片或视频。

¥You can then use the getCollection() or getEntry() query functions to select one or many images or videos from your collection.

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

¥See Cloudinary’s cldAssetsLoader documentation for more information.

生成 Cloudinary 图片 URL

¥Generating Cloudinary image URLs

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

¥The Astro Cloudinary SDK provides a getCldOgImageUrl() helper for generating and using URLs for your images. Use this when you need a URL instead of a component to display your image.

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

¥One common use for a URL is for an Open Graph image in <meta> tags for social media cards. This helper, like the components, provides you access to Cloudinary transformations to create dynamic, unique social cards for any of your pages.

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

¥The following example shows the necessary <meta> tags for a social media card, using getCldOgImageUrl() to generate an Open Graph image:

---
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 社交媒体卡模板。

¥Find Cloudinary Social Media Card templates on the Cloudinary docs.

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

¥See Cloudinary’s getCldOgImageUrl() documentation for more information.

在 Node.js 中使用 Cloudinary

¥Using Cloudinary in Node.js

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

¥For more complex asset management, uploading, or analysis, you can use the Cloudinary Node.js SDK when working in an Astro Node.js environment.

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

¥Install the Cloudinary Node.js SDK by running the appropriate command for your package manager:

npm install cloudinary

pnpm add cloudinary

yarn add cloudinary

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

¥Add the following environment variables in your .env file:

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

通过在 Astro 组件的围栏之间添加以下代码，使用新的 Cloudinary 实例配置你的账户：

¥Configure your account with a new Cloudinary instance by adding the following code between the fences of your Astro component:

---
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，以允许你与图片、视频和其他受支持的文件进行交互。

¥This will give you access to all of the Cloudinary APIs to allow you to interact with your images, videos, and other supported files.

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

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

¥Learn how to upload files using the Cloudinary Node.js SDK with Astro Forms.

官方资源

¥Official Resources