从零到一：Next.js + Supabase 构建全功能认证系统与 Vercel 部署实战

在构建 Prompt Skill Academy 的过程中，我们将一个纯静态或简单的 Web 应用升级为了拥有完整用户系统的生产级产品。以下是本次开发与部署的技术笔记。

1. 技术栈选型

• 前端框架: Next.js 16 (App Router)

• 后端服务: Supabase (Auth + PostgreSQL)

• 部署平台: Vercel

• 包管理器: npm, GitHub CLI (gh)

2. Supabase 认证系统集成

2.1 依赖安装与客户端配置

使用 @supabase/ssr 实现服务端与客户端的无缝衔接。

npm install @supabase/supabase-js @supabase/ssr

配置 src/lib/supabase/ 文件夹下的 client.ts 和 server.ts，确保在不同运行环境下都能获取到正确的 Supabase 实例。

2.2 全局 AuthContext

通过 React Context 封装 AuthContext.tsx，管理全局 user 状态，并导出 signIn, signUp, signOut, resetPassword, signInWithMagicLink 等核心方法。

2.3 交互 UI 实现

• AuthModal: 一个多功能的模态框，支持登录、注册、重置密码申请、魔法链接（Magic Link）四种模式的切换。

• Header 态切换: 登录前显示“登录/注册”按钮，登录后展示用户头像及下拉菜单（含学习进度入口和登出按钮）。

3. 生产环境部署 (Vercel)

3.1 仓库自动化

使用 GitHub CLI 快速创建私有仓库并推送：

gh repo create prompt-skill-academy --private --source=. --remote=origin --push

3.2 域名与重定向

• 在 Vercel 绑定自定义域名 www.getprompt.top。

• 关键配置: 在 Supabase 控制台的 Authentication -> URL Configuration 中，将 Site URL 修改为生产域名，并在 Redirect URLs 中添加 https://www.getprompt.top/**。这解决了验证链接跳转回 localhost:3000 的问题。

4. 邮件模板自定义与避坑指南

4.1 品牌化设计

我们为 Supabase 预设的四种邮件（注册确认、魔法链接、密码重置、邮箱更换）编写了符合项目暗色风格的 HTML 模板，采用紫青渐变按钮设计。

4.2 处理 .top 域名风险

在测试过程中，SpamAssassin 触发了 PDS_OTHER_BAD_TLD 警告。

• 问题: .top 域名因历史原因被部分邮件过滤系统视为高风险。

• 对策: 在邮件模板中移除包含域名链接的页脚，仅保留版权文本。这有效降低了邮件被识别为垃圾邮件的概率。

5. 进阶功能实现

5.1 魔法链接 (Magic Link)

实现无密码登录，通过 supabase.auth.signInWithOtp 向用户发送一个一键登录链接，提升用户体验。

5.2 完整重置密码流

1. 用户在弹窗输入邮箱申请重置。

2. Supabase 发送带有特定 Access Token 的链接。

3. 用户点击链接，自动登录并跳转至 /reset-password 页面。

4. 在该页面通过 supabase.auth.updateUser({ password: new_password }) 完成修改。

6. 总结

通过本次实践，我们建立了完整的用户旅程：

注册 -> 邮件验证 -> 登录 -> 课程学习 -> 进度记录 -> 个人中心。

将认证系统与生产部署结合，标志着项目从“Demo”走向了真正的“产品”。