10分钟上手Supabase CLI：从安装到云函数部署的全流程指南

引言：为什么选择Supabase CLI？

你是否还在为Firebase的封闭生态感到受限？是否正在寻找一个开源、灵活且功能完备的后端解决方案？Supabase CLI（命令行界面）正是为解决这些痛点而生。作为Supabase生态系统的重要组成部分，这个强大的工具允许开发者在本地环境中高效管理Supabase项目，从数据库迁移到云函数部署，一应俱全。

读完本文后，你将能够：

• 快速安装和配置Supabase CLI
• 在本地启动和管理Supabase服务
• 创建、迁移和版本控制数据库
• 开发、测试和部署云函数
• 利用类型生成提升开发效率

1. Supabase CLI简介

Supabase CLI是一个功能强大的命令行工具，它为开发者提供了一套完整的本地开发和云部署工作流。通过这个工具，你可以轻松管理Supabase项目的各个方面，而无需依赖复杂的图形界面。

1.1 核心功能概览

功能	描述	重要性
本地开发环境	在本地启动完整的Supabase服务栈	⭐⭐⭐⭐⭐
数据库迁移	版本控制和部署数据库模式变更	⭐⭐⭐⭐⭐
云函数管理	创建、测试和部署边缘函数	⭐⭐⭐⭐
类型生成	从数据库模式自动生成TypeScript类型	⭐⭐⭐⭐
项目管理	连接和管理远程Supabase项目	⭐⭐⭐

1.2 工作流程概览

flowchart LR
    A[安装CLI] --> B[初始化项目]
    B --> C[启动本地服务]
    C --> D[开发数据库]
    C --> E[开发云函数]
    D --> F[创建迁移]
    E --> G[测试函数]
    F --> H[部署迁移]
    G --> I[部署函数]
    H --> J[监控和调试]
    I --> J

2. 安装与配置

2.1 系统要求

在开始安装前，请确保你的系统满足以下要求：

• Docker Engine (20.10.0或更高版本)
• Git
• 至少2GB可用内存
• 稳定的互联网连接

2.2 多平台安装指南

2.2.1 使用NPM安装（推荐）

对于Node.js开发者，使用NPM安装是最简单的方式：

npm i supabase --save-dev

如需安装测试版通道：

npm i supabase@beta --save-dev

注意：使用Bun版本低于v1.0.17时，需要先将supabase添加为可信依赖：

bun add -D --trusted supabase

2.2.2 macOS (Homebrew)

# 安装稳定版
brew install supabase/tap/supabase

# 安装测试版
brew install supabase/tap/supabase-beta
brew link --overwrite supabase-beta

# 升级
brew upgrade supabase

2.2.3 Windows (Scoop)

# 添加Supabase仓库
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git

# 安装
scoop install supabase

# 升级
scoop update supabase

2.2.4 Linux

使用Homebrew：

brew install supabase/tap/supabase
brew upgrade supabase

使用系统包管理器：

# Debian/Ubuntu
sudo dpkg -i <下载的.deb文件>

# Fedora/RHEL
sudo rpm -i <下载的.rpm文件>

# Arch Linux
sudo pacman -U <下载的.pkg.tar.zst文件>

2.2.5 从源码安装

对于Go开发者，可以直接从源码安装：

# 需要Go 1.22或更高版本
go install github.com/supabase/cli@latest

# 创建符号链接以便全局访问
ln -s "$(go env GOPATH)/bin/cli" /usr/bin/supabase

2.3 验证安装

安装完成后，运行以下命令验证是否成功：

supabase --version

你应该能看到类似以下的输出：

supabase version 1.160.0

2.4 配置国内镜像（针对中国用户）

为了提高国内用户的访问速度，可以配置GitCode镜像：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/cli23/cli.git
cd cli

# 安装依赖
go mod download

# 构建并安装
go install .

3. 快速入门：第一个项目

3.1 初始化项目

让我们通过一个简单的命令创建并配置你的第一个Supabase项目：

# 创建项目目录
mkdir my-supabase-project
cd my-supabase-project

# 使用bootstrap命令快速设置项目
supabase bootstrap

bootstrap命令会引导你完成项目设置，包括：

1. 选择项目模板
2. 配置数据库
3. 设置认证选项
4. 初始化Git仓库（可选）

3.2 启动本地开发环境

项目初始化完成后，启动本地Supabase服务：

supabase start

首次运行时，这个命令会下载所需的Docker镜像，可能需要几分钟时间。成功启动后，你将看到类似以下的输出：

Started supabase local development setup.

         API URL: http://localhost:54321
     GraphQL URL: http://localhost:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: <your-jwt-secret>
        anon key: <your-anon-key>
service_role key: <your-service-role-key>

现在，你可以通过Studio URL（通常是http://localhost:54323）访问Supabase Studio，这是一个基于Web的数据库管理界面。

3.3 项目结构解析

supabase bootstrap命令创建的项目结构如下：

my-supabase-project/
├── .env.local           # 本地环境变量
├── .gitignore           # Git忽略文件
├── README.md            # 项目说明文档
├── supabase/            # Supabase配置目录
│   ├── config.toml      # 项目配置
│   ├── migrations/      # 数据库迁移文件
│   ├── functions/       # 边缘函数
│   ├── seed.sql         # 数据库种子数据
│   └── schema.sql       # 数据库模式定义
└── package.json         # 项目依赖

4. 数据库管理

4.1 数据库连接

Supabase CLI提供了多种连接数据库的方式：

# 使用psql连接数据库
supabase db remote connect

# 直接执行SQL命令
supabase db sql "SELECT NOW();"

# 执行SQL文件
supabase db sql -f path/to/file.sql

4.2 数据库迁移

数据库迁移是版本控制数据库模式变更的关键功能。使用Supabase CLI，你可以轻松创建和应用迁移：

# 创建新的迁移文件
supabase db new add_users_table

# 这会创建一个类似 supabase/migrations/20231101000000_add_users_table.sql 的文件

编辑生成的SQL文件，添加你的表定义：

-- Create users table
CREATE TABLE public.users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  full_name TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Set up Row Level Security (RLS)
ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Allow read access for authenticated users" ON public.users
  FOR SELECT USING (auth.role() = 'authenticated');

应用迁移：

# 应用所有未应用的迁移
supabase db push

# 查看迁移历史
supabase db migration list

4.3 数据导入与导出

# 导出数据库
supabase db dump -f backup.sql

# 导入数据
supabase db reset --import backup.sql

# 仅导入种子数据
supabase db seed

4.4 数据库分支管理

Supabase CLI支持创建数据库分支，用于并行开发：

# 创建新分支
supabase branches create feature-branch

# 切换分支
supabase branches activate feature-branch

# 列出所有分支
supabase branches list

# 删除分支
supabase branches delete feature-branch

5. 云函数开发

Supabase Edge Functions是基于Deno的无服务器函数，可以在全球边缘网络上运行。

5.1 创建你的第一个云函数

# 创建新函数
supabase functions new hello-world

这会在supabase/functions/hello-world目录下创建一个新的函数模板：

// supabase/functions/hello-world/index.ts
Deno.serve(async (req) => {
  const { name } = await req.json();
  const data = {
    message: `Hello ${name}!`,
  };

  return new Response(
    JSON.stringify(data),
    { headers: { "Content-Type": "application/json" } },
  );
});

5.2 本地测试云函数

# 启动函数本地服务器
supabase functions serve hello-world --no-verify-jwt

使用curl或Postman测试函数：

curl -i --location --request POST 'http://localhost:54321/functions/v1/hello-world' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Supabase"}'

5.3 部署云函数

测试通过后，部署到Supabase：

# 部署单个函数
supabase functions deploy hello-world

# 部署所有函数
supabase functions deploy --all

# 部署时设置环境变量
supabase functions deploy hello-world --env-file .env.production

5.4 云函数高级配置

函数可以通过supabase/functions/hello-world/config.json文件进行配置：

{
  "noVerifyJwt": false,
  "environment": {
    "API_KEY": "your-api-key"
  },
  "schedule": {
    "type": "cron",
    "value": "0 0 * * *"
  }
}

6. 类型生成

Supabase CLI可以从你的数据库模式自动生成TypeScript类型，提高开发效率和代码质量。

6.1 生成类型定义

# 生成类型
supabase gen types typescript --local > types/supabase.ts

6.2 在项目中使用生成的类型

import { Database } from '../types/supabase';

// 类型化的数据库客户端
const supabaseClient = createClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// 使用类型提示
const getUsers = async () => {
  const { data, error } = await supabaseClient
    .from('users')
    .select('id, email, full_name')
    .order('created_at', { ascending: false });
  
  if (error) throw error;
  return data;
};

7. 项目部署与协作

7.1 连接到远程项目

# 登录Supabase
supabase login

# 链接到远程项目
supabase link --project-ref <your-project-ref>

项目引用（project-ref）可以在Supabase项目控制台的设置 > API中找到。

7.2 部署数据库变更

# 将本地迁移推送到远程
supabase db push

# 从远程拉取最新变更
supabase db pull

7.3 团队协作工作流

sequenceDiagram
    participant Dev1
    participant Dev2
    participant Git
    participant Supabase Cloud
    
    Dev1->>Dev1: 创建迁移文件
    Dev1->>Git: 提交迁移
    Dev2->>Git: 拉取迁移
    Dev2->>Dev2: 本地测试迁移
    Dev1->>Supabase Cloud: 部署迁移
    Dev2->>Supabase Cloud: 验证部署

8. 高级功能

8.1 备份与恢复

# 创建数据库备份
supabase backups create

# 列出所有备份
supabase backups list

# 恢复备份
supabase backups restore <backup-id>

8.2 自定义域名配置

# 添加自定义域名
supabase domains add api.example.com

# 验证域名
supabase domains verify api.example.com

# 列出所有域名
supabase domains list

8.3 监控与日志

# 查看函数日志
supabase functions logs hello-world

# 实时监控函数
supabase functions logs hello-world --follow

# 查看数据库性能指标
supabase inspect db-table-sizes

9. 常见问题与解决方案

9.1 本地开发环境问题

问题	解决方案
端口冲突	使用--port参数指定自定义端口，如supa base start --port 55000
Docker镜像拉取缓慢	配置Docker国内镜像源，或优化网络连接
服务启动失败	检查Docker是否正在运行，执行supa base stop后再试

9.2 数据库迁移问题

问题	解决方案
迁移冲突	使用supa base db diff生成冲突解决迁移
迁移回滚	创建反向迁移文件，使用supa base db new rollback_migration
数据丢失风险	始终在迁移前创建备份，使用supa base backups create

9.3 云函数部署问题

问题	解决方案
部署超时	增加函数内存或超时时间配置
依赖问题	使用import_map.json管理函数依赖
权限错误	检查函数服务角色权限，确保有足够权限访问资源

10. 总结与下一步

通过本文，你已经掌握了Supabase CLI的核心功能，包括项目初始化、本地开发、数据库管理、云函数开发和项目部署。Supabase CLI提供了一个完整的开发工作流，让你能够在本地环境中高效开发，然后无缝部署到云端。

10.1 进阶学习资源

• 官方文档：Supabase CLI参考
• 示例项目：Supabase示例库
• 社区论坛：Supabase社区

10.2 推荐工作流

1. 使用supabase start启动本地开发环境
2. 使用Supabase Studio设计数据库模式
3. 使用supabase db new创建迁移文件
4. 使用supabase functions new开发云函数
5. 使用supabase functions serve测试函数
6. 提交代码到Git仓库
7. 使用supabase db push和supabase functions deploy部署变更
8. 使用supabase inspect和日志监控应用性能

10.3 结语

Supabase CLI彻底改变了后端开发的方式，让开发者能够以更高的效率构建全栈应用。无论你是个人开发者还是大型团队的一员，Supabase CLI都能为你提供一致、可靠的开发体验。

立即开始使用Supabase CLI，体验开源Firebase替代品的强大功能吧！

---

如果觉得本文对你有帮助，请点赞、收藏并关注作者，获取更多Supabase开发技巧和最佳实践。下期预告：《Supabase实时订阅高级用法》。