Next.js项目中Cloudinary生产环境出现JSON格式错误排查

问题背景 #

我在Next.js项目中使用以下Cloudinary函数上传PDF文件：

import { v2 as cloudinary, UploadApiResponse } from 'cloudinary'
import dotenv from 'dotenv'

dotenv.config()

const cloudinaryConfig = {
  cloud_name: process.env.CloudName as string,
  api_key: process.env.CloudapiKey as string,
  api_secret: process.env.CloudapiSecret as string,
}

cloudinary.config(cloudinaryConfig)

export default async function uploadPDFtoCloud(
  pdfFile: string,
): Promise<string> {
  try {
    const result: UploadApiResponse = await cloudinary.uploader.upload(
      pdfFile,
      {
        folder: 'file_doc_pdf',
        resource_type: 'raw',
        type: 'authenticated',
      },
    )
    return result.secure_url as string
  } catch (error) {
    console.error('Error Uploading file:', error)
    throw new Error('Failed to upload PDF: ')
  }
}

该函数在开发环境可正常返回secure_url，但执行npm run build测试生产环境时，触发如下错误：

Error Uploading file: {
  message: `Server return invalid JSON response. Status Code 500. SyntaxError: Unexpected token '<', "&lt;!DOCTYPE "... is not valid JSON`,     
  name: 'Error',
  http_code: 500
}

构建过程及运行应用测试该函数时都会触发错误，已确认环境变量配置正确，错误出现在upload方法调用处。

可能的原因分析 #

• Next.js环境变量加载逻辑问题：
  Next.js生产环境会自动处理环境变量，无需手动调用dotenv.config()。手动调用可能打乱变量加载顺序，导致构建时Cloudinary的配置参数未正确注入，认证失败后Cloudinary返回HTML格式的500错误页，而非预期的JSON响应，最终引发解析错误。另外，若该函数在客户端组件中调用，Cloudinary的密钥（api_secret）会暴露，且客户端环境无法正确访问服务端环境变量，同样会导致认证失败。

• 构建阶段执行上传逻辑的冲突：
  如果上传函数在Next.js构建阶段（比如静态生成页面的getStaticProps中）被调用，此时运行环境的网络权限、文件路径可能与开发环境不一致。比如传入的pdfFile路径在构建环境中不存在，或是构建环境无法访问Cloudinary的API，导致请求返回HTML格式的错误页面，无法解析为JSON。

• Cloudinary配置细节问题：
  虽然确认环境变量存在，但需检查变量名是否与Cloudinary的要求匹配（Cloudinary默认环境变量名为CLOUDINARY_CLOUD_NAME、CLOUDINARY_API_KEY、CLOUDINARY_API_SECRET），若自定义变量名，需确保生产环境中变量已正确映射。此外，type: 'authenticated'要求资源仅能通过签名URL访问，若Cloudinary账户未开启相关权限，也可能返回500错误。

• 上传参数有效性问题：
  生产环境中传入的pdfFile可能不是有效的文件路径或Base64编码字符串。比如开发环境中使用本地文件路径，生产环境中该路径不存在，导致Cloudinary API无法处理请求，返回HTML格式的错误响应。

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