supabase命令未找到的根本原因是Node.js版本低于18.x或全局安装路径未加入PATH；需确保node --version≥18.20.2，改用npm install -g supabase --user，并将npm bin路径写入shell配置文件。
supabase 命令未找到：Node 和 CLI 安装必须严格匹配
VSCode 里敲 supabase --version 报 “command not found”，不是插件没装，而是 CLI 根本没进系统 PATH。根本原因有两个：Node.js 版本低于 18.x，或全局安装路径未被 shell 加载。
实操建议：
- 先运行
node --version，必须 ≥18.20.2（2026 年主流 LTS）；若不满足，卸载旧版，从nodejs.org下载安装，别用 Homebrew 或系统包管理器混装 - 避免
sudo npm install -g supabase；改用npm install -g supabase --user，再确认npm config get prefix输出的bin路径已写入 shell 配置（如~/.zshrc中追加export PATH="$(npm config get prefix)/bin:$PATH"） - Windows 用户优先用
scoop install supabase（需先scoop bucket add supabase），绕过 npm 权限陷阱
.env.local 中 VITE_SUPABASE_URL 为空：环境变量前缀和加载时机错不得
前端调用 createClient() 时控制台报 Cannot read properties of undefined (reading 'url')，90% 是因为 VITE_SUPABASE_URL 在运行时为 undefined —— 不是密钥错了，是根本没传进去。
实操建议：
-
.env.local必须放在项目根目录，且内容严格两行、无空格、无引号：VITE_SUPABASE_URL=https://xxx.supabase.coVITE_SUPABASE_ANON_KEY=eyJhbGciOi... - Vite 只暴露
VITE_开头的变量，写成SUPABASE_URL或REACT_APP_SUPABASE_URL都无效 - 改完
.env.local后必须重启开发服务器（npm run dev），Vite 不会热重载环境变量 - 在组件中务必用
import { createClient } from '@supabase/supabase-js'初始化，硬编码 URL 会导致部署到 Vercel 时无法注入真实值
supabase start 卡在 “starting…”：Docker daemon 没开或配置不对
执行 supabase start 后终端停住、无错误提示、浏览器打不开 http://localhost:54321，大概率是 Docker 没真正跑起来——尤其 Windows 用户，Docker Desktop 默认不暴露 daemon 接口。
实操建议：
- 先验证 Docker 是否就绪：
docker --version和docker ps都得成功返回（哪怕空列表） - Windows 用户：打开 Docker Desktop → Settings → General → ✅
Expose daemon on tcp://localhost:2375 without TLS - Mac 用户：确保 Docker Desktop 已启动，且未勾选 “Use the new Virtual Machine”（旧版 HyperKit 更稳）
- 端口冲突常见于本地已有 PostgreSQL 占了
5432，或 Studio 端口54323被其他服务占用；可编辑supabase/config.toml修改[ports]段，再supabase stop && supabase start
VSCode 里 supabaseClient.from().select() 不补全：TypeScript 类型没接上
敲 supabaseClient.from('users'). 后没智能提示 select()、insert()，不是插件问题，是 TypeScript 没识别到类型定义。
实操建议：
- 确保项目有
tsconfig.json，且含"types": ["@supabase/supabase-js"]字段；JS 项目则建jsconfig.json并启用"checkJs": true - 不要只装
@supabase/supabase-js，必须额外安装类型包：npm install -D @types/supabase__supabase-js - VSCode 中按
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win/Linux），输入 “Developer: Restart TS Server” 强制刷新类型服务 - 验证方式：在
createClient()调用后，把鼠标悬停在supabaseClient上，应看到完整泛型类型声明，而非any
最易被忽略的是 supabase status 这个命令——它不光告诉你连上了没，还明确列出当前 branch、API URL、函数端口、数据库状态。每次切换分支或重装后，别只信 linked successfully，一定要跑一次 supabase status 看输出是否完整可信。
