项目简介
这是一个基于 Next.js 开发的开源电商门户项目，旨在演示电商平台常见功能及最佳实践。项目适合用于学习或快速启动 B2C 电商应用，支持多语言切换和响应式布局等。主要功能包括商品类目页、商品详情页、购物车、订单结算页、用户登录与订单管理等。
技术栈
- Next.js（App Router） ：使用 Next.js 最新的 App Router 构建。App Router 基于文件系统路由，支持 React Server Components、Suspense、Server Functions 等新特性。项目中混合使用静态生成（SSG）、增量静态再生（ISR）和服务端渲染（SSR）策略，提高性能和 SEO。
- Tailwind CSS：采用 Tailwind CSS 进行样式，Tailwind 是一个高度可定制的实用型 CSS 框架，为构建定制化设计提供了丰富的构建模块。
- shadcn/ui：使用 shadcn/ui 组件库，它基于 Radix UI 和 Tailwind 打造，提供易用且不含过度封装的可复用 UI 组件。该库的优点是生成的代码与手写代码几乎一致，无隐藏抽象。
- next-auth（或 Auth.js） ：用于用户认证，NextAuth.js 为 Next.js 提供开箱即用的认证解决方案，支持多种登录方式（社交登录、邮件登录等）。
- next-intl：用于国际化（i18n），next-intl 与 Next.js 路由系统集成良好，支持 App Router、服务器组件和静态渲染等场景，可简化多语言内容管理。
- Prisma：作为 ORM 与数据库交互。Prisma 提供强类型的数据库客户端和自动迁移工具，显著提升数据库操作的可靠性和开发体验。
- useSWR：用于前端数据获取。SWR 是 Vercel 提供的 React 数据获取钩子库，遵循 stale-while-revalidate 缓存策略，具有内置缓存与自动重新验证功能，可支持 SSR/ISR/SSG 等场景。
关键实现点
- 鉴权中间件：通过在
middleware.ts中读取会话 Cookie，判断用户是否已登录，对受保护路由进行重定向或拦截。Next.js Middleware 运行在 Edge 环境，可以在请求到达页面前执行权限检查。 - 多语言切换：使用 Next.js 的动态路由参数和 next-intl 的 Hook（如
useTranslations）实现语言切换和本地化文本替换。路由中包含语言前缀（如/zh和/en），利用 next-intl 的generateStaticParams等机制预渲染不同语言的内容。 - 静态与动态路由结合：商品详情等页面使用动态路由（如
app/[locale]/product/[id]/page.tsx）来根据商品 ID 渲染页面；同时通过generateStaticParams在构建时静态生成常用路径，提高加载速度。这样既保留了动态数据的灵活性，又利用静态渲染优化性能。 - Suspense 异步组件加载：利用 React 的
Suspense边界为异步组件提供加载占位（loading）界面。将需要延迟加载数据的子组件放入<Suspense>边界内，可以协调多个组件同时加载或分阶段加载的效果。 - useActionState 表单处理：在登录、购物车更新等表单中使用
useActionState钩子，提交表单触发服务器 Action 函数，并在客户端接收返回的更新状态。该钩子允许在服务器组件环境下，在客户端 JavaScript 加载前也能更新 UI 状态。 - API 路由结构：项目在
app/api（或pages/api）目录下编写 API 路由文件，以实现后端接口功能。Next.js 的 API 路由机制可以直接在应用内构建服务端接口，部署到 Vercel 时会自动以 Serverless 函数形式运行。 - 部署到 Vercel：利用 Vercel 平台的零配置特性进行部署。Next.js 与 Vercel 深度集成，自动支持 App Router、ISR、环境变量等功能，无需额外配置即可快速上线。
遇到的问题与解决方案
- 部署后 404：静态资源路径或构建配置问题可能导致部署后访问某些路径出现 404。通常需要检查
next.config.js的basePath、trailingSlash设置，以及正确配置动态路由的 fallback 策略，确保构建时已包含所有必要的页面。 - Session 获取失败：在使用 next-auth 时，可能遇到服务端无法获取会话（如调用
getServerSession失败）等问题。解决方案包括：确保在服务器环境使用getServerSession并正确传入authOptions；检查 Cookie 设置（如httpOnly、secure）是否符合要求；以及中间件仅在客户端进行简单会话检查，而关键的安全验证逻辑应在后端完成。 - 重定向丢失语言前缀：使用 Next.js 中间件或其他方法重定向时，有时会忽略 URL 中的语言前缀。为避免此类问题，需要在处理逻辑中保留或手动添加当前语言前缀，或者使用 next-intl 提供的跳转工具来自动处理语言上下文。
项目结构
图：项目主要目录结构（示例）
项目代码组织在 src 目录下，包含 app（应用路由）、api（后端接口）、components（UI 组件）、lib（工具库）、services（业务逻辑）、prisma（数据库模式定义）等。其中 app/[locale] 目录下定义了不同语言版本的页面子路径，如 category、product、cart 等。
项目预览
项目运行示例页面包括多语言首页、商品类目页、购物车页面、订单结算页面等。以下是部分界面预览（示意）：
- 主页：展示分类列表和推荐商品。
- 类目页：显示某一分类下的商品列表，支持分页和过滤。
- 商品详情页：展示商品图片、价格和详情信息。
- 购物车页：列出已加入购物车的商品，可更新数量或删除。
- 结算页：填写地址、选择支付方式并提交订单。
总结与未来改进
通过该项目，我们掌握了 Next.js App Router 及相关技术栈的使用方法，包括混合渲染策略、多语言国际化、现代表单处理等。未来可以进一步优化性能，例如添加缓存、细化增量静态更新策略，以及丰富购物功能（如支付集成、优惠券系统）和完善测试覆盖等，以提升项目的实用性和可维护性。
项目地址github.com/yuandabo/ne… 预览：next-portal-otskg7if8-yuandabos-projects.vercel.app/zh
