根本原因是Node.js版本低于18.x或全局安装路径未加入$PATH；需确认node --version≥18.0.0，避免nvm与系统Node混用，改用npm install -g supabase --user并确保npm bin路径已加入shell配置。
supabase CLI 安装失败或 supabase 命令未找到
根本原因不是网络慢或镜像源问题，而是 Node.js 版本低于 18.x，或全局安装路径没进 $PATH。macOS 上尤其容易因 Homebrew 装的 Node 和 nvm 管理的 Node 混用导致静默失败。
- 运行
node --version，必须 ≥18.0.0（2026 年推荐v18.20.2或v20.12.1） - 避免
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+
VS Code 中无法补全 from()、select() 等客户端方法
这不是插件没装对，是 TypeScript 类型服务压根没加载到 Supabase 的定义——@supabase/supabase-js 包本身不带 .d.ts，必须手动补全类型链。
- 项目有
tsconfig.json？确保含"types": ["@supabase/supabase-js"] - 纯 JS 项目？新建
jsconfig.json，启用"checkJs": true - 显式安装类型包：
npm install -D @types/supabase__supabase-js - 按
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win/Linux），输入 “Developer: Restart TS Server” 强制重载
Vite 项目里 VITE_SUPABASE_URL 读不到或报 Cannot read properties of undefined (reading 'url')
90% 是环境变量没按 Vite 规则暴露，或开发服务器没重启。Vite 只认 VITE_ 开头的变量，且不会热更新环境变量配置。
- 在项目根目录建
.env.local（不是.env，防止误提交） - 写两行，严格无空格、无引号：
VITE_SUPABASE_URL=https://xxx.supabase.co和VITE_SUPABASE_ANON_KEY=eyJhbG... -
必须重启
npm run dev，否则新变量永远不生效 - 初始化 client 时，务必用
createClient，不要硬编码 URL —— 否则部署到 Vercel 会直接挂
本地 supabase start 报 “Failed to start PostgREST” 或 “port already in use”
Supabase CLI 启动的是整套栈（PostgreSQL + PostgREST + Realtime + Studio），默认端口是固定组合。冲突基本来自 Docker Desktop 自带的 PostgreSQL，或你本地已跑着 pg 实例。
- 先停掉所有 Docker 容器：
docker stop $(docker ps -q) - 检查 5432、3000、54321 是否被占：
lsof -i :5432（macOS/Linux）或netstat -ano | findstr :5432（Windows） - 若端口被占，可改用自定义端口启动：
supabase start --api-port 3001 --db-port 5433 - 注意：
supabase start不会自动拉镜像，首次运行前建议先supabase init再supabase start
真正卡住人的地方往往不在安装步骤，而在环境变量命名规则、TypeScript 类型路径、以及 CLI 启动时对 Docker 进程状态的隐式依赖——这些点一旦漏掉一个，后续所有连接和补全都变成“看起来正常，实则失效”。
