1. 项目概述一个现代化的全栈健身应用起点最近在做一个健身追踪类的个人项目想找一个既能快速上手又能保证代码质量和开发体验的现代技术栈。我的核心需求很明确需要一个前后端一体、自带用户认证、数据库并且UI组件库足够漂亮和易用的解决方案。在对比了多个方案后我最终锁定了由mccmmj维护的nextjs-workout-app这个 Starter Kit。它本质上是一个基于 Next.js 14 (App Router)、Supabase 和 shadcn/ui 构建的样板项目为开发全栈应用——尤其是像健身应用这类需要用户管理和数据持久化的场景——提供了一个近乎完美的起点。这个 Starter Kit 最吸引我的地方在于它的“完整性”和“现代性”。它不是一个简单的“Hello World”示例而是一个已经配置好了身份验证包括基于 Cookie 的会话管理、数据库连接、现代化的 UI 组件库以及项目结构的最佳实践。这意味着我不用再花几天时间去手动集成 Auth、配置环境变量或者纠结于如何优雅地组织服务层代码。我可以直接克隆项目填上自己的 Supabase 密钥然后立刻开始编写业务逻辑——比如创建“训练计划”、“记录训练组数”这些功能。对于独立开发者或小团队来说这种效率提升是巨大的。接下来我会详细拆解这个项目的设计思路、核心配置并分享在基于它进行二次开发过程中的实操要点和避坑经验。2. 技术栈选型与架构设计解析2.1 为什么是 Next.js Supabase shadcn/ui选择这个技术栈组合并非偶然而是经过深思熟虑的尤其适合需要快速迭代验证想法MVP的全栈应用。Next.js 14 (App Router) 作为 React 的元框架它提供了开箱即用的解决方案。App Router 引入了基于文件系统的路由、服务端组件RSC、流式渲染等特性。对于健身应用来说训练计划列表、个人资料页这些对 SEO 和初始加载速度有要求的页面可以轻松地使用服务端组件来渲染直接从数据库获取数据无需客户端 JavaScript 介入首屏体验极佳。而像实时记录训练重量、组数这种交互性强的功能则可以使用客户端组件或 Server Actions 来处理。Next.js 的中间件Middleware功能也被这个 Starter Kit 用来进行路由保护确保未登录用户无法访问/dashboard等私有页面。Supabase 这是项目的“后端即服务”BaaS核心。它集成了 PostgreSQL 数据库、实时订阅、身份认证、存储和边缘函数。对于个人项目或初创公司自建和维护一套用户系统、数据库备份和 API 服务器是沉重的负担。Supabase 完美解决了这个问题。它的认证系统直接与 Next.js 集成通过supabase/ssr包实现了安全的、基于 Cookie 的会话管理使得用户状态在服务端和客户端都能安全访问。数据库方面我可以用熟悉的 SQL 或者其图形化界面来设计我的workouts、exercises、profiles表并通过自动生成的 TypeScript 类型保证前后端类型安全。shadcn/ui 这是一个构建在 Radix UI 之上的组件库其理念是“将组件复制到你的项目中”。这与直接安装一个 npm 包如 MUI不同。你可以通过命令行工具将需要的组件如按钮、表单、对话框直接复制到项目的/components/ui目录下。这样做的好处是你拥有组件的全部源代码可以对其进行任何程度的定制而不会被封装好的库所限制。对于健身应用我可以轻松定制一个显示心率区间的进度条或者一个记录组数的数字输入框样式完全符合设计需求且没有额外的运行时开销。注意这个技术栈的版本迭代很快。在开始前务必确认你使用的 Next.js、Supabase 客户端库和 shadcn/ui 的版本是相互兼容的。项目 README 或package.json中的版本通常是经过验证的稳定组合。2.2 项目核心架构设计这个 Starter Kit 的目录结构清晰地体现了现代 Next.js 应用的最佳实践。理解这个结构是进行高效二次开发的基础。with-supabase-app/ ├── app/ # Next.js 14 App Router 核心目录 │ ├── (auth)/ # 路由组包含登录、注册等认证相关页面 │ │ ├── login/ │ │ ├── signup/ │ │ └── layout.tsx │ ├── (dashboard)/ # 路由组需要认证的仪表板页面 │ │ ├── page.tsx │ │ └── layout.tsx │ ├── layout.tsx # 根布局包含全局的 Supabase 提供者 │ └── page.tsx # 首页可能公开访问 ├── components/ # 可复用组件 │ ├── ui/ # shadcn/ui 组件如 Button, Card 等 │ ├── auth/ # 认证相关组件如登录表单 │ └── theme-provider.tsx # 主题切换提供者如支持暗黑模式 ├── lib/ # 工具函数和配置 │ ├── supabase/ # Supabase 客户端配置 │ │ ├── client.ts # 用于客户端组件的 Supabase 客户端 │ │ ├── server.ts # 用于服务端组件、Server Actions 的客户端 │ │ └── middleware.ts # 用于中间件的客户端 │ └── utils.ts # 其他工具函数 ├── middleware.ts # Next.js 中间件用于路由保护 └── .env.local.example # 环境变量示例文件关键设计解读路由组(auth)和(dashboard)使用括号包裹的文件夹是 Next.js 的路由组它们不会影响 URL 路径但用于逻辑分组。这让我可以将所有认证页面组织在一起并为其设置一个不包含导航栏的独立布局layout.tsx同样为所有需要登录后才能访问的页面设置一个共同的仪表板布局。分离的 Supabase 客户端lib/supabase/下的三个客户端文件是精髓。client.ts用于在浏览器中运行的组件server.ts用于在服务器端运行的组件或 Server Actionsmiddleware.ts则专门用于中间件环境。这种分离确保了在不同运行时环境下都能使用正确和安全的方式与 Supabase 交互。中间件保护middleware.ts文件会检查用户访问的路径。如果用户尝试访问/dashboard下的任何页面而未登录中间件会将其重定向到/login页面。这是实现页面级权限控制最有效和高效的方式。3. 从零开始环境搭建与项目初始化实操3.1 创建 Supabase 项目与获取密钥在写一行代码之前我们需要先准备好后端的“大脑”——Supabase 项目。访问 Supabase 官网并登录/注册。在控制台点击 “New project”。填写项目信息给你的项目起个名字例如my-workout-app。设置数据库密码务必保存好并选择离你的目标用户最近的地理区域以减少延迟。等待项目初始化。大约需要1-2分钟。初始化完成后你会进入项目仪表板。获取 API 密钥在左侧菜单进入Settings API。这里你会看到两个关键信息Project URL形如https://xxxxxxxxxxxxxx.supabase.coanonpublic key一串很长的字符串。 这两个值就是前端应用连接 Supabase 的“地址”和“门票”。anonkey 是公开的用于在前端进行非敏感操作如登录、注册、查询公开数据。Supabase 的行级安全策略RLS会确保即使密钥公开用户也只能访问自己被授权的数据。实操心得我建议在 Supabase 后台的SQL Editor中运行一个简单的建表语句提前为健身应用创建一张测试表。例如CREATE TABLE public.workouts ( id UUID DEFAULT gen_random_uuid() PRIMARY KEY, user_id UUID REFERENCES auth.users(id) NOT NULL, name TEXT NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE(utc::text, NOW()) NOT NULL );这不仅能验证数据库连接还能让你立刻理解后续的数据操作流程。别忘了为这张表启用 RLS 并添加策略例如CREATE POLICY Users can manage their own workouts ON workouts FOR ALL USING (auth.uid() user_id);。3.2 本地克隆与配置项目官方提供了两种方式我强烈推荐使用 Vercel 的一键部署因为它能自动完成大部分配置。但为了彻底理解过程我们先走一遍本地克隆的流程。方法一使用create-next-app模板推荐打开你的终端执行以下命令。这里以pnpm为例它速度更快磁盘空间利用更高效pnpm create next-app my-workout-app --example with-supabase这个命令会从 Next.js 官方仓库拉取with-supabase模板并创建一个名为my-workout-app的文件夹。完成后进入项目目录cd my-workout-app方法二直接克隆仓库如果你想基于特定分支或 Fork你也可以直接克隆mccmmj/nextjs-workout-app或原始的vercel/next.js示例仓库。git clone https://github.com/mccmmj/nextjs-workout-app.git cd nextjs-workout-app pnpm install # 或 npm install / yarn install配置环境变量在项目根目录你会找到一个.env.local.example文件。复制它并重命名为.env.local。cp .env.local.example .env.local打开.env.local文件将你在 Supabase 控制台获取的Project URL和anon public key分别填入对应的变量中。NEXT_PUBLIC_SUPABASE_URLhttps://xxxxxxxxxxxxxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEYeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...注意变量名必须以NEXT_PUBLIC_开头这样 Next.js 才会将其暴露给浏览器端。切勿在此文件中存放服务器端密钥如SUPABASE_SERVICE_ROLE_KEY。启动开发服务器pnpm dev如果一切顺利终端会显示Ready on http://localhost:3000。打开浏览器访问该地址你应该能看到一个带有登录/注册按钮的启动页面。3.3 核心依赖包解析项目初始化后查看package.json可以让我们理解其能力边界。几个核心依赖如下表所示依赖包版本 (示例)核心作用next^14.0.0React 全栈框架提供路由、渲染、构建等核心能力。supabase/ssr^0.4.0关键包。提供与 Next.js App Router 深度集成的 Supabase 客户端支持 Cookie 管理实现服务端/客户端无缝认证。supabase/supabase-js^2.39.0Supabase 的 JavaScript/TypeScript 客户端库。tailwindcss^3.3.0实用优先的 CSS 框架用于快速构建自定义 UI。shadcn-uilatest实际上是通过shadcnCLI 工具添加组件并非直接 npm 安装。lucide-react^0.309.0一套精美的图标库shadcn/ui 组件经常使用它。next-themes^0.2.1用于为应用提供暗黑/明亮主题切换的支持。关于 shadcn/ui 的初始化项目模板已经预装了一些基础组件如 Button。如果你想添加更多组件例如一个用于显示训练详情的Card可以运行npx shadcn-uilatest add card这个命令会从上游下载Card组件的源代码并安装其依赖如radix-ui/react-card将其添加到你的/components/ui目录下。这种“拥有源代码”的方式给了你极大的定制自由。4. 核心功能模块实现与代码详解4.1 用户认证流程深度剖析这个 Starter Kit 的认证系统是其最大亮点之一。它利用supabase/ssr包实现了基于 HTTP-only Cookie 的会话管理彻底解决了传统 JWT 存储在localStorage中的安全风险易受 XSS 攻击。工作流程如下登录/注册用户在/login或/signup页面提交表单。Server Action 处理表单提交触发一个 Next.jsServer Action在app/(auth)/actions.ts中定义。这个 Action 在服务器端运行调用supabase.auth.signInWithPassword或supabase.auth.signUp。Cookie 设置supabase/ssr的createServerClient方法在认证成功后会自动将刷新令牌Refresh Token和安全地设置到用户的 HTTP-only Cookie 中。这个 Cookie 对前端 JavaScript 不可见因此无法被恶意脚本窃取。会话读取在任何需要用户信息的地方如服务端组件、中间件、Server Action都可以通过createServerClient读取这个 Cookie并调用supabase.auth.getUser()来获取当前用户对象。客户端同步通过一个特殊的SupabaseListener组件通常放在根布局里客户端可以订阅认证状态的变化通过supabase.auth.onAuthStateChange并更新 React 上下文Context中的用户状态从而驱动 UI 更新如显示用户名。关键代码片段解析在lib/supabase/server.ts中createServerClient的配置是关键import { createServerClient } from supabase/ssr import { cookies } from next/headers export function createClient() { const cookieStore cookies() return createServerClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { cookies: { getAll() { return cookieStore.getAll() }, setAll(cookiesToSet) { try { cookiesToSet.forEach(({ name, value, options }) cookieStore.set(name, value, options) ) } catch (error) { // 处理错误例如在中间件中调用时 } }, }, } ) }这个函数在每个请求的上下文中创建一个新的 Supabase 客户端实例并传入一个 Cookie 适配器使其能够读写 Next.js 的cookies()API。4.2 数据库操作与类型安全实践Supabase 提供了自动生成的 TypeScript 类型定义这能极大提升开发体验和代码安全性。生成类型首先在项目根目录运行 Supabase CLI 命令来拉取你数据库的结构并生成类型文件。npx supabase gen types typescript --project-id your-project-ref --schema public lib/database.types.ts将your-project-ref替换为你的 Supabase 项目 ID在项目设置里找到。这条命令会生成一个包含所有表、视图、函数类型的database.types.ts文件。进行类型安全的查询现在你在进行数据库操作时就能获得完整的类型提示和校验。// app/(dashboard)/workouts/page.tsx import { createClient } from /lib/supabase/server import type { Database } from /lib/database.types export default async function WorkoutsPage() { const supabase createClient() // 从会话中获取用户 const { data: { user } } await supabase.auth.getUser() // 类型安全的查询workouts 表和返回的 data 都有完整类型。 const { data: workouts, error } await supabase .from(workouts) .select(*) .eq(user_id, user?.id) // 只查询当前用户的训练 .order(created_at, { ascending: false }) if (error) { // 处理错误 } // 渲染 workouts 数据... }这样如果你拼错了字段名如user_id写成user_IdTypeScript 编译器会在开发阶段就报错而不是等到运行时才发现问题。4.3 构建健身应用核心页面基于这个 Starter Kit我们可以快速搭建出健身应用的核心界面。这里以创建训练记录页面为例。步骤 1创建受保护的路由和页面由于/workouts页面应该只对登录用户开放我们在app/目录下创建一个新的路由组(protected)并在其中创建页面。app/ ├── (protected)/ │ ├── workouts/ │ │ ├── page.tsx # 训练列表页 │ │ └── new/ │ │ └── page.tsx # 创建新训练页 │ └── layout.tsx # 继承自根布局可添加额外的保护或样式(protected)/layout.tsx可以利用中间件进行保护但更常见的做法是在page.tsx或layout.tsx的服务端组件中检查用户会话如果未登录则重定向。步骤 2实现训练列表页在app/(protected)/workouts/page.tsx中我们使用服务端组件来获取数据。import { createClient } from /lib/supabase/server import { redirect } from next/navigation import WorkoutCard from /components/workout-card // 一个自定义的展示组件 import { Button } from /components/ui/button import Link from next/link export default async function WorkoutsPage() { const supabase createClient() const { data: { user } } await supabase.auth.getUser() if (!user) { redirect(/login) // 未登录则跳转到登录页 } const { data: workouts } await supabase .from(workouts) .select(id, name, created_at, exercises ( name, sets, reps )) // 关联查询训练动作 .eq(user_id, user.id) .order(created_at, { ascending: false }) return ( div classNamecontainer mx-auto p-6 div classNameflex justify-between items-center mb-6 h1 classNametext-3xl font-bold我的训练记录/h1 Button asChild Link href/workouts/new 新建训练/Link /Button /div div classNamegrid gap-4 {workouts?.map((workout) ( WorkoutCard key{workout.id} workout{workout} / ))} {workouts?.length 0 ( p classNametext-center text-gray-500还没有训练记录开始你的第一次训练吧/p )} /div /div ) }步骤 3使用 Server Action 创建新训练在app/(protected)/workouts/new/page.tsx中我们创建一个表单并使用 Server Action 来处理提交避免创建额外的 API 路由。 首先在app/(protected)/workouts/actions.ts中定义 Actionuse server import { createClient } from /lib/supabase/server import { revalidatePath } from next/cache import { redirect } from next/navigation export async function createWorkout(formData: FormData) { const supabase createClient() const { data: { user } } await supabase.auth.getUser() if (!user) { throw new Error(未授权) } const name formData.get(name) as string // 这里可以获取更多表单字段如 exercises const { error } await supabase .from(workouts) .insert([{ name, user_id: user.id }]) if (error) { console.error(创建训练失败:, error) // 可以返回错误信息给前端展示 return { success: false, message: error.message } } // 成功创建后使训练列表页的缓存失效并重定向 revalidatePath(/workouts) redirect(/workouts) }然后在页面组件中使用这个 Action// app/(protected)/workouts/new/page.tsx import { createWorkout } from ../actions import { Input } from /components/ui/input import { Button } from /components/ui/button export default function NewWorkoutPage() { return ( form action{createWorkout} classNamespace-y-4 max-w-md mx-auto mt-10 div label htmlForname classNameblock text-sm font-medium训练名称/label Input idname namename required placeholder例如胸肌训练日 / /div {/* 可以添加更多输入字段用于记录动作、组数、重量等 */} Button typesubmit创建训练/Button /form ) }5. 深度定制、部署与常见问题排查5.1 样式与主题深度定制项目默认使用 Tailwind CSS 和 shadcn/ui。定制化主要从两个层面入手1. 定制 Tailwind修改tailwind.config.ts文件。例如为健身应用定义一套充满力量感的主题色。// tailwind.config.ts import type { Config } from tailwindcss const config: Config { theme: { extend: { colors: { primary: { DEFAULT: #3b82f6, // 蓝色 foreground: white, }, // 添加健身相关的语义化颜色 strength: #ef4444, // 红色用于最大重量 endurance: #10b981, // 绿色用于有氧 }, fontFamily: { sans: [Inter var, ...defaultTheme.fontFamily.sans], // 使用更现代的字体 }, }, }, }2. 定制 shadcn/ui 组件由于组件源代码就在你的/components/ui目录下你可以直接修改它们。例如修改button.tsx来改变所有按钮的圆角大小或阴影。// components/ui/button.tsx // ... 在 className 中添加或修改样式 const Button React.forwardRefHTMLButtonElement, ButtonProps( ({ className, variant default, size default, ...props }, ref) { return ( button className{cn( // 修改这里例如增加圆角 rounded-lg px-4 py-2 text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50, // ... 其他 variant 样式 )} ref{ref} {...props} / ) } )5.2 部署到 Vercel这是最简单的一步也是这个 Starter Kit 设计时优先考虑的部署方式。将你的代码推送到 GitHub、GitLab 或 Bitbucket 仓库。登录 Vercel 点击 “Add New...” - “Project”。导入你的 Git 仓库。在配置页面Vercel 会自动检测到这是一个 Next.js 项目。最关键的一步是配置环境变量。你需要手动添加或如果使用了 Supabase Vercel 集成可能会自动添加NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEY点击 “Deploy”。几分钟后你的健身应用就上线了。使用 Supabase Vercel 集成更推荐在 Vercel 的项目设置中找到 “Integrations” 市场搜索并添加 “Supabase Integration”。按照指引授权并关联你的 Supabase 项目。完成后环境变量会自动同步到 Vercel无需手动填写且后续数据库连接字符串如有变更也会自动更新。5.3 常见问题与排查技巧实录在实际开发中你几乎一定会遇到下面这些问题。这里是我的踩坑记录和解决方案。问题现象可能原因解决方案登录后页面刷新用户状态丢失1. 中间件或服务端组件中使用的createClient方法不正确。2. Cookie 域名/路径设置问题。1. 确保在服务端server.ts和中间件middleware.ts中使用正确的createServerClient方法并传入cookies()。2. 检查lib/supabase/server.ts中createServerClient的cookies.setAll逻辑确保在中间件环境下错误被妥善处理try-catch。在服务端组件中调用supabase.from().select()返回空数组但数据存在未正确传递用户认证上下文。服务端客户端默认使用服务端密钥如果配置了或匿名密钥可能绕过 RLS。在查询前必须先获取当前请求的用户const { data: { user } } await supabase.auth.getUser();。然后在查询中使用.eq(user_id, user.id)或确保你的 RLS 策略能基于auth.uid()正确工作。pnpm dev运行时出现 “Invalidcookies()call” 错误Next.js 15 在某些情况下对cookies()的调用有更严格的限制。确保cookies()只在 Server Component、Server Action 或 Route Handler 中调用。如果在普通工具函数中调用需要将cookies作为参数传入。检查lib/supabase/server.ts确保其只在服务端上下文中被导入和使用。shadcn/ui 组件样式不生效或报错1.tailwind.config.ts中content路径未包含组件。2. 组件依赖的 CSS 变量未定义。1. 检查tailwind.config.ts的content数组确保包含了./components/**/*.{ts,tsx}。2. 确保app/globals.css中引入了tailwind base; tailwind components; tailwind utilities;以及 shadcn/ui 的主题 CSS 文件通常通过import引入。部署到 Vercel 后认证功能在生产环境失效生产环境的环境变量未正确设置或 Supabase 项目配置的“重定向 URL”不包含生产域名。1. 在 Vercel 项目设置中核对NEXT_PUBLIC_SUPABASE_URL和NEXT_PUBLIC_SUPABASE_ANON_KEY的值。2. 登录 Supabase 控制台进入Authentication URL Configuration将你的 Vercel 生产域名如https://yourapp.vercel.app添加到Site URL和Redirect URLs中。TypeScript 报错找不到模块/lib/...或/components/...tsconfig.json中的baseUrl或paths配置不正确。检查项目根目录的tsconfig.json文件确保包含类似配置baseUrl: ., paths: { /*: [./*] }。这是模板自带的如果丢失需手动添加。一个高级技巧优化数据库查询当你的训练记录越来越多关联查询exercises时可能会影响性能。考虑在数据库中对workouts.user_id和created_at字段创建索引并避免在列表页进行过于复杂的关联查询。对于分页可以使用 Supabase 的range()方法。const page 1 const pageSize 10 const { data, error, count } await supabase .from(workouts) .select(*, { count: exact }) // 获取总数 .eq(user_id, user.id) .order(created_at, { ascending: false }) .range((page - 1) * pageSize, page * pageSize - 1)这个 Starter Kit 提供了一个极其坚固和现代的全栈开发地基。从我个人的使用体验来看它最大的价值在于将那些繁琐、易错的基础设施配置认证、数据库连接、类型安全、部署标准化了让开发者能百分百专注于业务逻辑的创新——也就是去思考如何设计更好的训练动作库、如何可视化用户的进步曲线。如果你正打算用 Next.js 做一个需要用户系统的应用直接从这个模板开始至少能为你节省一周的摸索时间。剩下的就是尽情发挥你的创意去构建那个独一无二的应用了。
基于Next.js与Supabase的全栈健身应用开发实战指南
1. 项目概述一个现代化的全栈健身应用起点最近在做一个健身追踪类的个人项目想找一个既能快速上手又能保证代码质量和开发体验的现代技术栈。我的核心需求很明确需要一个前后端一体、自带用户认证、数据库并且UI组件库足够漂亮和易用的解决方案。在对比了多个方案后我最终锁定了由mccmmj维护的nextjs-workout-app这个 Starter Kit。它本质上是一个基于 Next.js 14 (App Router)、Supabase 和 shadcn/ui 构建的样板项目为开发全栈应用——尤其是像健身应用这类需要用户管理和数据持久化的场景——提供了一个近乎完美的起点。这个 Starter Kit 最吸引我的地方在于它的“完整性”和“现代性”。它不是一个简单的“Hello World”示例而是一个已经配置好了身份验证包括基于 Cookie 的会话管理、数据库连接、现代化的 UI 组件库以及项目结构的最佳实践。这意味着我不用再花几天时间去手动集成 Auth、配置环境变量或者纠结于如何优雅地组织服务层代码。我可以直接克隆项目填上自己的 Supabase 密钥然后立刻开始编写业务逻辑——比如创建“训练计划”、“记录训练组数”这些功能。对于独立开发者或小团队来说这种效率提升是巨大的。接下来我会详细拆解这个项目的设计思路、核心配置并分享在基于它进行二次开发过程中的实操要点和避坑经验。2. 技术栈选型与架构设计解析2.1 为什么是 Next.js Supabase shadcn/ui选择这个技术栈组合并非偶然而是经过深思熟虑的尤其适合需要快速迭代验证想法MVP的全栈应用。Next.js 14 (App Router) 作为 React 的元框架它提供了开箱即用的解决方案。App Router 引入了基于文件系统的路由、服务端组件RSC、流式渲染等特性。对于健身应用来说训练计划列表、个人资料页这些对 SEO 和初始加载速度有要求的页面可以轻松地使用服务端组件来渲染直接从数据库获取数据无需客户端 JavaScript 介入首屏体验极佳。而像实时记录训练重量、组数这种交互性强的功能则可以使用客户端组件或 Server Actions 来处理。Next.js 的中间件Middleware功能也被这个 Starter Kit 用来进行路由保护确保未登录用户无法访问/dashboard等私有页面。Supabase 这是项目的“后端即服务”BaaS核心。它集成了 PostgreSQL 数据库、实时订阅、身份认证、存储和边缘函数。对于个人项目或初创公司自建和维护一套用户系统、数据库备份和 API 服务器是沉重的负担。Supabase 完美解决了这个问题。它的认证系统直接与 Next.js 集成通过supabase/ssr包实现了安全的、基于 Cookie 的会话管理使得用户状态在服务端和客户端都能安全访问。数据库方面我可以用熟悉的 SQL 或者其图形化界面来设计我的workouts、exercises、profiles表并通过自动生成的 TypeScript 类型保证前后端类型安全。shadcn/ui 这是一个构建在 Radix UI 之上的组件库其理念是“将组件复制到你的项目中”。这与直接安装一个 npm 包如 MUI不同。你可以通过命令行工具将需要的组件如按钮、表单、对话框直接复制到项目的/components/ui目录下。这样做的好处是你拥有组件的全部源代码可以对其进行任何程度的定制而不会被封装好的库所限制。对于健身应用我可以轻松定制一个显示心率区间的进度条或者一个记录组数的数字输入框样式完全符合设计需求且没有额外的运行时开销。注意这个技术栈的版本迭代很快。在开始前务必确认你使用的 Next.js、Supabase 客户端库和 shadcn/ui 的版本是相互兼容的。项目 README 或package.json中的版本通常是经过验证的稳定组合。2.2 项目核心架构设计这个 Starter Kit 的目录结构清晰地体现了现代 Next.js 应用的最佳实践。理解这个结构是进行高效二次开发的基础。with-supabase-app/ ├── app/ # Next.js 14 App Router 核心目录 │ ├── (auth)/ # 路由组包含登录、注册等认证相关页面 │ │ ├── login/ │ │ ├── signup/ │ │ └── layout.tsx │ ├── (dashboard)/ # 路由组需要认证的仪表板页面 │ │ ├── page.tsx │ │ └── layout.tsx │ ├── layout.tsx # 根布局包含全局的 Supabase 提供者 │ └── page.tsx # 首页可能公开访问 ├── components/ # 可复用组件 │ ├── ui/ # shadcn/ui 组件如 Button, Card 等 │ ├── auth/ # 认证相关组件如登录表单 │ └── theme-provider.tsx # 主题切换提供者如支持暗黑模式 ├── lib/ # 工具函数和配置 │ ├── supabase/ # Supabase 客户端配置 │ │ ├── client.ts # 用于客户端组件的 Supabase 客户端 │ │ ├── server.ts # 用于服务端组件、Server Actions 的客户端 │ │ └── middleware.ts # 用于中间件的客户端 │ └── utils.ts # 其他工具函数 ├── middleware.ts # Next.js 中间件用于路由保护 └── .env.local.example # 环境变量示例文件关键设计解读路由组(auth)和(dashboard)使用括号包裹的文件夹是 Next.js 的路由组它们不会影响 URL 路径但用于逻辑分组。这让我可以将所有认证页面组织在一起并为其设置一个不包含导航栏的独立布局layout.tsx同样为所有需要登录后才能访问的页面设置一个共同的仪表板布局。分离的 Supabase 客户端lib/supabase/下的三个客户端文件是精髓。client.ts用于在浏览器中运行的组件server.ts用于在服务器端运行的组件或 Server Actionsmiddleware.ts则专门用于中间件环境。这种分离确保了在不同运行时环境下都能使用正确和安全的方式与 Supabase 交互。中间件保护middleware.ts文件会检查用户访问的路径。如果用户尝试访问/dashboard下的任何页面而未登录中间件会将其重定向到/login页面。这是实现页面级权限控制最有效和高效的方式。3. 从零开始环境搭建与项目初始化实操3.1 创建 Supabase 项目与获取密钥在写一行代码之前我们需要先准备好后端的“大脑”——Supabase 项目。访问 Supabase 官网并登录/注册。在控制台点击 “New project”。填写项目信息给你的项目起个名字例如my-workout-app。设置数据库密码务必保存好并选择离你的目标用户最近的地理区域以减少延迟。等待项目初始化。大约需要1-2分钟。初始化完成后你会进入项目仪表板。获取 API 密钥在左侧菜单进入Settings API。这里你会看到两个关键信息Project URL形如https://xxxxxxxxxxxxxx.supabase.coanonpublic key一串很长的字符串。 这两个值就是前端应用连接 Supabase 的“地址”和“门票”。anonkey 是公开的用于在前端进行非敏感操作如登录、注册、查询公开数据。Supabase 的行级安全策略RLS会确保即使密钥公开用户也只能访问自己被授权的数据。实操心得我建议在 Supabase 后台的SQL Editor中运行一个简单的建表语句提前为健身应用创建一张测试表。例如CREATE TABLE public.workouts ( id UUID DEFAULT gen_random_uuid() PRIMARY KEY, user_id UUID REFERENCES auth.users(id) NOT NULL, name TEXT NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE(utc::text, NOW()) NOT NULL );这不仅能验证数据库连接还能让你立刻理解后续的数据操作流程。别忘了为这张表启用 RLS 并添加策略例如CREATE POLICY Users can manage their own workouts ON workouts FOR ALL USING (auth.uid() user_id);。3.2 本地克隆与配置项目官方提供了两种方式我强烈推荐使用 Vercel 的一键部署因为它能自动完成大部分配置。但为了彻底理解过程我们先走一遍本地克隆的流程。方法一使用create-next-app模板推荐打开你的终端执行以下命令。这里以pnpm为例它速度更快磁盘空间利用更高效pnpm create next-app my-workout-app --example with-supabase这个命令会从 Next.js 官方仓库拉取with-supabase模板并创建一个名为my-workout-app的文件夹。完成后进入项目目录cd my-workout-app方法二直接克隆仓库如果你想基于特定分支或 Fork你也可以直接克隆mccmmj/nextjs-workout-app或原始的vercel/next.js示例仓库。git clone https://github.com/mccmmj/nextjs-workout-app.git cd nextjs-workout-app pnpm install # 或 npm install / yarn install配置环境变量在项目根目录你会找到一个.env.local.example文件。复制它并重命名为.env.local。cp .env.local.example .env.local打开.env.local文件将你在 Supabase 控制台获取的Project URL和anon public key分别填入对应的变量中。NEXT_PUBLIC_SUPABASE_URLhttps://xxxxxxxxxxxxxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEYeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...注意变量名必须以NEXT_PUBLIC_开头这样 Next.js 才会将其暴露给浏览器端。切勿在此文件中存放服务器端密钥如SUPABASE_SERVICE_ROLE_KEY。启动开发服务器pnpm dev如果一切顺利终端会显示Ready on http://localhost:3000。打开浏览器访问该地址你应该能看到一个带有登录/注册按钮的启动页面。3.3 核心依赖包解析项目初始化后查看package.json可以让我们理解其能力边界。几个核心依赖如下表所示依赖包版本 (示例)核心作用next^14.0.0React 全栈框架提供路由、渲染、构建等核心能力。supabase/ssr^0.4.0关键包。提供与 Next.js App Router 深度集成的 Supabase 客户端支持 Cookie 管理实现服务端/客户端无缝认证。supabase/supabase-js^2.39.0Supabase 的 JavaScript/TypeScript 客户端库。tailwindcss^3.3.0实用优先的 CSS 框架用于快速构建自定义 UI。shadcn-uilatest实际上是通过shadcnCLI 工具添加组件并非直接 npm 安装。lucide-react^0.309.0一套精美的图标库shadcn/ui 组件经常使用它。next-themes^0.2.1用于为应用提供暗黑/明亮主题切换的支持。关于 shadcn/ui 的初始化项目模板已经预装了一些基础组件如 Button。如果你想添加更多组件例如一个用于显示训练详情的Card可以运行npx shadcn-uilatest add card这个命令会从上游下载Card组件的源代码并安装其依赖如radix-ui/react-card将其添加到你的/components/ui目录下。这种“拥有源代码”的方式给了你极大的定制自由。4. 核心功能模块实现与代码详解4.1 用户认证流程深度剖析这个 Starter Kit 的认证系统是其最大亮点之一。它利用supabase/ssr包实现了基于 HTTP-only Cookie 的会话管理彻底解决了传统 JWT 存储在localStorage中的安全风险易受 XSS 攻击。工作流程如下登录/注册用户在/login或/signup页面提交表单。Server Action 处理表单提交触发一个 Next.jsServer Action在app/(auth)/actions.ts中定义。这个 Action 在服务器端运行调用supabase.auth.signInWithPassword或supabase.auth.signUp。Cookie 设置supabase/ssr的createServerClient方法在认证成功后会自动将刷新令牌Refresh Token和安全地设置到用户的 HTTP-only Cookie 中。这个 Cookie 对前端 JavaScript 不可见因此无法被恶意脚本窃取。会话读取在任何需要用户信息的地方如服务端组件、中间件、Server Action都可以通过createServerClient读取这个 Cookie并调用supabase.auth.getUser()来获取当前用户对象。客户端同步通过一个特殊的SupabaseListener组件通常放在根布局里客户端可以订阅认证状态的变化通过supabase.auth.onAuthStateChange并更新 React 上下文Context中的用户状态从而驱动 UI 更新如显示用户名。关键代码片段解析在lib/supabase/server.ts中createServerClient的配置是关键import { createServerClient } from supabase/ssr import { cookies } from next/headers export function createClient() { const cookieStore cookies() return createServerClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, { cookies: { getAll() { return cookieStore.getAll() }, setAll(cookiesToSet) { try { cookiesToSet.forEach(({ name, value, options }) cookieStore.set(name, value, options) ) } catch (error) { // 处理错误例如在中间件中调用时 } }, }, } ) }这个函数在每个请求的上下文中创建一个新的 Supabase 客户端实例并传入一个 Cookie 适配器使其能够读写 Next.js 的cookies()API。4.2 数据库操作与类型安全实践Supabase 提供了自动生成的 TypeScript 类型定义这能极大提升开发体验和代码安全性。生成类型首先在项目根目录运行 Supabase CLI 命令来拉取你数据库的结构并生成类型文件。npx supabase gen types typescript --project-id your-project-ref --schema public lib/database.types.ts将your-project-ref替换为你的 Supabase 项目 ID在项目设置里找到。这条命令会生成一个包含所有表、视图、函数类型的database.types.ts文件。进行类型安全的查询现在你在进行数据库操作时就能获得完整的类型提示和校验。// app/(dashboard)/workouts/page.tsx import { createClient } from /lib/supabase/server import type { Database } from /lib/database.types export default async function WorkoutsPage() { const supabase createClient() // 从会话中获取用户 const { data: { user } } await supabase.auth.getUser() // 类型安全的查询workouts 表和返回的 data 都有完整类型。 const { data: workouts, error } await supabase .from(workouts) .select(*) .eq(user_id, user?.id) // 只查询当前用户的训练 .order(created_at, { ascending: false }) if (error) { // 处理错误 } // 渲染 workouts 数据... }这样如果你拼错了字段名如user_id写成user_IdTypeScript 编译器会在开发阶段就报错而不是等到运行时才发现问题。4.3 构建健身应用核心页面基于这个 Starter Kit我们可以快速搭建出健身应用的核心界面。这里以创建训练记录页面为例。步骤 1创建受保护的路由和页面由于/workouts页面应该只对登录用户开放我们在app/目录下创建一个新的路由组(protected)并在其中创建页面。app/ ├── (protected)/ │ ├── workouts/ │ │ ├── page.tsx # 训练列表页 │ │ └── new/ │ │ └── page.tsx # 创建新训练页 │ └── layout.tsx # 继承自根布局可添加额外的保护或样式(protected)/layout.tsx可以利用中间件进行保护但更常见的做法是在page.tsx或layout.tsx的服务端组件中检查用户会话如果未登录则重定向。步骤 2实现训练列表页在app/(protected)/workouts/page.tsx中我们使用服务端组件来获取数据。import { createClient } from /lib/supabase/server import { redirect } from next/navigation import WorkoutCard from /components/workout-card // 一个自定义的展示组件 import { Button } from /components/ui/button import Link from next/link export default async function WorkoutsPage() { const supabase createClient() const { data: { user } } await supabase.auth.getUser() if (!user) { redirect(/login) // 未登录则跳转到登录页 } const { data: workouts } await supabase .from(workouts) .select(id, name, created_at, exercises ( name, sets, reps )) // 关联查询训练动作 .eq(user_id, user.id) .order(created_at, { ascending: false }) return ( div classNamecontainer mx-auto p-6 div classNameflex justify-between items-center mb-6 h1 classNametext-3xl font-bold我的训练记录/h1 Button asChild Link href/workouts/new 新建训练/Link /Button /div div classNamegrid gap-4 {workouts?.map((workout) ( WorkoutCard key{workout.id} workout{workout} / ))} {workouts?.length 0 ( p classNametext-center text-gray-500还没有训练记录开始你的第一次训练吧/p )} /div /div ) }步骤 3使用 Server Action 创建新训练在app/(protected)/workouts/new/page.tsx中我们创建一个表单并使用 Server Action 来处理提交避免创建额外的 API 路由。 首先在app/(protected)/workouts/actions.ts中定义 Actionuse server import { createClient } from /lib/supabase/server import { revalidatePath } from next/cache import { redirect } from next/navigation export async function createWorkout(formData: FormData) { const supabase createClient() const { data: { user } } await supabase.auth.getUser() if (!user) { throw new Error(未授权) } const name formData.get(name) as string // 这里可以获取更多表单字段如 exercises const { error } await supabase .from(workouts) .insert([{ name, user_id: user.id }]) if (error) { console.error(创建训练失败:, error) // 可以返回错误信息给前端展示 return { success: false, message: error.message } } // 成功创建后使训练列表页的缓存失效并重定向 revalidatePath(/workouts) redirect(/workouts) }然后在页面组件中使用这个 Action// app/(protected)/workouts/new/page.tsx import { createWorkout } from ../actions import { Input } from /components/ui/input import { Button } from /components/ui/button export default function NewWorkoutPage() { return ( form action{createWorkout} classNamespace-y-4 max-w-md mx-auto mt-10 div label htmlForname classNameblock text-sm font-medium训练名称/label Input idname namename required placeholder例如胸肌训练日 / /div {/* 可以添加更多输入字段用于记录动作、组数、重量等 */} Button typesubmit创建训练/Button /form ) }5. 深度定制、部署与常见问题排查5.1 样式与主题深度定制项目默认使用 Tailwind CSS 和 shadcn/ui。定制化主要从两个层面入手1. 定制 Tailwind修改tailwind.config.ts文件。例如为健身应用定义一套充满力量感的主题色。// tailwind.config.ts import type { Config } from tailwindcss const config: Config { theme: { extend: { colors: { primary: { DEFAULT: #3b82f6, // 蓝色 foreground: white, }, // 添加健身相关的语义化颜色 strength: #ef4444, // 红色用于最大重量 endurance: #10b981, // 绿色用于有氧 }, fontFamily: { sans: [Inter var, ...defaultTheme.fontFamily.sans], // 使用更现代的字体 }, }, }, }2. 定制 shadcn/ui 组件由于组件源代码就在你的/components/ui目录下你可以直接修改它们。例如修改button.tsx来改变所有按钮的圆角大小或阴影。// components/ui/button.tsx // ... 在 className 中添加或修改样式 const Button React.forwardRefHTMLButtonElement, ButtonProps( ({ className, variant default, size default, ...props }, ref) { return ( button className{cn( // 修改这里例如增加圆角 rounded-lg px-4 py-2 text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50, // ... 其他 variant 样式 )} ref{ref} {...props} / ) } )5.2 部署到 Vercel这是最简单的一步也是这个 Starter Kit 设计时优先考虑的部署方式。将你的代码推送到 GitHub、GitLab 或 Bitbucket 仓库。登录 Vercel 点击 “Add New...” - “Project”。导入你的 Git 仓库。在配置页面Vercel 会自动检测到这是一个 Next.js 项目。最关键的一步是配置环境变量。你需要手动添加或如果使用了 Supabase Vercel 集成可能会自动添加NEXT_PUBLIC_SUPABASE_URLNEXT_PUBLIC_SUPABASE_ANON_KEY点击 “Deploy”。几分钟后你的健身应用就上线了。使用 Supabase Vercel 集成更推荐在 Vercel 的项目设置中找到 “Integrations” 市场搜索并添加 “Supabase Integration”。按照指引授权并关联你的 Supabase 项目。完成后环境变量会自动同步到 Vercel无需手动填写且后续数据库连接字符串如有变更也会自动更新。5.3 常见问题与排查技巧实录在实际开发中你几乎一定会遇到下面这些问题。这里是我的踩坑记录和解决方案。问题现象可能原因解决方案登录后页面刷新用户状态丢失1. 中间件或服务端组件中使用的createClient方法不正确。2. Cookie 域名/路径设置问题。1. 确保在服务端server.ts和中间件middleware.ts中使用正确的createServerClient方法并传入cookies()。2. 检查lib/supabase/server.ts中createServerClient的cookies.setAll逻辑确保在中间件环境下错误被妥善处理try-catch。在服务端组件中调用supabase.from().select()返回空数组但数据存在未正确传递用户认证上下文。服务端客户端默认使用服务端密钥如果配置了或匿名密钥可能绕过 RLS。在查询前必须先获取当前请求的用户const { data: { user } } await supabase.auth.getUser();。然后在查询中使用.eq(user_id, user.id)或确保你的 RLS 策略能基于auth.uid()正确工作。pnpm dev运行时出现 “Invalidcookies()call” 错误Next.js 15 在某些情况下对cookies()的调用有更严格的限制。确保cookies()只在 Server Component、Server Action 或 Route Handler 中调用。如果在普通工具函数中调用需要将cookies作为参数传入。检查lib/supabase/server.ts确保其只在服务端上下文中被导入和使用。shadcn/ui 组件样式不生效或报错1.tailwind.config.ts中content路径未包含组件。2. 组件依赖的 CSS 变量未定义。1. 检查tailwind.config.ts的content数组确保包含了./components/**/*.{ts,tsx}。2. 确保app/globals.css中引入了tailwind base; tailwind components; tailwind utilities;以及 shadcn/ui 的主题 CSS 文件通常通过import引入。部署到 Vercel 后认证功能在生产环境失效生产环境的环境变量未正确设置或 Supabase 项目配置的“重定向 URL”不包含生产域名。1. 在 Vercel 项目设置中核对NEXT_PUBLIC_SUPABASE_URL和NEXT_PUBLIC_SUPABASE_ANON_KEY的值。2. 登录 Supabase 控制台进入Authentication URL Configuration将你的 Vercel 生产域名如https://yourapp.vercel.app添加到Site URL和Redirect URLs中。TypeScript 报错找不到模块/lib/...或/components/...tsconfig.json中的baseUrl或paths配置不正确。检查项目根目录的tsconfig.json文件确保包含类似配置baseUrl: ., paths: { /*: [./*] }。这是模板自带的如果丢失需手动添加。一个高级技巧优化数据库查询当你的训练记录越来越多关联查询exercises时可能会影响性能。考虑在数据库中对workouts.user_id和created_at字段创建索引并避免在列表页进行过于复杂的关联查询。对于分页可以使用 Supabase 的range()方法。const page 1 const pageSize 10 const { data, error, count } await supabase .from(workouts) .select(*, { count: exact }) // 获取总数 .eq(user_id, user.id) .order(created_at, { ascending: false }) .range((page - 1) * pageSize, page * pageSize - 1)这个 Starter Kit 提供了一个极其坚固和现代的全栈开发地基。从我个人的使用体验来看它最大的价值在于将那些繁琐、易错的基础设施配置认证、数据库连接、类型安全、部署标准化了让开发者能百分百专注于业务逻辑的创新——也就是去思考如何设计更好的训练动作库、如何可视化用户的进步曲线。如果你正打算用 Next.js 做一个需要用户系统的应用直接从这个模板开始至少能为你节省一周的摸索时间。剩下的就是尽情发挥你的创意去构建那个独一无二的应用了。
