Supabase 开源仓库本地开发指南Turborepo 多站点联调、Docker 运行 Studio 与联邦文档机制【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase本文以 Supabase 开源仓库根目录下的 DEVELOPERS.md 为核心系统讲解如何搭建该仓库的本地开发环境从 Node/pnpm 版本约束、Turborepo 多站点并行开发到用 Docker 在本地跑通 Supabase Studio再到添加站点重定向、接入外部“联邦文档”等高频开发任务。读完本文你可以独立完成仓库克隆、三个核心站点www / studio / docs的本地联调并理解 docs 构建管线如何自动拉取外部仓库的文档内容。一、仓库形态与开发依赖1.1 Turborepo 单仓多应用结构该仓库是一个典型的 Turborepo 单体仓库所有面向用户的站点官网 www、Studio 控制台、docs 文档站、design-system、learn、kb 等集中在 apps/ 目录下共享代码与配置集中在 packages/ 目录另有 docker/ 目录提供本地 Docker 化的 Supabase 全栈环境、e2e/ 目录存放 Playwright 端到端测试、examples/ 目录存放各框架示例项目。根目录的 pnpm-workspace.yaml 定义 workspace 成员turbo.jsonc 定义跨项目的任务编排。从 turbo.jsonc 可以看到关键的任务配置builddependsOn: [^build]即构建某应用前会先构建它依赖的 workspace 包产物缓存dist/**与.next/**排除.next/cache与.next/devdevcache: false且persistent: true即开发服务器长驻运行、不做任务缓存——这正是pnpm dev能够“同时启动所有应用”且互不阻塞的底层原因test不缓存、typecheck依赖上游包的 typecheck。因此你在开发时执行pnpm dev本质上是 turbo 并行拉起所有 workspace 的dev任务各站点互不干扰。1.2 必须安装的依赖与版本约束DEVELOPERS.md 列出的五个必装依赖可以结合仓库内的实际配置确定精确版本依赖版本约束仓库依据Git任意可用版本用于 clone/fork 流程Node.js22.nvmrc内容为22且engines.node 22.13.nvmrc、package.jsonpnpm11.13.1package.json 的packageManager: pnpm11.13.1字段make或对应平台的 build-essentials任意可用版本构建脚本使用Docker任意可用版本本地运行 Studio 全栈所需两个值得注意的工程细节根 package.json 中的preinstall: npx only-allow pnpm会强制安装器只能是 pnpm用 npm/yarn 安装会在 preinstall 阶段直接失败.nvmrc只写了一个主版本号22配合package.json的engines字段node 22.13、pnpm 11.13实际环境应安装 Node 22 的较新小版本并让 corepack 或包管理器按packageManager字段自动匹配 pnpm 11.13.1。二、本地开发标准流程2.1 Fork、克隆与安装依赖按 DEVELOPERS.md 的步骤Fork 上游仓库后克隆你自己的 forkgit clone https://github.com/github_username/supabase.git cd supabase在仓库根目录安装依赖pnpm install复制 www 站点的本地环境变量示例文件cp apps/www/.env.local.example apps/www/.env.local该示例文件 apps/www/.env.local.example 确实存在于仓库中是 www 站点本地启动的必需前置条件单独跑 www 时尤其注意。并行启动所有应用pnpm dev启动后文档给出的三个核心站点及其本地端口如下站点目录Scope 名说明本地地址supabase.comapps/wwwwww主官网http://localhost:3000Studio 控制台apps/studiostudio需要 Docker见第四节http://localhost:8082supabase.com/docsapps/docsdocsGuides 与 Reference 文档站Next.jshttp://localhost:3001/docs2.2 单独启动某个站点利用 scope 名可以只启动单个站点例如pnpm dev:www从根 package.json 的 scripts 可以看到这套命令的完整清单全部通过turbo run dev --filterscope实现过滤dev:www/dev:docs/dev:studio/dev:kb/dev:design-system按 scope 单独启动dev:studio-local先执行pnpm setup:cli即supabase start -x studio后用supabase status生成keys.json再经 scripts/generateLocalEnv.js 生成本地 env再以NODE_ENVtest MODEtest启动 studio——这是用 Supabase CLI 的本地环境联调 Studio 的快捷路径。针对 docs 站点的补充约定环境变量、AI 友好的 Markdown 生成、无障碍检查等单独写在 apps/docs/DEVELOPERS.md其中明确社区贡献者需要手动创建apps/docs/.env.local并写入NEXT_PUBLIC_IS_PLATFORMfalse然后访问 http://localhost:3001/docs注意末尾必须带/docs。2.3 共享包与 workspace 内安装依赖Monorepo 在 packages/ 下维护一组共享包DEVELOPERS.md 列出的核心几个为packages/ai-commandsAI 相关功能的 Helper/Commandspackages/common所有站点共享的 React 组件认证、遥测、feature flag 等packages/config共享配置Tailwind、typography、code-hike 代码高亮主题等packages/shared-data跨应用共享的数据区域、套餐、错误码等packages/tsconfig共享 TypeScript 配置base.json、nextjs.json、react-library.jsonpackages/ui 与 packages/ui-patterns通用 UI 组件与组合模式。在某个 workspace 内安装新依赖时需要先cd进入该目录再执行安装例如cd apps/studio pnpm add react这样依赖只会写入该 workspace 自己的package.json不会污染其他项目。三、用 Docker 在本地运行 Supabase StudioDEVELOPERS.md 指出Studio 是一个 Next.js 前端但它需要后端的真实 Supabase 服务数据库、Auth、Storage 等才能完整联调因此要额外启动 Docker 环境。仓库的 docker/ 目录就是为本地开发准备的完整自托管栈进入 docker 目录cd docker复制环境变量示例文件cp .env.example .envdocker/.env.example 覆盖了数据库口令、JWT 密钥、Auth URL 等全部可配置项仓库同时提供 docker/CONFIG.md 解释各项配置的语义与取值范围以及 docker/README.md 说明目录组织。启动容器docker compose up该命令初始化 docker/docker-compose.yml 中定义的容器Kong 网关、Postgres、GoTrue Auth、Storage、Realtime、Studio 等。首次启动需要拉取镜像耗时取决于机器与网络。完成后访问 http://localhost:8082 即可看到本地运行中的 Supabase。文档特别强调只要还在使用本地 Supabase 实例就必须保持 Docker 容器运行。此外该目录还有若干变体 compose 文件如 docker/docker-compose.kong.yml、docker/docker-compose.pg17.yml、docker/docker-compose.pgbouncer.yml分别对应不同网关/Postgres 版本/连接池的组合可按需切换docker/下的reset.sh、setup.sh、update.sh用于重置、初始化与版本升级。四、常见开发任务4.1 添加站点重定向DEVELOPERS.md 指出给主站添加重定向只需在主站的重定向文件中新增一条条目。对应文件在当前仓库中为 apps/www/lib/redirects.js在 www 的 Next.js 配置中生效新增规则后本地pnpm dev:www即可验证 301/308 行为。4.2 联邦文档Federated Docsdocs 站支持“联邦”机制文档内容可以直接来自supabase/supabase之外的外部仓库例如客户端库supabase/vecs自带文档无需复制、无需手动同步而是在 docs 构建管线中自动拉取并生成且嵌入后在 Supabase 文档中呈现为原生页面。其工作原理与仓库中的实现证据构建期拉取机制依托 Next.js 构建管线——通过构建时获取远端 markdown 并处理为对应页面。仓库中 apps/docs/scripts/federated-content/fetch-federated-content.ts 就是拉取联邦内容的脚本入口参考实现以 Vecs 为例的完整实现位于 apps/docs/app/guides/ai/python/ 下的[[...slug]]动态路由目录接入其他外部文档时可直接以此为起点链接转换外部 markdown 中的相对链接渲染到 Supabase 文档后通常无法一一对应需要使用 rehype 插件做链接转换实现见 apps/docs/lib/mdx/plugins/rehypeLinkTransform.tsmarkdown 扩展兼容外部文档可能使用了 Supabase 文档默认不支持的语法扩展例如 mkdocs-material 的 Admonition 语法仓库为此专门构建了 remark 插件apps/docs/lib/mdx/plugins/remarkAdmonition.test.ts 即为 Admonition 插件的配套测试若需要尚未支持的扩展按文档建议开 Issue 与官方协作实现。五、协作与贡献流程DEVELOPERS.md 对贡献流程的约定值得在动手前读一遍Pull Request完成改动后直接开 PR由维护者评审合并后贡献者会出现在仓库的 contributor 列表中Issue 分配仓库没有issue 分配流程任何人可以直接认领任何 issue。为避免重复 PR文档建议在 Issue 下尽早、频繁地留言表明自己正在处理若发现已有他人提交了对应 PR优先与原作者协作而不是另开一份PR 评审顺序按提交顺序评审倾向于接受最早且最接近可合并状态的那一份。六、小结环境三要素Node 22.nvmrc、pnpm 11.13.1package.json 的packageManager、Docker仅 Studio 全栈联调需要核心工作流pnpm install→ 复制 apps/www/.env.local.example →pnpm dev再按需用dev:www/dev:docs/dev:studio单站点调试Studio 本地联调cd docker cp .env.example .env docker compose up端口 8082高频任务重定向条目写入 apps/www/lib/redirects.js外部文档接入参照 apps/docs/app/guides/ai/python/ 的联邦文档实现与 rehypeLinkTransform.ts 链接转换插件。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Supabase 开源仓库本地开发指南：Turborepo 多站点联调、Docker 运行 Studio 与联邦文档机制
Supabase 开源仓库本地开发指南Turborepo 多站点联调、Docker 运行 Studio 与联邦文档机制【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase本文以 Supabase 开源仓库根目录下的 DEVELOPERS.md 为核心系统讲解如何搭建该仓库的本地开发环境从 Node/pnpm 版本约束、Turborepo 多站点并行开发到用 Docker 在本地跑通 Supabase Studio再到添加站点重定向、接入外部“联邦文档”等高频开发任务。读完本文你可以独立完成仓库克隆、三个核心站点www / studio / docs的本地联调并理解 docs 构建管线如何自动拉取外部仓库的文档内容。一、仓库形态与开发依赖1.1 Turborepo 单仓多应用结构该仓库是一个典型的 Turborepo 单体仓库所有面向用户的站点官网 www、Studio 控制台、docs 文档站、design-system、learn、kb 等集中在 apps/ 目录下共享代码与配置集中在 packages/ 目录另有 docker/ 目录提供本地 Docker 化的 Supabase 全栈环境、e2e/ 目录存放 Playwright 端到端测试、examples/ 目录存放各框架示例项目。根目录的 pnpm-workspace.yaml 定义 workspace 成员turbo.jsonc 定义跨项目的任务编排。从 turbo.jsonc 可以看到关键的任务配置builddependsOn: [^build]即构建某应用前会先构建它依赖的 workspace 包产物缓存dist/**与.next/**排除.next/cache与.next/devdevcache: false且persistent: true即开发服务器长驻运行、不做任务缓存——这正是pnpm dev能够“同时启动所有应用”且互不阻塞的底层原因test不缓存、typecheck依赖上游包的 typecheck。因此你在开发时执行pnpm dev本质上是 turbo 并行拉起所有 workspace 的dev任务各站点互不干扰。1.2 必须安装的依赖与版本约束DEVELOPERS.md 列出的五个必装依赖可以结合仓库内的实际配置确定精确版本依赖版本约束仓库依据Git任意可用版本用于 clone/fork 流程Node.js22.nvmrc内容为22且engines.node 22.13.nvmrc、package.jsonpnpm11.13.1package.json 的packageManager: pnpm11.13.1字段make或对应平台的 build-essentials任意可用版本构建脚本使用Docker任意可用版本本地运行 Studio 全栈所需两个值得注意的工程细节根 package.json 中的preinstall: npx only-allow pnpm会强制安装器只能是 pnpm用 npm/yarn 安装会在 preinstall 阶段直接失败.nvmrc只写了一个主版本号22配合package.json的engines字段node 22.13、pnpm 11.13实际环境应安装 Node 22 的较新小版本并让 corepack 或包管理器按packageManager字段自动匹配 pnpm 11.13.1。二、本地开发标准流程2.1 Fork、克隆与安装依赖按 DEVELOPERS.md 的步骤Fork 上游仓库后克隆你自己的 forkgit clone https://github.com/github_username/supabase.git cd supabase在仓库根目录安装依赖pnpm install复制 www 站点的本地环境变量示例文件cp apps/www/.env.local.example apps/www/.env.local该示例文件 apps/www/.env.local.example 确实存在于仓库中是 www 站点本地启动的必需前置条件单独跑 www 时尤其注意。并行启动所有应用pnpm dev启动后文档给出的三个核心站点及其本地端口如下站点目录Scope 名说明本地地址supabase.comapps/wwwwww主官网http://localhost:3000Studio 控制台apps/studiostudio需要 Docker见第四节http://localhost:8082supabase.com/docsapps/docsdocsGuides 与 Reference 文档站Next.jshttp://localhost:3001/docs2.2 单独启动某个站点利用 scope 名可以只启动单个站点例如pnpm dev:www从根 package.json 的 scripts 可以看到这套命令的完整清单全部通过turbo run dev --filterscope实现过滤dev:www/dev:docs/dev:studio/dev:kb/dev:design-system按 scope 单独启动dev:studio-local先执行pnpm setup:cli即supabase start -x studio后用supabase status生成keys.json再经 scripts/generateLocalEnv.js 生成本地 env再以NODE_ENVtest MODEtest启动 studio——这是用 Supabase CLI 的本地环境联调 Studio 的快捷路径。针对 docs 站点的补充约定环境变量、AI 友好的 Markdown 生成、无障碍检查等单独写在 apps/docs/DEVELOPERS.md其中明确社区贡献者需要手动创建apps/docs/.env.local并写入NEXT_PUBLIC_IS_PLATFORMfalse然后访问 http://localhost:3001/docs注意末尾必须带/docs。2.3 共享包与 workspace 内安装依赖Monorepo 在 packages/ 下维护一组共享包DEVELOPERS.md 列出的核心几个为packages/ai-commandsAI 相关功能的 Helper/Commandspackages/common所有站点共享的 React 组件认证、遥测、feature flag 等packages/config共享配置Tailwind、typography、code-hike 代码高亮主题等packages/shared-data跨应用共享的数据区域、套餐、错误码等packages/tsconfig共享 TypeScript 配置base.json、nextjs.json、react-library.jsonpackages/ui 与 packages/ui-patterns通用 UI 组件与组合模式。在某个 workspace 内安装新依赖时需要先cd进入该目录再执行安装例如cd apps/studio pnpm add react这样依赖只会写入该 workspace 自己的package.json不会污染其他项目。三、用 Docker 在本地运行 Supabase StudioDEVELOPERS.md 指出Studio 是一个 Next.js 前端但它需要后端的真实 Supabase 服务数据库、Auth、Storage 等才能完整联调因此要额外启动 Docker 环境。仓库的 docker/ 目录就是为本地开发准备的完整自托管栈进入 docker 目录cd docker复制环境变量示例文件cp .env.example .envdocker/.env.example 覆盖了数据库口令、JWT 密钥、Auth URL 等全部可配置项仓库同时提供 docker/CONFIG.md 解释各项配置的语义与取值范围以及 docker/README.md 说明目录组织。启动容器docker compose up该命令初始化 docker/docker-compose.yml 中定义的容器Kong 网关、Postgres、GoTrue Auth、Storage、Realtime、Studio 等。首次启动需要拉取镜像耗时取决于机器与网络。完成后访问 http://localhost:8082 即可看到本地运行中的 Supabase。文档特别强调只要还在使用本地 Supabase 实例就必须保持 Docker 容器运行。此外该目录还有若干变体 compose 文件如 docker/docker-compose.kong.yml、docker/docker-compose.pg17.yml、docker/docker-compose.pgbouncer.yml分别对应不同网关/Postgres 版本/连接池的组合可按需切换docker/下的reset.sh、setup.sh、update.sh用于重置、初始化与版本升级。四、常见开发任务4.1 添加站点重定向DEVELOPERS.md 指出给主站添加重定向只需在主站的重定向文件中新增一条条目。对应文件在当前仓库中为 apps/www/lib/redirects.js在 www 的 Next.js 配置中生效新增规则后本地pnpm dev:www即可验证 301/308 行为。4.2 联邦文档Federated Docsdocs 站支持“联邦”机制文档内容可以直接来自supabase/supabase之外的外部仓库例如客户端库supabase/vecs自带文档无需复制、无需手动同步而是在 docs 构建管线中自动拉取并生成且嵌入后在 Supabase 文档中呈现为原生页面。其工作原理与仓库中的实现证据构建期拉取机制依托 Next.js 构建管线——通过构建时获取远端 markdown 并处理为对应页面。仓库中 apps/docs/scripts/federated-content/fetch-federated-content.ts 就是拉取联邦内容的脚本入口参考实现以 Vecs 为例的完整实现位于 apps/docs/app/guides/ai/python/ 下的[[...slug]]动态路由目录接入其他外部文档时可直接以此为起点链接转换外部 markdown 中的相对链接渲染到 Supabase 文档后通常无法一一对应需要使用 rehype 插件做链接转换实现见 apps/docs/lib/mdx/plugins/rehypeLinkTransform.tsmarkdown 扩展兼容外部文档可能使用了 Supabase 文档默认不支持的语法扩展例如 mkdocs-material 的 Admonition 语法仓库为此专门构建了 remark 插件apps/docs/lib/mdx/plugins/remarkAdmonition.test.ts 即为 Admonition 插件的配套测试若需要尚未支持的扩展按文档建议开 Issue 与官方协作实现。五、协作与贡献流程DEVELOPERS.md 对贡献流程的约定值得在动手前读一遍Pull Request完成改动后直接开 PR由维护者评审合并后贡献者会出现在仓库的 contributor 列表中Issue 分配仓库没有issue 分配流程任何人可以直接认领任何 issue。为避免重复 PR文档建议在 Issue 下尽早、频繁地留言表明自己正在处理若发现已有他人提交了对应 PR优先与原作者协作而不是另开一份PR 评审顺序按提交顺序评审倾向于接受最早且最接近可合并状态的那一份。六、小结环境三要素Node 22.nvmrc、pnpm 11.13.1package.json 的packageManager、Docker仅 Studio 全栈联调需要核心工作流pnpm install→ 复制 apps/www/.env.local.example →pnpm dev再按需用dev:www/dev:docs/dev:studio单站点调试Studio 本地联调cd docker cp .env.example .env docker compose up端口 8082高频任务重定向条目写入 apps/www/lib/redirects.js外部文档接入参照 apps/docs/app/guides/ai/python/ 的联邦文档实现与 rehypeLinkTransform.ts 链接转换插件。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考