Next.js+TypeScript构建失败：未找到cloudinary变量

这个问题的核心是TypeScript静态类型检查无法识别全局注入的cloudinary变量——开发环境中浏览器已经加载了Cloudinary的脚本，全局对象上存在cloudinary所以运行正常，但构建时TS会做预检查，不知道这个变量的存在，因此抛出错误。

下面是两种可行的解决方法：

方法一：声明全局类型（推荐，类型安全） #

在项目根目录创建一个类型声明文件，比如types/cloudinary-media-library.d.ts，写入以下内容：

declare var cloudinary: {
  createMediaLibrary: (
    config: {
      cloud_name: string;
      api_key: string;
      multiple?: boolean;
    },
    handlers: {
      insertHandler: (data: { assets: Array<{ url: string }> }) => void;
    }
  ) => { show: () => void };
};

然后确保你的tsconfig.json中包含该类型目录，比如：

{
  "include": ["types/**/*.d.ts", "src/**/*"]
}

这样TypeScript就能识别cloudinary的类型，原代码无需修改即可通过构建。

方法二：通过window对象访问（快速解决） #

直接将代码中的cloudinary替换为(window as any).cloudinary，利用window全局对象绕过TS的类型检查：

<Script
  id="cloudinary"
  defer
  src="https://media-library.cloudinary.com/global/all.js"
  onReady={() => {
    widgetRef.current = (window as any).cloudinary.createMediaLibrary(
      {
        cloud_name: "<cloud name here>",
        api_key: "<api key here>",
        multiple: false,
      },
      {
        insertHandler: (data) => {
          const selectedImage = { ...data.assets[0] };
          form.setFieldValue("image", selectedImage.url);
        },
      }
    );

    setWidgetReady(true);
  }}
></Script>

额外优化：完善widgetRef类型 #

为了让按钮点击时的类型更安全，建议给widgetRef指定类型：

const widgetRef = useRef<{ show: () => void } | null>(null);

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