自定义域名

自定义域名让你能够向用户展示品牌化的体验。这项功能可以作为付费计划项目的付费附加组件使用。

🌐 Custom domains allow you to present a branded experience to your users. These are available as a paid add-on for projects on a paid plan.

Supabase 支持两种类型的域名：

🌐 There are two types of domains supported by Supabase:

1. 自定义域名，就是你使用像 api.example.com 这样的域名，而不是项目默认的域名。
2. 虚荣子域（实验性功能），你可以为你的项目在 supabase.co 上设置不同的子域。

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

🌐 You can choose either a custom domain or vanity subdomain for each project.

自定义域名 #

🌐 Custom domains

自定义域名会改变你的项目 URL 在用户面前的显示方式。当出现以下情况时，这会很有用：

🌐 Custom domains change the way your project's URLs appear to your users. This is useful when:

• 你正在使用 Supabase Auth 的 OAuth（社交登录），项目的 URL 会显示在 OAuth 授权同意屏幕上。
• 你正在为第三方系统创建 API，例如，通过 Edge Functions 为你的项目实现 webhooks 或外部 API 调用。
• 你正在把网址存储在数据库里或把它们编码成二维码。

自定义域名可以帮助你长期保持 API 的可移植性。通过使用自定义域名，你可以从一个 Supabase 项目迁移到另一个项目，或者在未来更方便地对 API 进行版本管理。

🌐 Custom domains help you keep your APIs portable for the long term. By using a custom domain you can migrate from one Supabase project to another, or make it easier to version APIs in the future.

限制 #

🌐 Limitations

• 自定义域名并不是用来通过 Edge Functions 托管前端应用的。
• 你只能为任何一个 Supabase 项目绑定一个自定义域名。无法将项目的资源拆分到多个自定义域名上。
• 自定义域名只能通过 CNAME 记录来支持。

在 Supabase 仪表板上配置自定义域名 #

🌐 Configure a custom domain using the Supabase dashboard

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

🌐 Follow the Custom Domains steps in the General Settings page in the Dashboard to set up a custom domain for your project.

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

🌐 Configure a custom domain using the Supabase CLI

这个例子假设你的 Supabase 项目是 abcdefghijklmnopqrst，对应的 API URL 是 abcdefghijklmnopqrst.supabase.co，并在 api.example.com 配置了自定义域名。

🌐 This example assumes your Supabase project is abcdefghijklmnopqrst with a corresponding API URL abcdefghijklmnopqrst.supabase.co and configures a custom domain at api.example.com.

开始吧：

🌐 To get started:

1. 安装 最新版本的 Supabase CLI。
2. 登录到你的 Supabase 账户，使用 CLI。
3. 确保你对该项目有拥有者或管理员权限。
4. 从 DNS 提供商获取一个自定义域名。目前只支持子域名。
   • 用 api.example.com 替代 example.com。

添加一个 CNAME 记录 #

🌐 Add a CNAME record

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

🌐 You need to add a CNAME record to your domain's DNS settings to ensure your custom domain points to the Supabase project.

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

🌐 If your project's default domain is abcdefghijklmnopqrst.supabase.co you should:

• 为 api.example.com 创建一个指向 abcdefghijklmnopqrst.supabase.co. 的 CNAME 记录。
• 使用较低的 TTL 值来传播更改，以防你犯错。

验证域名所有权 #

🌐 Verify ownership of the domain

通过 Supabase 注册你的域名来证明你拥有它。你需要下载两个 TXT 记录并将它们添加到你的 DNS 设置中。

🌐 Register your domain with Supabase to prove that you own it. You need to download two TXT records and add them to your DNS settings.

在 CLI 中，运行 domains create 来注册域名和 Supabase，并获取你的验证记录：

🌐 In the CLI, run domains create to register the domain and Supabase and get your verification records:

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

返回单个 TXT 记录。例如：

🌐 A single TXT records is returned. For example:

1
[...]
2
Required outstanding validation records:
3
        _acme-challenge.api.example.com. TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q

把记录添加到你域名的 DNS 设置里。记得去掉前后的空格。用一个低 TTL 值，这样如果出了错可以方便地修改记录。

🌐 Add the record to your domains' DNS settings. Make sure to trim surrounding whitespace. Use a low TTL value so you can change the records if you make a mistake.

一些 DNS 注册商会自动将你的域名添加到正在创建的 DNS 记录中。因此，创建 api.example.com 的 DNS 记录可能会被创建为 api.example.com.example.com 的记录。在这种情况下，从你创建的记录中移除域名；举个例子，你应该创建一个 api 的 TXT 记录，而不是 api.example.com。

🌐 Some DNS registrars automatically append your domain name to the DNS entries being created. As such, creating a DNS record for api.example.com might instead create a record for api.example.com.example.com. In such cases, remove the domain name from the records you're creating; as an example, you would create a TXT record for api, instead of api.example.com.

验证你的域名 #

🌐 Verify your domain

确保你已经配置了所有必需的 DNS 设置：

🌐 Make sure you've configured all required DNS settings:

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

使用 domains reverify 命令开始验证你的域名。你可能需要运行这个命令几次，因为 DNS 记录需要一段时间才能传播。

🌐 Use the domains reverify command to begin the verification process of your domain. You may need to run this command a few times because DNS records take a while to propagate.

1
supabase domains reverify --project-ref abcdefghijklmnopqrst

在后台，Supabase 会检查你的 DNS 记录并颁发 SSL 证书。Supabase 使用多个证书颁发机构（包括 Let's Encrypt、Google Trust Services 和 SSL.com）来确保高可用性。具体的颁发机构会根据可用性来选择，这个过程可能需要最长 30 分钟。

🌐 In the background, Supabase will check your DNS records and issue an SSL certificate. Supabase uses multiple Certificate Authorities (including Let's Encrypt, Google Trust Services and SSL.com) to ensure high availability. The specific issuer is chosen based on availability and this process can take up to 30 minutes.

准备激活你的域名 #

🌐 Prepare to activate your domain

在你激活域名之前，先为域名更改准备好你的应用和集成：

🌐 Before you activate your domain, prepare your applications and integrations for the domain change:

• 这个项目的 Supabase 域名仍然有效。
  • 你不需要马上在你的应用中更改 Supabase 的 URL。
  • 你可以把它和自定义域名互换使用。
• 一旦激活，Supabase Auth 就会立即使用自定义域名。
  • OAuth 流程会把自定义域名作为回调 URL 来展示。
  • SAML 将改用自定义域名。这意味着你项目的 EntityID 已经改变，这可能会导致现有身份提供商的 SAML 停止工作。

为了避免给你的用户带来问题，请按照以下步骤操作：

🌐 To prevent issues for your users, follow these steps:

1. 针对你的每个 Supabase OAuth 提供商：
   • 在提供商的开发者控制台（不是在 Supabase 仪表板）中，找到 OAuth 应用，并添加自定义域 Supabase Auth 回调 URL 以及 Supabase 项目 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 单点登录可能会停止工作，直到域名被激活。提前做好计划吧。

激活你的域名 #

🌐 Activate your domain

一旦你完成了为你的项目激活新域名所需的准备工作，你就可以使用 domains activate CLI 命令来激活它。

🌐 Once you've done the necessary preparations to activate the new domain for your project, you can activate it using the domains activate CLI command.

1
supabase domains activate --project-ref abcdefghijklmnopqrst

当这一步完成后，Supabase 将会从你新的域名处理请求。Supabase 项目的域名 仍然可以使用 并处理请求，所以你不需要急着更改客户端代码中的 URL。

🌐 When this step completes, Supabase will serve the requests from your new domain. The Supabase project domain continues to work and serve requests so you do not need to rush to change client code URLs.

如果你想在客户端代码中使用新的域，请更改你在 Supabase 客户端库中使用的 URL：

🌐 If you wish to use the new domain in client code, change the URL used in your Supabase client libraries:

1
import { createClient } from '@supabase/supabase-js'
2
3
// Use a custom domain as the supabase URL
4
const supabase = createClient('https://api.example.com', 'sb_publishable_...')

同样，你的 Edge Functions 现在可以在 https://api.example.com/functions/v1/your_function_name 访问，你的存储对象在 https://api.example.com/storage/v1/object/public/your_file_path.ext。

🌐 Similarly, your Edge Functions will now be available at https://api.example.com/functions/v1/your_function_name, and your Storage objects at https://api.example.com/storage/v1/object/public/your_file_path.ext.

移除自定义域名 #

🌐 Remove a custom domain

移除自定义域名在使用 Supabase Auth 进行 OAuth 或 SAML 时可能会引发一些问题。你可能需要撤销上面 准备激活你的域名 步骤中所做的更改。

🌐 Removing a custom domain may cause some issues when using Supabase Auth with OAuth or SAML. You may have to reverse the changes made in the Prepare to activate your domain step above.

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

🌐 To remove an activated custom domain you can use the domains delete CLI command.

1
supabase domains delete --project-ref abcdefghijklmnopqrst

虚荣子域 #

🌐 Vanity subdomains

个性化子域名让你可以提供一个基础的品牌体验，相比使用自定义域名。它们允许你在 Supabase 上的自定义子域名（例如 my-example-brand.supabase.co）托管服务，而不是使用默认的随机分配的 abcdefghijklmnopqrst.supabase.co。

🌐 Vanity subdomains allow you to present a basic branded experience, compared to custom domains. They allow you to host your services at a custom subdomain on Supabase (e.g., my-example-brand.supabase.co) instead of the default, randomly assigned abcdefghijklmnopqrst.supabase.co.

开始吧：

🌐 To get started:

1. 安装 最新版本的 Supabase CLI。
2. 登录到你的 Supabase 账户，使用 CLI。
3. 确保你对想要为其设置自定义子域名的项目拥有所有者或管理员权限。
4. 确保你的组织在仪表板的计费页面上使用付费计划（专业版/团队版/企业版）。

配置一个自定义子域名 #

🌐 Configure a vanity subdomain

你只能通过命令行来配置个性化子域名。

🌐 You can configure vanity subdomains via the CLI only.

假设你的 Supabase 项目的域名是 abcdefghijklmnopqrst.supabase.co，并且你想在 my-example-brand.supabase.co 配置一个自定义子域名。

🌐 Assume your Supabase project's domain is abcdefghijklmnopqrst.supabase.co and you wish to configure a vanity subdomain at my-example-brand.supabase.co.

查看子域名是否可用 #

🌐 Check subdomain availability

使用 CLI 的 vanity-subdomains check-availability 命令来检查你想要的子域名是否可以使用：

🌐 Use the vanity-subdomains check-availability command of the CLI to check if your desired subdomain is available for use:

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

准备激活子域 #

🌐 Prepare to activate the subdomain

在你激活自定义子域名之前，先为子域名的更改准备好你的应用和集成：

🌐 Before you activate your vanity subdomain, prepare your applications and integrations for the subdomain change:

• 这个项目的 Supabase 域名仍然有效，不会消失。
  • 你不需要立即或一次性更改你应用中的 Supabase URL。
  • 你可以把它和自定义域名互换使用。
• 一旦激活，Supabase Auth 就会立即使用子域名。
  • OAuth 流程会把子域名当作回调 URL 来使用。
  • SAML 将改用子域名。这意味着你项目的 EntityID 已经改变，这可能导致使用现有身份提供商的 SAML 停止工作。

为了避免给你的用户带来问题，确保你已经完成了以下步骤：

🌐 To prevent issues for your users, make sure you have gone through these steps:

1. 浏览你所有的 Supabase OAuth 提供商：
   • 在提供商的开发者控制台（不是在 Supabase 仪表板里！）中，找到 OAuth 应用，并添加子域名 Supabase Auth 回调 URL 除了 Supabase 项目 URL 之外。 例如：
     • https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback 和
     • https://my-example-brand.supabase.co/auth/v1/callback
   • 使用 Twitter 登录 会使用绑定到项目域的 Cookie。在这种情况下，请确保你的前端代码使用子域而不是默认的项目域。
2. 浏览你所有的 SAML 身份提供者：
   • 你需要通过电子邮件联系所有现有的身份提供商，并要求他们更新 SAML 应用（你的项目）的元数据。用 https://example-brand.supabase.co/auth/v1/... 替换 https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}。
   • 一旦这些更改完成，SAML 单点登录可能会停止工作，直到域名被激活。提前做好计划吧。

激活子域名 #

🌐 Activate a subdomain

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

🌐 Once you've chosen an available subdomain and have done all the necessary preparations for it, you can reconfigure your Supabase project to start using it.

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

🌐 Use the vanity-subdomains activate command to activate and claim your subdomain:

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

如果你想在客户端代码中使用新域名，你可以这样设置：

🌐 If you wish to use the new domain in client code, you can set it up like so:

1
import { createClient } from '@supabase/supabase-js'
2
3
// Use a custom domain as the supabase URL
4
const supabase = createClient('https://my-example-brand.supabase.co', 'sb_publishable_...')

在使用 使用 Twitter 登录 时，确保你的前端代码只使用子域名。

🌐 When using Sign in with Twitter make sure your frontend code is using the subdomain only.

移除自定义子域名 #

🌐 Remove a vanity subdomain

移除子域名在使用 Supabase Auth 进行 OAuth 或 SAML 时可能会引发一些问题。你可能需要撤销上面 准备激活子域名 步骤中所做的更改。

🌐 Removing a subdomain may cause some issues when using Supabase Auth with OAuth or SAML. You may have to reverse the changes made in the Prepare to activate the subdomain step above.

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

🌐 Use the vanity-subdomains delete command of the CLI to remove the subdomain my-example-brand.supabase.co from your project.

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

价格 #

🌐 Pricing

要详细了解费用是如何计算的，请参考 管理自定义域使用情况。

🌐 For a detailed breakdown of how charges are calculated, refer to Manage Custom Domain usage.