自定义域名

自定义域名允许您为用户提供品牌化的体验。该功能作为付费计划项目的附加服务提供。

Supabase 支持两种域名类型：

1. 自定义域名：使用如 api.example.com 这样的域名替代项目的默认域名
2. 个性化子域名（实验性）：可以在 supabase.co 上为您的项目设置不同的子域名

您可以为每个项目选择自定义域名或个性化子域名。

自定义域名

自定义域名会改变项目URL在用户面前的显示方式。这在以下场景中特别有用：

• 当您使用OAuth（社交登录）与Supabase Auth时，项目URL会显示在OAuth授权界面上
• 当您为第三方系统创建API时，例如通过边缘函数实现webhook或外部API调用
• 当您在数据库中存储URL或将其编码到二维码中时

自定义域名有助于长期保持API的可移植性。通过使用自定义域名，您可以轻松地在不同Supabase项目间迁移，或为未来的API版本控制提供便利。

通过Supabase仪表板配置自定义域名#

在仪表板的常规设置页面中，按照自定义域名的步骤为您的项目设置自定义域名。

使用 Supabase CLI 配置自定义域名#

本示例假设您的 Supabase 项目 ID 为 abcdefghijklmnopqrst，对应 API URL 为 abcdefghijklmnopqrst.supabase.co，并将在 api.example.com 配置自定义域名。

开始前请确保：

1. 安装最新版本的 Supabase CLI
2. 使用 CLI 登录您的 Supabase 账户
3. 确认您对该项目拥有所有者或管理员权限
4. 从 DNS 提供商处获取自定义域名（目前仅支持子域名）
   • 使用 api.example.com 而非 example.com

添加 CNAME 记录#

您需要在域名的 DNS 设置中添加 CNAME 记录，以确保自定义域名指向 Supabase 项目。

如果您的项目默认域名为 abcdefghijklmnopqrst.supabase.co，您应该：

• 为 api.example.com 创建 CNAME 记录，解析至 abcdefghijklmnopqrst.supabase.co.
• 使用较低的 TTL 值以便在配置出错时快速传播变更

验证域名所有权

在 Supabase 注册您的域名以证明所有权。您需要下载两个 TXT 记录并将其添加到 DNS 设置中。

在 CLI 中运行 domains create 命令，在 Supabase 注册域名并获取验证记录：

1
supabase domains create --project-ref abcdefghijklmnopqrst --custom-hostname api.example.com

系统会返回一个 TXT 记录。例如：

1
2
3
[...]需要完成的验证记录：        _acme-challenge.api.example.com. TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q

将该记录添加到您的域名 DNS 设置中。确保去除前后空格。使用较低的 TTL 值，以便在出错时能快速修改记录。

某些域名注册商会自动将您的域名附加到正在创建的 DNS 条目中。因此，为 api.example.com 创建 DNS 记录可能会变成 api.example.com.example.com。这种情况下，请从您创建的记录中移除域名部分。例如，您应该为 api 创建 TXT 记录，而不是 api.example.com。

验证您的域名

确保您已配置所有必需的 DNS 设置：

• 指向 Supabase 项目域名的自定义域名的 CNAME 记录
• _acme-challenge.<您的自定义域名> 的 TXT 记录

使用 domains reverify 命令开始域名验证流程。由于 DNS 记录传播需要时间，您可能需要多次运行此命令。

1
supabase domains reverify --project-ref abcdefghijklmnopqrst

在后台，Supabase 会检查您的 DNS 记录并使用 Let's Encrypt 为您的域名颁发 SSL 证书。此过程最多可能需要 30 分钟。

准备激活您的域名

在激活域名之前，请为您的应用程序和集成做好域名变更准备：

• 项目的 Supabase 域名仍保持活跃状态
  • 您无需立即更改应用程序中的 Supabase URL
  • 可以将其与自定义域名交替使用
• Supabase Auth 将在激活后立即使用自定义域名
  • OAuth 流程会将自定义域名作为回调 URL 进行通告
  • SAML 将改用自定义域名。这意味着您项目的 EntityID 已变更，可能导致现有身份提供商的 SAML 停止工作

为避免影响用户使用，请按以下步骤操作：

1. 为每个 Supabase OAuth 提供商：

   • 在提供商的开发者控制台（非 Supabase 仪表盘）中，找到 OAuth 应用并添加自定义域名的 Supabase Auth 回调 URL 同时保留原项目 URL。例如：
     • https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback 和
     • https://api.example.com/auth/v1/callback
   • Twitter 登录使用与项目域名绑定的 cookies。请确保前端代码使用自定义域名而非默认项目域名。

2. 为每个 SAML 身份提供商：

   • 联系您的提供商，要求他们更新 SAML 应用的元数据。应使用 https://api.example.com/auth/v1/... 替代 https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}
   • 完成这些变更后，在域名激活前 SAML 单点登录可能会暂时失效。请提前做好相应规划

激活您的域名

当您完成项目新域名激活的必要准备工作后，可以使用 domains activate CLI 命令来激活它。

1
supabase domains activate --project-ref abcdefghijklmnopqrst

此步骤完成后，Supabase 将从您的新域名提供服务。Supabase 项目域名仍可继续使用，因此您无需急于更改客户端代码中的URL。

如果希望在客户端代码中使用新域名，请修改 Supabase 客户端库中使用的URL：

1
2
3
4
import { createClient } from '@supabase/supabase-js'// 使用自定义域名作为 supabase URLconst supabase = createClient('https://api.example.com', 'public-anon-key')

同样地，您的边缘函数现在将通过 https://api.example.com/functions/v1/your_function_name 访问，存储对象则通过 https://api.example.com/storage/v1/object/public/your_file_path.ext 访问。

移除自定义域名

移除自定义域名可能会在使用 Supabase Auth 与 OAuth 或 SAML 时导致一些问题。您可能需要撤销在_准备激活您的域名_步骤中所做的更改。

要移除已激活的自定义域名，可以使用 domains delete CLI 命令。

1
supabase domains delete --project-ref abcdefghijklmnopqrst

自定义子域名

相比完全自定义域名，自定义子域名允许您展示基本的品牌化体验。它使您能够在Supabase上使用自定义子域名托管服务（例如my-example-brand.supabase.co），而不是默认随机分配的abcdefghijklmnopqrst.supabase.co。

开始使用前需要：

1. 安装最新版本的Supabase CLI
2. 通过CLI登录您的Supabase账户
3. 确保您对目标项目拥有所有者或管理员权限
4. 确保您的组织在仪表盘账单页面已升级到付费计划（专业版/团队版/企业版）

配置自定义子域名

目前仅能通过CLI配置自定义子域名。

假设您的Supabase项目当前域名为abcdefghijklmnopqrst.supabase.co，您希望将其配置为my-example-brand.supabase.co。

检查子域名可用性

使用CLI的vanity-subdomains check-availability命令检查目标子域名是否可用：

1
supabase vanity-subdomains --project-ref abcdefghijklmnopqrst check-availability --desired-subdomain my-example-brand --experimental

准备激活子域名

在激活您的自定义子域名前，请为应用程序和集成做好域名变更准备：

• 项目的Supabase域名将保持有效且不会被移除
  • 您无需立即或一次性更改应用程序中的Supabase URL
  • 可以同时使用自定义域名和原域名
• 激活后Supabase Auth将立即使用子域名
  • OAuth流程会将子域名作为回调URL
  • SAML将改用子域名。这意味着您项目的EntityID已变更，可能导致现有身份提供商的SAML停止工作

为避免影响用户使用，请确保完成以下步骤：

1. 检查所有Supabase OAuth提供商：
   • 在提供商的开发者控制台（非Supabase仪表盘）中，找到OAuth应用并额外添加子域名的Supabase Auth回调URL。例如：
     • https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback 和
     • https://my-example-brand.supabase.co/auth/v1/callback
   • Twitter登录使用与项目域名绑定的cookies。这种情况下请确保前端代码使用子域名而非默认项目域名
2. 检查所有SAML身份提供商：
   • 需通过邮件联系所有现有身份提供商，要求他们更新SAML应用（您的项目）的元数据。使用https://example-brand.supabase.co/auth/v1/...替代https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}
   • 完成这些变更后，在域名激活前SAML单点登录可能会暂时失效。请提前做好应对计划

激活子域名

当您选择了一个可用的子域名并完成所有必要准备工作后，可以重新配置您的 Supabase 项目以开始使用它。

使用 vanity-subdomains activate 命令来激活并认领您的子域名：

1
supabase vanity-subdomains --project-ref abcdefghijklmnopqrst activate --desired-subdomain my-example-brand

如果您希望在客户端代码中使用新域名，可以按如下方式设置：

1
2
3
4
import { createClient } from '@supabase/supabase-js'// 使用自定义域名作为 supabase URLconst supabase = createClient('https://my-example-brand.supabase.co', 'public-anon-key')

当使用 Twitter 登录 时，请确保您的前端代码仅使用子域名。

移除自定义子域名

移除子域名可能会在使用 Supabase Auth 与 OAuth 或 SAML 时导致一些问题。您可能需要撤销在_准备激活子域名_步骤中所做的更改。

使用 CLI 的 vanity-subdomains delete 命令从您的项目中移除子域名 my-example-brand.supabase.co。

1
supabase vanity-subdomains delete --project-ref abcdefghijklmnopqrst --experimental

定价

有关费用计算的详细说明，请参阅管理自定义域名使用情况。