cloudinary-next

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudinary Next

Purpose

用途

Use this skill to help developers build, debug, or review Next.js projects that integrate Cloudinary through

next-cloudinary

and, for server-only operations, the Cloudinary Node SDK v2.

This skill is organized for progressive loading. Do not load every reference file by default. Start with the workflow below, then load only the reference files needed for the user's task.

本技能旨在帮助开发者构建、调试或审查通过

next-cloudinary

集成Cloudinary的Next.js项目，对于仅服务器端操作，则使用Cloudinary Node SDK v2。

本技能采用渐进式加载组织。默认无需加载所有参考文件，请先遵循下方工作流程，再仅加载用户任务所需的参考文件。

Core workflow

核心工作流程

Classify the user's goal before writing code:
- render a transformed Cloudinary image in JSX
- generate a Cloudinary URL string
- embed a video player
- upload from the browser
- perform a signed upload
- upload from the server
- delete an asset
- build an overlay or text overlay
- generate an OG/social image
- fix TypeScript, environment, import, runtime, or upload errors
- review an existing implementation
Load the relevant reference file from the map below.
Apply the non-negotiable rules in this
```
SKILL.md
```
before using any detailed reference.
For code review or debugging, load
```
references/troubleshooting.md
```
plus the task-specific reference.
When a detail is version-sensitive or not covered here, consult the official documentation linked in
```
references/official-docs.md
```
and prefer official prop names and event names over memory.

编写代码前先明确用户目标：
- 在JSX中渲染经过变换的Cloudinary图片
- 生成Cloudinary URL字符串
- 嵌入视频播放器
- 从浏览器上传资源
- 执行签名上传
- 从服务器端上传资源
- 删除资源
- 创建图片叠加层或文字叠加层
- 生成OG/社交图片
- 修复TypeScript、环境配置、导入、运行时或上传相关错误
- 审查现有实现
从下方的参考映射中加载相关参考文件。
在使用任何详细参考内容前，先遵循本
```
SKILL.md
```
中的不可违背规则。
进行代码审查或调试时，加载
```
references/troubleshooting.md
```
以及任务特定的参考文件。
当涉及版本敏感内容或此处未覆盖的细节时，请查阅
```
references/official-docs.md
```
中链接的官方文档，优先使用官方的属性名和事件名，而非凭记忆编写。

Non-negotiable rules

不可违背规则

Use

next-cloudinary

for Next.js components and URL helpers:

CldImage

CldVideoPlayer

CldUploadWidget

CldUploadButton

CldOgImage

getCldImageUrl

getCldOgImageUrl

, and

getCldVideoUrl

Use the Cloudinary Node SDK v2 only for server-side operations:
```
import { v2 as cloudinary } from 'cloudinary'
```
.

Never expose

CLOUDINARY_API_SECRET

to the browser. Never create

NEXT_PUBLIC_CLOUDINARY_API_SECRET

Put upload widgets, video player UI, and any component with React event handlers behind a Client Component boundary with
```
'use client'
```
.
```
CldImage
```
may be used from a Server Component for static rendering, but if you add client-only props such as
```
onLoad
```
or local state, move it into a Client Component.
Do not import
```
cloudinary
```
in Client Components or Edge runtime code. Server Actions and route handlers that import
```
cloudinary
```
must run on the Node.js runtime.
Use documented
```
next-cloudinary
```
prop names and shapes. Do not infer prop names from Cloudinary URL transformation parameters.
Use
```
onSuccess
```
for upload widget success handling. Do not use deprecated upload callback names unless the installed version explicitly documents them.
For deletes, pass a public ID, not a delivery URL. Pass
```
resource_type
```
when deleting videos or raw assets, and use
```
invalidate: true
```
when CDN cache invalidation is desired.

针对Next.js组件和URL工具，使用

next-cloudinary

：

CldImage

、

CldVideoPlayer

、

CldUploadWidget

、

CldUploadButton

、

CldOgImage

、

getCldImageUrl

、

getCldOgImageUrl

和

getCldVideoUrl

。

仅在服务器端操作中使用Cloudinary Node SDK v2：
```
import { v2 as cloudinary } from 'cloudinary'
```
。

绝不能向浏览器暴露

CLOUDINARY_API_SECRET

，绝不能创建

NEXT_PUBLIC_CLOUDINARY_API_SECRET

。

将上传组件、视频播放器UI以及任何包含React事件处理器的组件放置在带有
```
'use client'
```
的Client Component边界内。
```
CldImage
```
可在Server Component中用于静态渲染，但如果添加了仅客户端可用的属性（如
```
onLoad
```
）或本地状态，请将其移至Client Component中。
不要在Client Component或Edge运行时代码中导入
```
cloudinary
```
。导入
```
cloudinary
```
的Server Action和路由处理器必须在Node.js运行时环境下运行。
使用
```
next-cloudinary
```
文档中规定的属性名和格式。不要从Cloudinary URL变换参数中推断属性名。
上传组件的成功处理使用
```
onSuccess
```
，除非已安装版本明确记录了已弃用的上传回调名称，否则不要使用这些弃用名称。
删除资源时，传入公共ID而非分发URL。删除视频或原始资源时需传入
```
resource_type
```
，当需要清除CDN缓存时使用
```
invalidate: true
```
。

Reference map

参考映射

Load the smallest useful set of references:

```
references/official-docs.md
```
— official documentation links and the global prop-name rule.
```
references/api-decision-tree.md
```
— choose the correct Cloudinary API/component/helper for a user goal.
```
references/project-setup.md
```
— install packages, configure Next.js image domains, configure upload presets, and create starter setup files.
```
references/environment.md
```
— environment variables and TypeScript process env typing.
```
references/imports.md
```
— correct import paths and server/client boundaries.

references/cldimage.md

—

CldImage

, sample assets, and

getCldImageUrl

usage.

```
references/cldimage-transformations.md
```
— transformation props, generative editing, optimization, raw transformations, and crop traps.
```
references/responsive-images.md
```
— responsive image sizing and
```
sizes
```
guidance.
```
references/video-player.md
```
—
```
CldVideoPlayer
```
, required CSS, and client-only player setup.
```
references/upload-widget.md
```
— browser uploads, upload widget/button usage, events, and signed-vs-unsigned tradeoffs.
```
references/signed-uploads.md
```
— App Router signature endpoint pattern.
```
references/server-upload-delete.md
```
— Server Action and route-handler upload/delete patterns with the Node SDK v2.
```
references/overlays.md
```
— image overlays and text overlay prop shapes.
```
references/og-images.md
```
— App Router and Pages Router OG/social card patterns.
```
references/typescript.md
```
— upload result narrowing, server upload result types, refs, and avoiding
```
any
```
.
```
references/troubleshooting.md
```
— common error messages and fixes.
```
references/quick-checklist.md
```
— final code-review checklist and best practices.

加载最有用的最小参考文件集：

```
references/official-docs.md
```
—— 官方文档链接和全局属性名规则。
```
references/api-decision-tree.md
```
—— 根据用户目标选择正确的Cloudinary API/组件/工具。
```
references/project-setup.md
```
—— 安装包、配置Next.js图片域名、配置上传预设以及创建初始设置文件。
```
references/environment.md
```
—— 环境变量和TypeScript进程环境类型定义。
```
references/imports.md
```
—— 正确的导入路径和服务器/客户端边界。

references/cldimage.md

——

CldImage

、示例资源以及

getCldImageUrl

的用法。

```
references/cldimage-transformations.md
```
—— 变换属性、生成式编辑、优化、原始变换以及裁剪陷阱。
```
references/responsive-images.md
```
—— 响应式图片尺寸和
```
sizes
```
属性指南。
```
references/video-player.md
```
——
```
CldVideoPlayer
```
、所需CSS以及仅客户端播放器设置。
```
references/upload-widget.md
```
—— 浏览器端上传、上传组件/按钮用法、事件以及签名与无签名上传的权衡。
```
references/signed-uploads.md
```
—— App Router签名端点模式。
```
references/server-upload-delete.md
```
—— 使用Node SDK v2的Server Action和路由处理器上传/删除模式。
```
references/overlays.md
```
—— 图片叠加层和文字叠加层的属性格式。
```
references/og-images.md
```
—— App Router和Pages Router的OG/社交卡片实现模式。
```
references/typescript.md
```
—— 上传结果类型收窄、服务器端上传结果类型、引用以及避免使用
```
any
```
类型。
```
references/troubleshooting.md
```
—— 常见错误信息及修复方案。
```
references/quick-checklist.md
```
—— 最终代码审查清单和最佳实践。

Output expectations

输出预期

When generating code, include the file path, the complete relevant code block, and a short note about where the code runs: Client Component, Server Component, Server Action, or route handler.

When reviewing code, report issues in this order: secret exposure, server/client boundary mistakes, import/runtime mistakes, incorrect component/helper choice, incorrect prop/event names, missing TypeScript narrowing, and missing cache invalidation or resource type handling.

When using reusable templates, copy from

assets/app-router-signature-route.ts

assets/server-action-upload.ts

, or

assets/server-action-delete.ts

and adapt names, folders, and return values to the user's project.

生成代码时，请包含文件路径、完整的相关代码块，以及关于代码运行位置的简短说明：Client Component、Server Component、Server Action或路由处理器。

审查代码时，按以下顺序报告问题：密钥暴露、服务器/客户端边界错误、导入/运行时错误、组件/工具选择错误、属性/事件名称错误、缺失TypeScript类型收窄、缺失缓存清除或资源类型处理。

使用可复用模板时，请从

assets/app-router-signature-route.ts

、

assets/server-action-upload.ts

或

assets/server-action-delete.ts

中复制，并根据用户项目调整名称、文件夹和返回值。