Supabase 邮箱注册与邮箱确认链接完整配置指南

# Supabase 邮箱注册与邮箱确认链接完整配置指南

如果你正在用 `Supabase Auth` 做用户系统，并且希望支持：

- 邮箱注册
- 邮箱密码登录
- 注册后发送确认邮件
- 用户点击邮件链接后激活账号

那这篇文章就是一套可以直接落地的配置说明。

---

## 一、你要实现的效果

一个标准的流程通常是：

1. 用户输入邮箱和密码注册
2. Supabase 创建用户
3. Supabase 发送一封确认邮件到用户邮箱
4. 用户点击邮件中的确认链接
5. 用户回到你的网站
6. 账号变成已验证状态
7. 用户之后就可以正常登录

这和“邮箱验证码登录”不是一回事。

这里讲的是：

**邮箱注册 + 邮箱确认链接**

不是：

**输入 6 位邮箱验证码登录**

---

## 二、Supabase 默认支持什么

Supabase Auth 默认就支持：

- `signUp(email, password)`
- `signInWithPassword(email, password)`
- 注册后发送确认邮件
- 邮件确认后激活账号

所以大多数情况下，你不需要自己写邮件发送逻辑。

---

## 三、先在 Supabase 后台确认邮箱功能已开启

进入：

`Authentication -> Providers -> Email`

这里要确认：

- Email provider 已开启
- 支持 `Email + Password`

如果这里关闭了，前端注册一定不会成功。

---

## 四、配置站点地址和回跳地址

进入：

`Authentication -> URL Configuration`

这一步非常重要，因为邮箱确认链接最终需要知道要跳回哪里。

### 1. Site URL

填你的正式站地址，例如：

```txt
https://imvz.com
```

如果当前还没正式绑定域名，也可以先填：

```txt
https://imvz.vercel.app
```

### 2. Redirect URLs

建议至少加入：

```txt
https://imvz.com
https://www.imvz.com
http://localhost:3000
```

如果你本地开发端口不是 `3000`，就替换成你自己的本地端口。

注意：

- 没有配置这些地址时，用户点邮件里的确认链接后可能回不到你的网站
- 线上和本地地址都建议加上

---

## 五、前端注册代码怎么写

最常见的注册方式是：

```ts
const { error } = await supabase.auth.signUp({
  email,
  password
})
```

这段代码执行后，如果邮箱确认已启用，Supabase 会：

- 创建用户
- 发确认邮件

你的前端一般只需要提示用户：

- 注册成功
- 请前往邮箱点击确认链接

例如：

```ts
const { data, error } = await supabase.auth.signUp({
  email,
  password
})

if (error) throw error

console.log('Account created. Check your email for the confirmation link.')
```

---

## 六、如果你想显式指定确认邮件回跳地址

可以在注册时传 `emailRedirectTo`：

```ts
const { error } = await supabase.auth.signUp({
  email,
  password,
  options: {
    emailRedirectTo: 'https://imvz.com'
  }
})
```

这个参数的作用是：

- 用户点击确认邮件后
- Supabase 完成验证
- 再把用户带回这个地址

如果不传，通常会使用你在 `URL Configuration` 里配置的默认站点地址。

建议：

- 正式环境可以显式传正式域名
- 本地测试时可以传 `http://localhost:3000`

---

## 七、登录代码怎么写

邮箱密码登录通常就是：

```ts
const { error } = await supabase.auth.signInWithPassword({
  email,
  password
})
```

如果用户已经完成邮箱确认，这里就能正常登录。

如果还没确认邮箱，是否允许登录，取决于你的 Supabase 配置和当前 Auth 策略。

在产品层面更稳的做法是：

- 登录成功后读取用户资料
- 检查 `email_confirmed_at` 或 `email_verified`
- 未确认时做引导

---

## 八、前端环境变量怎么配

在 Nuxt 项目里，通常需要：

```env
NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx
```

本地 `.env.local` 和线上环境变量都要配。

例如：

### 本地 `.env.local`

```env
NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx
```

### Vercel 环境变量

在 `Project -> Settings -> Environment Variables` 中加入同样的两个值。

---

## 九、如何判断用户邮箱是否已经确认

Supabase 用户对象里通常能拿到邮箱确认相关字段。

常见判断思路：

```ts
const {
  data: { user }
} = await supabase.auth.getUser()

if (user?.email_confirmed_at) {
  console.log('Email confirmed')
}
```

如果你在业务表里也同步用户，可以把这个状态同步写入你自己的 `users` 表，方便后台和权限控制。

---

## 十、常见报错排查

### 1. 注册成功了，但没收到确认邮件

先检查：

- Supabase Email provider 是否开启
- 邮箱是不是进了垃圾箱
- 当前项目邮件发送额度是否正常
- 邮箱地址有没有拼错

如果只是自己测试，也可以先用常见邮箱服务测试，比如 Gmail、Outlook 等。

### 2. 点击确认邮件后跳转错地址

原因通常是：

- `Site URL` 配错了
- `Redirect URLs` 没加当前域名
- `emailRedirectTo` 写错了

解决：

- 回到 `Authentication -> URL Configuration` 检查
- 确认正式域名和 localhost 都已加入

### 3. 注册后页面提示成功，但用户无法登录

常见原因：

- 用户还没点击确认邮件
- 前端没给出“请去邮箱确认”的提示

解决：

- 注册成功后明确提示用户查收邮件
- 登录失败时给出更友好的说明

### 4. 本地可以，线上不行

原因通常是：

- 线上域名没有加入 `Redirect URLs`

### 5. 线上可以，本地不行

原因通常是：

- `http://localhost:3000` 没在允许回跳列表里

---

## 十一、一个更完整的 Nuxt 注册逻辑示例

```ts
const { error } = await supabase.auth.signUp({
  email,
  password,
  options: {
    emailRedirectTo: window.location.origin
  }
})

if (error) {
  throw error
}

message.value = 'Account created. Check your email for the confirmation link.'
```

这套写法比较适合：

- 本地开发
- 正式站
- 预发布环境

因为 `window.location.origin` 会自动跟着当前站点走。

---

## 十二、产品层面的建议

如果你做的是正式的 SaaS 或 AI 应用，建议把这几件事一起做好：

- 注册成功后显示明确提示
- 给一个“重新发送确认邮件”的入口
- 登录成功后同步用户到业务表
- 后台能够看到用户是否已验证邮箱
- 对未验证邮箱用户做适当限制，比如不允许直接消费付费额度

这样后面接：

- 订阅
- 积分
- 用户中心
- 管理后台

都会更顺。

---

## 十三、推荐的最小配置

如果你现在只想先把邮箱注册跑通，最小配置就是：

### Supabase

- 打开 `Authentication -> Providers -> Email`
- 配好 `Authentication -> URL Configuration`

### 前端

- 配好 `NUXT_PUBLIC_SUPABASE_URL`
- 配好 `NUXT_PUBLIC_SUPABASE_ANON_KEY`
- 调 `signUp(email, password)`

### 提示文案

注册成功后提示：

```txt
Account created. Check your email for the confirmation link.
```

---

## 十四、总结

Supabase 做邮箱注册和邮箱确认链接，本身已经非常省事。你真正要注意的点只有几个：

1. Email Provider 要开启
2. Site URL 和 Redirect URLs 要填对
3. 注册成功后要明确提醒用户去邮箱点击确认链接
4. 前端和线上环境变量要配齐

只要这 4 个点没错，邮箱注册这条链路一般都能很顺利跑通。

如果你的站后面还要接：

- Google 登录
- 用户资料同步
- 订阅与积分系统
- 管理员后台

建议都统一围绕 Supabase Auth 来做，这样维护成本最低。