SvelteKit部署Vercel时$env/static/private环境变量导出报错

问题原因 #

SvelteKit的$env/static/private在构建阶段会做静态分析，只有构建时存在的环境变量才会被导出。本地开发时.env文件里的变量在启动时就加载了，所以能正常识别；但Vercel默认是先构建再注入环境变量，导致构建阶段找不到这个变量，触发Rollup导出错误。

解决方法 #

• 给环境变量添加前缀（推荐）：
  SvelteKit要求私有环境变量必须以VITE_或SVELTEKIT_开头（新版推荐SVELTEKIT_）。把你的变量名改成SVELTEKIT_ENV_VAR_NAME：

  • 本地.env文件：SVELTEKIT_ENV_VAR_NAME='random123'
  • Vercel后台变量名同步改为SVELTEKIT_ENV_VAR_NAME
  • 代码中导入：import { SVELTEKIT_ENV_VAR_NAME } from '$env/static/private';

• 在Vercel开启构建时注入环境变量：
  如果不想改变量名，进入Vercel项目的Settings → Environment Variables，找到你的ENV_VAR_NAME，点击变量右侧的编辑按钮，勾选Expose this variable to the Build Environment选项，保存后重新部署。

• 手动声明环境变量类型（可选）：
  在项目根目录创建src/app.d.ts，添加变量的类型声明，帮助SvelteKit的静态分析识别：

  declare namespace App {
    interface PrivateEnv {
      ENV_VAR_NAME: string;
    }
  }
  

验证步骤 #

• 本地先删除.env文件，运行npm run build，如果也出现同样错误，说明是构建阶段变量未加载的问题，按上面的方法修复。
• 修复后重新部署Vercel，查看构建日志确认无错误。

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