根本原因是Node.js版本低于18.x或npm全局bin路径未加入$PATH；需确认node --version≥18.0.0，改用npm install -g supabase --user，并将npm config get prefix)/bin加入shell配置。
supabase CLI 安装后命令未找到
根本原因不是没装上，而是 Node.js 版本低于 18.x，或全局 bin 路径没进 $PATH。尤其在 macOS 上混用 Homebrew Node 和 nvm，或 Windows 上 PowerShell 执行策略限制，都会让 supabase --version 报 “command not found”。
实操建议：
- 先运行
node --version，确认 ≥18.0.0；否则从 nodejs.org 下载 v18.20.2 或 v20.12.1 LTS - 避免
sudo npm install -g supabase；改用npm install -g supabase --user - 安装后执行
npm config get prefix，把输出路径加进 shell 配置（如~/.zshrc中追加export PATH="$(npm config get prefix)/bin:$PATH"） - 最后必须跑
supabase --version确认输出为 v1.20.0+，低于 v1.18 的版本不支持本地 functions 调试
VITE_SUPABASE_URL 在组件里读不到
不是环境变量写错了，是 Vite 默认只暴露以 VITE_ 开头的变量——写成 SUPABASE_URL 或 REACT_APP_SUPABASE_URL 都会变成 undefined，控制台报 Cannot read properties of undefined (reading 'url')。
实操建议：
- 在项目根目录新建
.env.local（别用.env，它可能被提交到 Git） - 严格按格式写两行，**无空格、无引号、无注释**：
VITE_SUPABASE_URL=https://your-project-id.supabase.coVITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 - 改完必须重启开发服务器（
npm run dev），Vite 不会热重载环境变量 - 初始化客户端时，一定用
import { createClient } from '@supabase/supabase-js'，硬编码 URL 会导致部署到 Vercel 时无法替换
supabase functions serve 卡在 “starting…”
这不是函数代码问题，而是 Supabase CLI 启动的是 Docker 容器，Docker daemon 没开、配置不对，或 Windows 上没启用 TCP 暴露，就会静默卡住，控制台几乎不报错。
实操建议：
- macOS/Linux：确保 Docker Desktop 已启动；macOS M1/M2 用户注意不要用 Rosetta 启动 Docker
- Windows：打开 Docker Desktop → Settings → General → ✅
Expose daemon on tcp://localhost:2375 without TLS（缺这步必失败） - 验证是否生效：终端执行
docker info，能返回信息才算通 - 启动函数前先跑
supabase status，确认当前 branch 和函数端口已显示，再执行supabase functions serve
VSCode 里 supabaseClient.from(). 后没补全
不是插件没装对，是 TypeScript 类型服务没识别到 @supabase/supabase-js 的声明——这个包本身不带内建类型，需手动配类型定义。
实操建议：
- 确保项目有
tsconfig.json，并在"types"字段加入"@supabase/supabase-js" - JS 项目也得装类型包：
npm install -D @types/supabase__supabase-js - VS Code 中按
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win/Linux），输入 “Developer: Restart TS Server” 强制重载 - 验证点：在
supabaseClient.from('users').后敲.，应立刻列出select()、insert()等方法
VITE_SUPABASE_URL 不会自动更新，必须手动改 .env.local 里的值——这是最容易被忽略的一环，尤其在多人协作或 CI/CD 场景下。 
