cloudinary-next

Cloudinary Next

用途

使用此技能帮助开发者构建、调试或审查通过 next-cloudinary 集成 Cloudinary 的 Next.js 项目；对于仅限服务端的操作，则使用 Cloudinary Node SDK v2。

此技能采用渐进式加载。默认情况下，不要加载所有参考文件。请先按照以下工作流操作，然后仅加载用户任务所需的参考文件。

核心工作流

1. 编写代码前，先判断用户的目标：
   • 在 JSX 中呈现经过转换的 Cloudinary 图片
   • 生成 Cloudinary URL 字符串
   • 嵌入视频播放器
   • 从浏览器上传
   • 执行签名上传
   • 从服务端上传
   • 删除资源
   • 构建叠加层或文字叠加层
   • 生成 OG／社交图片
   • 修复 TypeScript、环境、导入、运行时或上传错误
   • 审查现有实现
2. 从下方的映射中加载相关参考文件。
3. 使用详细参考前，先遵循此 SKILL.md 中不可妥协的规则。
4. 对于代码审查或调试，同时加载 references/troubleshooting.md 和任务专用参考文件。
5. 如果某项内容与版本有关，或本文未涵盖，请查阅 references/official-docs.md 中链接的官方文档，并优先采用官方的属性名和事件名，而不要依赖记忆。

不可妥协的规则

• 对于 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' 声明之后的客户端组件边界内。
• 静态渲染时，可以在服务端组件中使用 CldImage；但如果添加了 onLoad 等仅限客户端的属性或本地状态，请将其移入客户端组件。
• 不要在客户端组件或 Edge 运行时代码中导入 cloudinary。导入 cloudinary 的 Server Action 和路由处理程序必须在 Node.js 运行时中运行。
• 使用文档中说明的 next-cloudinary 属性名和结构。不要根据 Cloudinary URL 转换参数推断属性名。
• 上传组件成功处理请使用 onSuccess。除非已安装版本的文档明确说明，否则不要使用已弃用的上传回调名称。
• 删除时，请传入公共 ID，而不是投递 URL。删除视频或原始资源时，请传入 resource_type；需要使 CDN 缓存失效时，请使用 invalidate: true。

参考文档索引

加载最精简且实用的参考文档集：

• references/official-docs.md — 官方文档链接和全局属性名称规则。
• references/api-decision-tree.md — 根据用户目标选择正确的 Cloudinary API／组件／辅助函数。
• references/project-setup.md — 安装软件包、配置 Next.js 图片域名、配置上传预设，以及创建起始设置文件。
• references/environment.md — 环境变量和 TypeScript process env 类型声明。
• 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 — 最终代码审查清单和最佳实践。

输出要求

生成代码时，请包含文件路径、完整且相关的代码块，并简要说明代码运行的位置：客户端组件、服务端组件、Server Action 或路由处理程序。

审查代码时，请按以下顺序报告问题：密钥泄露、服务端／客户端边界错误、导入／运行时错误、组件／辅助函数选择错误、属性／事件名称错误、缺少 TypeScript 类型收窄，以及缺少缓存失效或资源类型处理。

使用可复用模板时，请从 assets/app-router-signature-route.ts、assets/server-action-upload.ts 或 assets/server-action-delete.ts 复制，并根据用户的项目调整名称、文件夹和返回值。