Next.js13(App Router)中next-cloudinary的Cloudinary Widget持续加载无法显示

1. 核对Cloudinary核心配置 #

• 确认cloudName和uploadPreset完全正确：如果用无签名上传，必须在Cloudinary后台把该预设的**“签名上传”选项关闭**；如果是签名上传，要确保签名参数（signature、timestamp等）生成正确且未过期。
• 检查上传预设的“允许的资源类型”是否包含video，没有开启视频权限会导致加载异常。

2. 排查资源加载与网络问题 #

• 打开浏览器控制台「Network」面板，搜索cloudinary相关脚本，确认https://widget.cloudinary.com/v2.0/global/all.js是否以200状态码加载成功。如果是403/404，检查域名是否被本地防火墙、代理屏蔽，或者Cloudinary账号是否处于正常状态。
• 切换网络环境（比如手机热点）测试，排除本地网络限制的影响。

3. Next.js环境适配检查 #

• 如果你用的是next-cloudinary包，确认包版本与你的Next.js版本兼容（比如Next.js 13+需要next-cloudinary v4及以上），可以尝试升级或回退版本验证。
• 必须把使用Widget的组件标记为客户端组件（顶部加'use client';），因为Widget依赖浏览器DOM环境，不能在服务端组件中初始化。

4. 代码逻辑与样式干扰排查 #

• 确保Widget初始化代码在组件挂载后执行（比如放在useEffect钩子中），避免在服务端渲染阶段调用。
• 排查页面全局CSS或自定义样式：比如是否有过高z-index的元素覆盖Widget，或者overflow: hidden导致Widget容器被隐藏。
• 检查是否重复初始化Widget（比如多次调用createUploadWidget），避免实例冲突导致加载卡住。

示例正确初始化代码（Next.js客户端组件） #

'use client';

import { useEffect } from 'react';

export default function UploadVideoModal() {
  useEffect(() => {
    let widget: any;

    const initCloudinaryWidget = async () => {
      const { createUploadWidget } = await import('cloudinary-core');
      widget = createUploadWidget(
        {
          cloudName: '你的云名称',
          uploadPreset: '你的上传预设',
          resourceType: 'video', // 明确指定视频资源类型
          maxFileSize: 104857600 // 按需设置最大文件大小，比如100MB
        },
        (error: any, result: any) => {
          if (result?.event === 'success') {
            console.log('上传完成:', result.info);
            // 处理上传成功后的业务逻辑
          }
        }
      );
    };

    initCloudinaryWidget();

    // 绑定Widget打开按钮
    const openBtn = document.getElementById('open-upload-widget');
    const handleOpen = () => widget?.open();
    openBtn?.addEventListener('click', handleOpen);

    // 组件卸载时清理资源
    return () => {
      widget?.destroy();
      openBtn?.removeEventListener('click', handleOpen);
    };
  }, []);

  return (
    <div>
      <button id="open-upload-widget">选择并上传视频</button>
    </div>
  );
}

内容的提问来源于stack exchange，提问作者Arshil Hapani