Supabase CLI 仅是本地开发工具，真正运行 Supabase 服务需通过 Docker Compose 启动 PostgreSQL、Realtime、Auth 等全套后端组件；npm 或 brew 安装的只是命令行工具，不包含服务本身。
Linux 上安装 Supabase CLI 本身不等于“装好 Supabase”——它只是本地开发工具，真正运行 Supabase 服务必须靠 Docker Compose 启动一整套后端组件（PostgreSQL、Realtime、Auth、Storage 等）。直接用 npm install supabase 或 brew install supabase 只能得到命令行工具，无法启动数据库或实时服务。
supabase CLI 安装：选对方式，避开 Linux 权限陷阱
Supabase CLI 是你和本地/远程 Supabase 项目交互的入口，但 Linux 下容易卡在权限或依赖上：
- 别用
sudo npm install -g supabase：全局安装常因 Node.js 权限模型导致后续supabase start报EPERM或找不到二进制文件；推荐加--save-dev本地安装：npm i supabase --save-dev - Homebrew on Linux（linuxbrew）可行但冗余：需先装
gcc编译，且brew install supabase/tap/supabase实际下载的是预编译二进制，不是源码；若已装 Docker，CLI 工具完全够用，不必强求 brew - 验证是否真可用：运行
supabase -v后，立刻试supabase init—— 如果卡在 “Logging in…” 且浏览器打不开，说明系统默认浏览器未注册或 DISPLAY 环境变量缺失，此时改用supabase login --no-browser手动粘贴授权码
supabase start：本质是 docker-compose up，必须检查资源与端口
supabase start 命令背后会自动生成 docker-compose.yml 并执行 docker-compose up -d。它失败的常见原因和对策如下：
- 端口被占：默认占用
5432（PostgreSQL）、54321（Studio）、8000（API）、6000（Realtime）；用lsof -i :5432或ss -tulpn | grep ':5432'查冲突进程，杀掉或改.env中的POSTGRES_PORT - 内存不足：Supabase 全栈最低需 2GB 可用内存；
docker stats可看容器实际内存使用，若supabase_db进程频繁 OOM，需在docker-compose.yml的dbservice 下加mem_limit: 1.5g - 初始化卡住：首次
supabase start会拉镜像 + 初始化 DB schema + 生成密钥，耗时 2–5 分钟；若超 10 分钟无响应，查日志：docker logs supabase_db和docker logs supabase_kong，常见错误是password authentication failed for user "supabase_admin"，说明.env里PASSWORD不一致
配置文件 .env：service_role_key 和 anon_key 不是密码，别手动生成
Supabase 本地环境的认证密钥由 supabase start 自动写入 .env，手动改会导致前端 SDK 认证失败或 API 返回 401：
-
ANON_KEY和SERVICE_ROLE_KEY是 JWT 密钥派生的固定字符串，不是随机密码；修改后supabase db push会失败，因为 PostgREST 服务启动时已绑定该密钥 - 真正要改的只有
POSTGRES_PASSWORD和JWT_SECRET—— 前者影响数据库连接凭证，后者影响所有 JWT 签发；改完必须supabase stop && supabase start重启才生效 - 敏感值不要硬编码进 Git：把
.env加入.gitignore；团队协作时用supabase secrets set管理（仅限云项目），本地开发无需此步
验证服务是否真正就绪：别只看 terminal 的 “Started successfully”
终端显示 Started successfully 只代表容器启动了，不代表各服务已 ready。真实可用需三重确认：
- 数据库连得上：
psql -h localhost -p 5432 -U postgres -d postgres，输入POSTGRES_PASSWORD能进即通 - API 路由可访问：
curl -s http://localhost:8000/rest/v1/ | jq .应返回 JSON Schema（可能含 401，但非 404 或 connection refused） - Studio 打得开：
http://localhost:54321能加载登录页，且用项目初始邮箱（如admin@email.com）和你在supabase init时设的密码登录成功
最容易被忽略的是 Realtime 服务健康状态：WebSocket 连接不上时，supabase.channel(...).subscribe() 会静默失败，必须打开浏览器开发者工具 Network 标签页，过滤 ws://localhost:6000/ 看是否建立连接并收到 connected 消息。没这一步，实时功能就等于没启用。
