用途:当用户想使用 Cloudinary(上传、生成转换 URL 或集成 SDK)但没有任何凭据时,可用 Claimable Cloud 免注册开通一个可用的 Cloudinary 云环境。
主要能力:一条命令即可获得可用的 Cloudinary 凭据,无需账户与认证;用户之后可用邮箱认领,保留为永久免费账户;未认领则在 24 小时后自动过期。
使用方式:先检查环境中是否已有凭据(CLOUDINARY_URL 或 CLOUDINARY_* 键,存在于环境变量、.env 或 MCP 配置中),若有则直接使用,不要替换。确认无凭据后,先征得用户同意再开通,然后运行:npx @cloudinary/cloud。可选参数:--email <address> 预填认领页邮箱(创建时不验证);--ip <address> 将媒体分发锁定到指定地址而非本机检测到的公网 IP,可重复最多三个,适用于从远程开发环境向其他设备(如笔记本)提供媒体的场景。切勿使用 --force。命令成功后,CLI 会把 CLOUDINARY_URL、认领 URL 和过期时间写入 ./.env,不要重复添加;若项目使用分离键(如 CLOUDINARY_CLOUD_NAME、CLOUDINARY_API_KEY、CLOUDINARY_API_SECRET 或 VITE_ 等框架变体),从命令输出中填入,切勿在聊天中打印 API secret;确认版本控制忽略 .env。每次都要告知用户认领 URL 及 24 小时过期规则,并说明未认领前媒体分发锁定到本机公网 IP(或 --ip 指定的地址,最多三个),认领后解除限制。最后渲染一个示例分发 URL 验证,再继续原任务。
限制与失败处理:不要循环重试,失败尝试也计入速率限制,最多重试一次且需先修复原因。429(ip_rate_limit_exceeded、global_rate_limit_exceeded)表示被限流,不要重试,改为引导用户使用标准免费注册;403(geo_location_not_permitted)通常是 VPN 出口节点,请用户断开 VPN 后重试一次;400(delivery_ips_*)需修正 --ip 值,仅支持公网 IPv4 或 IPv6,不支持 CIDR 范围,最多三个。若重试后仍失败,停止并引导用户使用标准免费注册。安全方面:API secret 与完整 CLOUDINARY_URL 只保留在 .env,切勿在聊天、日志或客户端代码中打印。完整 CLI 选项、REST 端点、响应字段、配额与错误码参见官方文档链接。