本地测试Sanity IO时process变量未找到的.env.local问题排查

问题现象 #

• 本地运行Sanity Studio时抛出错误：

  Uncaught error: Can't find variable: process
  http://localhost:3333/sanity.config.ts:5:26
  

• 将项目ID直接硬编码到sanity.config.ts中可正常运行，但.env.local文件无法读取环境变量
• .env文件未显示教程中的齿轮图标

核心原因&解决步骤 #

1. 文件名拼写错误 #

你提供的环境文件名是.en.local，正确的文件名应该是.env.local（少了一个v）。这是导致环境文件不被识别、没有齿轮图标的直接原因。

• 修正文件名后，VSCode等编辑器会自动识别为环境配置文件，显示齿轮图标。

2. Sanity Studio v3 环境变量加载配置 #

Sanity Studio v3 默认不会自动加载.env.local文件，需要手动配置加载逻辑：

方案一：使用Sanity CLI的环境变量支持

Sanity CLI会自动加载根目录下的.env或.env.local文件，但变量名不需要NEXT_PUBLIC_前缀（这是Next.js用于暴露浏览器端变量的前缀，Sanity Studio是独立服务）：

• 修改.env.local内容：

  SANITY_PROJECT_ID=xxxxxx
  SANITY_DATASET=production
  SANITY_API_VERSION=2022-11-15
  

• 修改sanity.config.ts：

  import {defineConfig} from 'sanity'
  import {deskTool} from 'sanity/desk'
  import {visionTool} from '@sanity/vision'
  import {schemaTypes} from './schemas'
  
  const projectId = process.env.SANITY_PROJECT_ID!
  const dataset = process.env.SANITY_DATASET!
  
  export default defineConfig({
    name: 'Jeremy',
    title: 'Sanity Stuff',
    projectId,
    dataset,
    plugins: [deskTool(), visionTool()],
    schema: {
      types: schemaTypes,
    },
  })
  

方案二：手动导入dotenv加载文件

如果坚持使用NEXT_PUBLIC_前缀，需要在配置文件顶部手动加载.env.local：

• 修改sanity.config.ts开头：

  import dotenv from 'dotenv'
  dotenv.config({ path: '.env.local' })
  
  import {defineConfig} from 'sanity'
  // ... 其余代码不变
  

3. TypeScript 类型声明修复 #

为避免TS报错process is not defined，添加类型声明：

• 在项目根目录创建env.d.ts文件：

  declare global {
    namespace NodeJS {
      interface ProcessEnv {
        SANITY_PROJECT_ID: string
        SANITY_DATASET: string
        SANITY_API_VERSION: string
        // 若使用NEXT_PUBLIC_前缀则添加以下字段
        NEXT_PUBLIC_SANITY_PROJECT_ID: string
        NEXT_PUBLIC_SANITY_DATASET: string
        NEXT_PUBLIC_SANITY_API_VERSION: string
      }
    }
  }
  
  export {}
  

• 确保tsconfig.json的include数组包含env.d.ts：

  "include": ["next-env.d.ts", "env.d.ts", "**/*.ts", "**/*.tsx"]
  

4. 重启开发服务 #

修改环境文件或配置后，必须重启sanity dev服务，否则新的环境变量不会生效。

额外建议 #

• 不要在Sanity Studio中使用NEXT_PUBLIC_前缀，这是Next.js专属的浏览器端变量前缀，Sanity Studio作为独立服务，直接使用无前缀的变量更规范。
• 确保.env.local文件放在Sanity项目的根目录下，和package.json同级。

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