Supabase开发环境搭建与本地部署指南
项目地址: https://gitcode.com/GitHub_Trending/supa/supabase 你还在为后端开发配置繁琐的数据库、认证和API服务而烦恼吗？本文将带你一步到位搭建Supabase本地开发环境，无需复杂云服务配置，即可拥有完整的Firebase替代方案。读完本文后，你将能够在本地运行Supabase全部服务，包括PostgreSQL数据库、身份验证、实时订阅和存储功能，并通过Studio界面轻松管理你的项目。
准备工作
在开始搭建Supabase开发环境前，请确保你的系统已安装以下工具：
- Git：用于克隆代码仓库
- Node.js v22.x或更高版本：运行JavaScript环境
- pnpm 9.x.x或更高版本：包管理工具
- make或操作系统对应的构建工具
- Docker：用于运行容器化服务
这些工具是Supabase本地开发的基础，确保它们都已正确安装并配置好环境变量。
克隆代码仓库
首先，我们需要获取Supabase的源代码。使用以下命令克隆官方仓库：
git clone https://gitcode.com/GitHub_Trending/supa/supabase
cd supabase
这将创建一个名为supa/supabase的目录，并下载所有必要的源代码文件。如果你计划贡献代码，可以先Fork仓库，然后克隆你自己的Fork版本。
安装依赖
进入项目目录后，执行以下命令安装所有依赖包：
pnpm install
这个命令会安装项目根目录和所有子项目所需的依赖。Supabase使用Turborepo管理多个应用和包，所以这一步可能需要几分钟时间，具体取决于你的网络速度和计算机性能。
配置环境变量
接下来，需要创建必要的环境变量文件。执行以下命令复制示例环境变量：
cp apps/www/.env.local.example apps/www/.env.local
这个文件包含了运行主网站所需的环境变量配置。对于大多数本地开发场景，使用默认值即可，但如果你需要自定义某些设置，可以编辑这个文件。
运行开发服务器
Supabase提供了多种运行方式，你可以选择同时运行所有应用，或者只运行你需要的部分。
运行所有应用
使用以下命令启动所有Supabase应用：
pnpm dev
这将启动以下服务：
| 应用 | 目录 | 本地地址 | 描述 |
|---|---|---|---|
| 主网站 | /apps/www | http://localhost:3000 | Supabase官方网站 |
| Studio控制台 | /apps/studio | http://localhost:8082 | 数据库管理界面 |
| 文档网站 | /apps/docs | http://localhost:3001/docs | 开发文档 |
单独运行应用
如果你只需要运行特定的应用，可以使用作用域名称：
pnpm dev:www # 只运行主网站
pnpm dev:studio # 只运行Studio控制台
pnpm dev:docs # 只运行文档网站
例如，要开发数据库相关功能，只需运行Studio控制台即可。
运行Docker容器
Supabase Studio需要Docker支持才能完整运行所有功能。按照以下步骤启动Docker容器：
cd docker
cp .env.example .env
docker compose up
第一条命令进入Docker配置目录，第二条复制环境变量示例文件，第三条启动所有必要的Docker容器。首次运行时，Docker会下载所需的镜像，这可能需要一些时间。
成功启动后，你可以通过访问http://localhost:8082打开Supabase Studio界面。这个界面提供了数据库管理、认证设置、存储配置等功能，与Supabase云服务的控制台类似。
Docker容器包含了PostgreSQL数据库、认证服务、实时服务器等所有必要组件，确保本地开发环境与生产环境尽可能一致。
项目结构解析
了解Supabase的项目结构有助于你更好地理解和定制系统。以下是主要目录的说明：
-
/apps：包含所有主要应用
- /apps/www：主网站代码 apps/www
- /apps/studio：管理控制台 apps/studio
- /apps/docs：文档网站 apps/docs
- /apps/cms：内容管理系统 apps/cms
- /apps/design-system：设计系统 apps/design-system
-
/packages：共享包和组件
- /packages/common：通用React组件 packages/common
- /packages/ui：UI组件库 packages/ui
- /packages/ai-commands：AI相关功能 packages/ai-commands
- /packages/config：共享配置 packages/config
-
/supabase：Supabase核心功能
- /supabase/migrations：数据库迁移脚本 supabase/migrations
- /supabase/functions：服务器函数 supabase/functions
-
/examples：示例项目和代码片段 examples
- /examples/auth：认证相关示例 examples/auth
- /examples/ai：AI功能示例 examples/ai
- /examples/todo-list：待办事项应用示例 examples/todo-list
-
/docker：Docker配置文件 docker
- /docker-compose.yml：Docker编排文件 docker/docker-compose.yml
这个结构采用了Monorepo模式，将多个相关项目组织在一个代码仓库中，便于共享代码和管理依赖。
数据库迁移
Supabase使用PostgreSQL数据库，数据库结构的变更通过迁移脚本管理。迁移文件位于supabase/migrations目录中。这些文件按时间戳命名，确保它们按正确顺序执行。
例如，最新的迁移文件包括：
这些迁移脚本定义了数据库模式、函数和触发器，是Supabase功能的核心实现。
开发示例应用
Supabase提供了丰富的示例项目，可以帮助你快速理解如何使用各种功能。以下是一些值得尝试的示例：
用户认证示例
examples/auth目录包含多种认证方式的实现：
- expo-social-auth：React Native社交登录
- flutter-mfa：Flutter多因素认证
- nextjs：Next.js认证实现
AI功能示例
examples/ai展示了Supabase的AI能力：
- image_search：图像搜索功能
- llamafile-edge：边缘函数中的LLM集成
- vector_hello_world：向量数据库入门
实时功能示例
examples/realtime展示了实时数据同步功能：
- flutter-figma-clone：协作设计工具示例
- nextjs-auth-presence：在线状态指示
- nextjs-authorization-demo：实时权限控制
尝试运行这些示例，可以帮助你快速掌握Supabase的核心功能和最佳实践。
构建和部署
当你完成开发并准备部署时，可以使用以下命令构建项目：
pnpm build
这将构建所有应用和包，并生成生产就绪的静态文件。构建产物位于各个应用的.next或dist目录中。
对于生产部署，Supabase提供了多种选项：
- 自托管：使用Docker Compose部署到你自己的服务器
- 云服务：使用Supabase官方托管服务
- 平台即服务：部署到Vercel、Netlify等平台
具体的部署步骤取决于你的目标环境，请参考官方文档获取详细指南。
常见问题解决
在搭建和使用Supabase本地开发环境时，可能会遇到一些常见问题。以下是一些解决方案：
Docker相关问题
如果Docker容器无法启动，尝试以下步骤：
- 检查Docker是否正在运行
- 执行
docker compose down停止所有容器 - 删除
docker/volumes目录中的数据 - 重新运行
docker compose up
依赖安装问题
如果依赖安装失败，尝试：
- 更新pnpm到最新版本：
npm install -g pnpm - 清除pnpm缓存：
pnpm store prune - 重新安装依赖：
pnpm install
端口冲突
如果启动服务时提示端口已被占用，可以修改相应应用的配置文件更改端口号，或者关闭占用端口的其他应用。
总结
通过本文的步骤，你已经成功搭建了Supabase的本地开发环境，并了解了项目结构和基本使用方法。现在你可以：
- 在本地开发和测试Supabase应用
- 使用Studio管理数据库和用户
- 探索丰富的示例项目
- 定制和扩展Supabase功能
Supabase提供了一个强大的开源替代方案，让你能够构建完整的后端服务，而无需依赖专有云服务。随着项目的不断发展，你可以通过参与贡献指南成为社区的一部分，帮助改进这个强大的工具。
无论是开发小型应用还是构建企业级系统，Supabase的本地开发环境都能提供一致、高效的开发体验，加速你的开发流程。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
