跳到主要内容

Swee-官网

Swee 官网是 Swee AI 社交娱乐平台的品牌展示网站，基于 Next.js 13 构建。作为平台的对外门户，集成了品牌展示、应用下载引导、多语言支持、用户认证、SEO 优化等核心功能，同时承载账户管理（注销等）等关键用户操作。

一、项目技术架构​

1.1 整体架构图​

1.2 核心技术栈​

领域技术选型版本
框架Next.js (Pages Router)13.4.1
UI 库React + HeroUI18.x / 2.7.5
状态管理Recoil0.7.6
样式Tailwind CSS + SCSS3.4.10
动画Framer Motion + Swiper11.3.30 / 11.0.5
国际化next-i18next + i18next15.3.1 / 23.16.5
HTTPAxios (via @swee/request)1.3.3
错误监控Sentry7.105.0
日志Pino8.11.0
移动调试VConsole3.15.1
部署Docker + PM2 + K8s-

1.3 Provider 嵌套架构​

二、核心功能模块​

2.1 页面路由结构​

路由功能说明
/品牌首页Swiper 轮播 + 下载引导
/contact联系我们商务联系信息
/profile/settings/close账户注销需登录保护
/dev开发测试组件调试页面
/login-test登录测试登录流程测试

2.2 品牌首页​

首页采用全屏 Swiper 轮播设计，支持：

  • 3 组 Banner 配置：每组包含标题、描述文案和对应背景图
  • 自动播放：5 秒间隔自动切换
  • 鼠标滚轮控制：mousewheel 模块实现滚轮切换
  • 无限循环：loop 模式无缝衔接
  • 响应式背景：Mobile/Desktop 加载不同尺寸背景图

2.3 灵活的页面配置系统​

每个页面支持声明式配置，通过 NextPageWithLayout 类型扩展：

声明式页面配置

通过 TypeScript 类型扩展 NextPage，实现页面级别的布局、权限、滚动条等配置声明化，避免在每个页面中重复编写逻辑代码。

types/page.d.ts
type NextPageWithLayout = NextPage & {
  Layout?: React.FC<any>;                // 自定义布局组件
  Wrapper?: React.FC<PropsWithChildren>; // 自定义包装组件
  hideHeader?: boolean;                  // 隐藏导航头部
  showScrollBar?: boolean;               // 显示滚动条
  pure?: boolean;                        // 纯组件模式（无 Layout）
  needLogin?: boolean;                   // 需要登录保护
};

2.4 认证与账户管理​

  • 统一认证：通过 @swee/login 的 AuthProvider 实现
  • 多方式登录：邮箱密码、邮箱验证码、Google OAuth、Web3 签名
  • 条件登录保护：页面配置 needLogin 后自动弹出登录弹窗
  • 账户注销：useDeleteAccount Hook + SweeModal 二次确认

三、国际化方案​

3.1 三语言支持​

语言代码说明
英文en-US默认语言
繁体中文zh-TW台湾市场
印尼语id-ID东南亚市场

3.2 实现架构​

国际化踩坑

必须设置 localeDetection: false 禁用自动语言检测。如果开启，搜索引擎爬虫会因为自动重定向而无法正确索引各语言版本的页面，严重影响 SEO 效果。

  • 禁用自动语言检测：localeDetection: false，避免爬虫问题
  • SSG 翻译注入：每个页面通过 getStaticProps = getTranslationStaticProps 预注入翻译
  • 客户端按需加载：使用 i18next-http-backend 在客户端异步加载

四、样式与设计系统​

4.1 多层样式架构​

4.2 关键样式配置​

样式架构设计

项目采用四层样式架构：Tailwind CSS 原子化 → HeroUI 组件库 → @swee/uikit 品牌预设 → SCSS 模块。通过 darkMode: 'class' 实现全站默认深色主题，配合 @swee/uikit 的 green-gradient 品牌渐变色统一视觉风格。

  • 暗色主题：darkMode: 'class'，全站默认深色背景
  • 品牌渐变色：bg-gradient 来自 @swee/uikit 的 green-gradient
  • 自定义断点：新增 xs: 475px 断点适配小屏设备
  • 骨架屏配色：自定义 react-loading-skeleton 深色模式变量
  • 图片长缓存：/images/* 设置 max-age=31536000, immutable

五、API 代码生成​

5.1 OpenAPI 自动化​

从 https://swee-gateway.x3live.info/swee-user/v3/api-docs 自动生成：

  • 登录/注册 API（邮箱密码、验证码、第三方）
  • 用户信息管理 API
  • 支付密码 API
  • 账户删除 API
  • 管理后台对接 API

六、错误监控与调试​

6.1 Sentry 全链路监控​

Sentry 三端覆盖

Sentry 同时覆盖 Client、Server、Edge 三端，实现全链路错误追踪。生产环境开启 10% 的 Session Replay 采样率，测试环境 100% 采样，并通过 maskAllText + blockAllMedia 确保用户隐私安全。

6.2 移动端调试​

utils/vconsole.ts
// 自动检测移动端 + Debug 模式，动态注入 VConsole
if (isClient && isDebug && isMobile) {
  import('vconsole').then((Vconsole) => new Vconsole.default());
}

七、部署架构​

7.1 Docker 多阶段构建​

7.2 Kubernetes 多环境部署​

环境命名空间域名
测试swee-testswee.x3live.info
生产swee-prodswee.xyz

资源配置：内存 1Gi request / 2Gi limit，临时存储 10Gi

八、技术亮点总结​

8.1 智能响应式设计​

  • Mobile / Desktop 分别加载不同背景图，避免移动端加载大图
  • 自动检测 UA 实现移动端重定向到 /mobile

8.2 SEO 优化策略​

SEO 优化成果

通过 SSG 静态生成 + Google Site Verification + 自定义 CDN 字体加载 + 合理 meta 标签配置，确保搜索引擎可完整抓取多语言页面内容，提升品牌站点的搜索可见性。

  • Google Site Verification 验证搜索控制台
  • SSG 静态生成确保爬虫可抓取
  • 自定义 Font 从 CDN 加载（static.swee.live）
  • 合理的 meta 标签配置

8.3 高效的图片管理​

  • TinyPNG 批量压缩脚本
  • 永久缓存策略（1 年 immutable）
  • 支持多种格式（JPEG, PNG, GIF, SVG, AVIF, HEIC, WebP）

8.4 工程化实践​

  • Monorepo 共享：6 个 @swee 公共包集成
  • OpenAPI 代码生成：API 类型自动同步后端
  • 组件脚手架：pnpm cc 快速创建标准化组件
  • 翻译管理：Excel 翻译总表 + 自动化脚本

8.5 Pino 日志系统​

  • 生产环境使用 Pino 高性能 JSON 日志
  • 支持日志级别控制

九、项目数据概览​

指标数据
页面路由5 个
视图组件4 个
公共包依赖6 个 @swee 包
支持语言3 种（en-US / zh-TW / id-ID）
环境配置3 套（dev / test / production）
Sentry 覆盖Client + Server + Edge 三端
静态资源缓存1 年 immutable
部署方式Docker + K8s + PM2