supabase cli安装失败或命令未找到的根本原因是node.js版本低于18.x或全局安装权限受限；需确认node --version≥18.0.0，避免混用nvm与系统node，改用npm install -g supabase --user并确保npm bin路径已加入$path。
supabase-cli 安装失败或 supabase 命令未找到
根本原因通常是 Node.js 版本不匹配或全局安装权限被限制。Supabase CLI 要求 Node.js ≥18.x，且不能混用 nvm 与系统自带 Node（尤其 macOS 上 Homebrew 安装的 Node 常引发冲突）。
实操建议：
- 先运行
node --version确认版本；若低于 18.0.0，卸载旧版，从 nodejs.org 下载 LTS（2026 年推荐 v18.20.2 或 v20.12.1） - 避免用
sudo npm install -g supabase；改用npm install -g supabase --user或通过 nvm 管理后执行nvm use 18再安装 - 安装后运行
supabase --version；若提示 “command not found”，检查npm config get prefix输出路径是否已加入$PATH（常见于 zsh 用户需在~/.zshrc中追加export PATH="$(npm config get prefix)/bin:$PATH"）
VS Code 中无法自动补全 supabase 客户端方法（如 from()、select()）
这不是插件问题，而是 TypeScript 类型定义缺失导致的——@supabase/supabase-js 包本身不带内建类型声明，需手动关联或启用自动推导。
实操建议：
- 确保项目根目录有
tsconfig.json，且包含"types": ["@supabase/supabase-js"]字段（若用 JS 项目，可新建jsconfig.json并启用"checkJs": true） - 不要只装
@supabase/supabase-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()等方法
本地开发时 supabase start 报错 “Failed to start PostgREST” 或 “port already in use”
Supabase CLI 的 supabase start 会启动一整套本地栈（PostgreSQL + PostgREST + Realtime + Storage），默认绑定 5432（DB）、3000（API）、54321（Studio）等端口。冲突多来自 Docker Desktop 预占或已有 PostgreSQL 进程。
实操建议：
- 先停掉本地其他 PostgreSQL：macOS 执行
brew services stop postgresql；Windows 检查服务列表中 “postgresql-x64” 是否运行 - 不要手动改
supabase/config.toml中的端口——CLI 会忽略它；正确方式是用环境变量覆盖：SUPABASE_API_PORT=3001 supabase start - 若 Docker Desktop 已开，确认其资源分配 ≥4GB RAM（低于此值常导致 PostgREST 启动超时）
- 首次运行后，访问
http://localhost:54321（Studio）前，务必等终端输出 “Started Supabase local development setup!” 再刷新，否则页面空白是正常现象
前端调用 supabase.auth.signInWithPassword() 却返回 “Email not confirmed” 或 400 错误
这和 Supabase 项目设置强相关，不是代码写错。免费计划默认开启邮箱确认流程，但本地开发时邮件服务未配置，导致用户注册后卡在 “unconfirmed” 状态。
实操建议：
- 进 Supabase 控制台 → “Authentication” → “Providers”，关闭 “Enable email confirmations”（仅限开发环境！上线前必须打开）
- 或保留确认流程，改用 “Email Provider” → “Test email” 功能，手动点击发送的测试链接完成确认
- 若用
supabase.auth.signInWithPassword()登录失败，先检查用户状态：supabase.auth.getUser()返回的user?.email_confirmed_at是否为null - 注意：关闭邮箱确认后，
auth.signInWithPassword()仍可能因密码强度不足报错，此时需在 “Authentication” → “Policies” → “Password requirements” 中临时调低最小长度
supabase start 启动后生成的 .env.local 文件——它里面的 SUPABASE_URL 和 SUPABASE_ANON_KEY 是本地地址（http://localhost:54321），而非控制台里看到的云端 URL。前端若硬编码了线上密钥，本地就永远连不上自己的数据库。
