SvelteKit预览与部署时报错：supabaseUrl is required 求助

核心原因 #

SvelteKit在开发模式（npm run dev）和生产/预览模式下的环境变量加载逻辑存在差异：dev模式下Vite会默认暴露所有环境变量，而生产构建（包括npm run preview和Vercel部署）会严格按照规则过滤变量，导致未正确配置的变量无法被读取。

排查与解决步骤 #

1. 检查环境变量命名前缀
   客户端代码（页面组件、路由中的客户端逻辑）需要访问的环境变量必须以PUBLIC_为前缀，比如PUBLIC_SUPABASE_URL和PUBLIC_SUPABASE_ANON_KEY。如果你的变量没有加这个前缀，生产构建后客户端将无法读取，直接触发「supabaseUrl is required」错误。

2. 确认初始化逻辑的环境变量来源

   • 客户端初始化Supabase时，必须使用import.meta.env.PUBLIC_*来读取变量，示例：

     <script>
       import { onMount } from 'svelte';
       import { createClient } from '@supabase/auth-helpers-sveltekit';
       
       let supabase;
       
       onMount(() => {
         supabase = createClient(
           import.meta.env.PUBLIC_SUPABASE_URL,
           import.meta.env.PUBLIC_SUPABASE_ANON_KEY
         );
       });
     </script>
     

   • 服务端（如hooks.server.ts、API路由）初始化时，使用process.env.*读取私有变量，示例：

     // hooks.server.ts
     import { createSupabaseServerClient } from '@supabase/auth-helpers-sveltekit';
     import type { Handle } from '@sveltejs/kit';
     
     export const handle: Handle = async ({ event, resolve }) => {
       event.locals.supabase = createSupabaseServerClient({
         supabaseUrl: process.env.SUPABASE_URL,
         supabaseKey: process.env.SUPABASE_ANON_KEY,
         event
       });
       
       return resolve(event);
     };
     

3. 避免模块级过早初始化
   不要在组件的模块级别（onMount之外）初始化Supabase，否则客户端在hydration阶段会尝试读取未注入的环境变量，导致报错。将初始化逻辑放在onMount或服务端load函数中。

4. 本地预览的环境变量验证
   npm run preview基于构建后的产物运行，构建时的环境变量会被打包进产物。如果构建时未正确加载.env文件：

   • 确保使用正确的环境变量文件名，比如.env.production（生产构建）或.env.local（本地覆盖）
   • 构建前确认.env文件中的变量已正确设置，修改变量后需要重新执行npm run build再启动预览

5. Vercel部署的环境变量检查

   • 确认环境变量设置在Production环境下，而非仅Preview/Development环境
   • 变量名要严格匹配代码中的使用（注意大小写，比如SUPABASE_URL和supabase_url是不同变量）
   • 修改变量后需触发全新部署（而非使用构建缓存），确保新变量生效

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