Sanity + Next.js报错：缺少环境变量SANITY_STUDIO_DATASET

报错信息 #

Error: Missing environment variable: SANITY_STUDIO_DATASET

配置代码 #

export const apiVersion = process.env.SANITY_STUDIO_API_VERSION || "2023-12-03";

export const dataset = assertValue(
  process.env.SANITY_STUDIO_DATASET,
  "Missing environment variable: SANITY_STUDIO_DATASET"
);

export const projectId = assertValue(
  process.env.SANITY_STUDIO_SANITY_PROJECT_ID,
  "Missing environment variable: SANITY_STUDIO_SANITY_PROJECT_ID"
);

排查要点 #

• 环境变量文件问题

  • 确认根目录下存在.env.local文件（Next.js开发环境默认读取该文件），且变量SANITY_STUDIO_DATASET已正确写入，注意变量名大小写完全匹配，不要出现拼写错误。
  • 若使用.env、.env.development等其他环境文件，需确认当前运行环境对应正确的配置文件（Next.js会根据NODE_ENV自动加载对应文件）。

• 变量加载生效问题

  • 修改环境变量文件后必须重启Next.js开发服务器，否则新的变量值不会被加载。
  • 若该配置文件在客户端组件中使用，变量名需要添加NEXT_PUBLIC_前缀（如NEXT_PUBLIC_SANITY_STUDIO_DATASET），Next.js限制客户端组件只能读取带该前缀的环境变量；若仅在服务端/Sanity配置中使用，则不需要前缀。
  • 检查assertValue函数逻辑，确认是否误将合法的空值或默认值判定为缺失（比如数据集名称为空字符串也会触发报错）。

• Sanity Studio配置细节

  • 若为Next.js集成的Sanity Studio，确认Studio配置文件（如app/studio/sanity.config.ts）所在目录的环境变量文件是否正确，或者根目录的环境变量是否能被Studio读取。
  • 检查next-sanity的createClient调用，确认传入的dataset参数是否正确引用了该变量，没有拼写错误。

• 部署环境变量同步

  • 若部署到Vercel、Netlify等平台，需在平台的环境变量设置面板中手动添加SANITY_STUDIO_DATASET，本地的.env.local不会自动同步到部署环境。

验证方法 #

• 在配置代码中临时添加console.log(process.env.SANITY_STUDIO_DATASET)，运行项目后查看终端输出，确认变量是否被正确读取。
• 在终端执行printenv SANITY_STUDIO_DATASET（Mac/Linux）或set SANITY_STUDIO_DATASET（Windows），检查系统当前环境中是否存在该变量。

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