vscode 配置 supabase 全栈环境需确保三件事：正确安装并验证 cli（v1.20.0+）、环境变量严格使用 vite_ 前缀写入 .env.local、edge functions 依赖 docker 正常运行；分支切换后须手动更新 vite_supabase_url。
VSCode 配置 Supabase 全栈项目开发环境，核心在于三件事：正确安装 CLI、环境变量不漏传、前端框架能读到 VITE_SUPABASE_URL 和 VITE_SUPABASE_ANON_KEY。其他花哨插件或自动配置，反而容易导致连接失败或密钥泄露。
supabase cli 安装与项目关联必须手动验证
Supabase CLI 不是“装完就跑”，尤其在 Windows 或多 Node 版本环境下，supabase login 和 supabase link 极易静默失败。
- 用
scoop install supabase（Windows）或brew install supabase（macOS）安装，避免 npm 全局安装带来的权限和版本混乱 - 运行
supabase --version确认输出为v1.20.0+（2026 年主流稳定版），低于 v1.18 的版本不支持branches和本地functions调试 -
supabase link --project-ref your-project-ref后，务必执行supabase status—— 它会显示当前连接的 branch、database URL、函数端口等，而不是只返回 “linked successfully” - 若
supabase status报错Project not found，检查.supabase/config.toml是否被 Git 忽略，或是否误删了.supabase目录
Vite / Vue 项目中环境变量必须带 VITE_ 前缀且写入 .env.local
Supabase 官方 SDK 依赖客户端可访问的环境变量，但 Vite 默认只暴露以 VITE_ 开头的变量。直接写 SUPABASE_URL 会导致运行时 undefined，控制台报错 Cannot read properties of undefined (reading 'url')。
- 在项目根目录新建
.env.local（不要用.env，它可能被提交到 Git） - 写入两行，严格按格式（无空格、无引号）：
VITE_SUPABASE_URL=https://your-project-id.supabase.co VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- 重启开发服务器（
npm run dev），否则 Vite 不会重新加载环境变量 - 在组件中使用时，必须从
import { createClient } from '@supabase/supabase-js'初始化，而非硬编码 URL —— 否则部署到 Vercel 时无法自动替换
本地调试边函数（Edge Functions）需启用 Docker daemon 并指定端口
Supabase CLI 的 supabase functions serve 本质是启动一个本地容器，若 Docker 没开或配置不对，函数永远处于 “starting…” 状态，且控制台无明确错误提示。
- Windows 用户：打开 Docker Desktop → Settings → General → ✅
Expose daemon on tcp://localhost:2375 without TLS（这是关键，缺它必失败） - macOS 用户：确保 Docker 正在运行，且未启用 “Use the new Virtualization framework”（该选项与
supabase_vector_supabase_cli镜像不兼容） - 启动函数前，先运行
supabase start；再新开终端执行supabase functions serve，默认监听http://localhost:54321/functions/v1/hello-function - 调用时注意路径：前端 fetch 必须用完整 URL，例如
fetch('http://localhost:54321/functions/v1/hello-function')，不能省略/v1/或端口
最容易被忽略的是：Supabase 的 branches 功能虽然强大，但它生成的 API URL（如 https://feature-auth-xxx.supabase.co）**不会自动更新** VITE_SUPABASE_URL。每次切分支后，你得手动改 .env.local 或用脚本注入 —— 否则前端还在连 production 数据库。
