265 lines
8.2 KiB
Markdown
265 lines
8.2 KiB
Markdown
# venus-nextjs
|
||
|
||
个人作品集/博客网站模板，适用于设计师、开发者、自由职业者展示作品和服务。
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 15.5.9 (已锁定版本，App Router)
|
||
- React 19.2.3 (已锁定版本，修复 CVE-2025-55182 漏洞)
|
||
- TypeScript 5
|
||
- Tailwind CSS 4
|
||
- next-auth (身份认证)
|
||
- next-themes (深色/浅色主题切换)
|
||
- AOS (滚动动画)
|
||
- react-slick (轮播组件)
|
||
- Markdown/MDX (博客内容)
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/
|
||
├── app/ # Next.js App Router 入口
|
||
│ ├── layout.tsx # 根布局 (Header + Footer + 主题Provider)
|
||
│ ├── page.tsx # 首页
|
||
│ ├── not-found.tsx # 404 页面
|
||
│ ├── globals.css # 全局样式
|
||
│ ├── context/ # React Context
|
||
│ │ └── AuthDialogContext.tsx # 认证对话框状态管理
|
||
│ ├── api/ # API 路由和数据
|
||
│ │ ├── auth/[...nextauth]/route.ts # NextAuth 认证 API
|
||
│ │ ├── data.tsx # 静态数据 (菜单、计数器、服务、作品集)
|
||
│ │ └── contex/ToasetContex.tsx # Toast 通知 Context
|
||
│ └── (site)/ # 路由分组 (共享布局)
|
||
│ ├── about/page.tsx # 关于页面
|
||
│ ├── blog/page.tsx # 博客列表
|
||
│ ├── contact/page.tsx # 联系页面
|
||
│ ├── documentation/page.tsx # 文档页面
|
||
│ ├── portfolio/page.tsx # 作品集列表
|
||
│ └── services/page.tsx # 服务页面
|
||
├── components/ # 可复用组件
|
||
│ ├── Layout/ # 布局组件
|
||
│ │ ├── Header/index.tsx # 导航栏 (Logo + 菜单 + 主题切换)
|
||
│ │ └── Footer/index.tsx # 页脚
|
||
│ ├── Home/ # 首页专用组件
|
||
│ │ ├── Hero/index.tsx # Hero 区域
|
||
│ │ ├── Services/index.tsx # 服务展示
|
||
│ │ ├── Counter/index.tsx # 数据统计
|
||
│ │ ├── WorkProgress/index.tsx # 工作进度
|
||
│ │ └── Contact/index.tsx # 联系表单
|
||
│ ├── Auth/ # 认证相关
|
||
│ │ ├── SignIn/index.tsx # 登录组件
|
||
│ │ ├── SignUp/index.tsx # 注册组件
|
||
│ │ ├── SocialSignIn.tsx # 社交登录
|
||
│ │ └── AuthDialog/ # 认证对话框
|
||
│ ├── Blog/ # 博客组件
|
||
│ ├── Contact/ # 联系页组件
|
||
│ │ ├── Form/index.tsx # 联系表单
|
||
│ │ ├── ContactInfo/index.tsx # 联系信息
|
||
│ │ └── OfficeLocation/index.tsx # 办公地点
|
||
│ ├── Documentation/ # 文档组件
|
||
│ ├── portfolio/ # 作品集组件
|
||
│ ├── Common/ # 通用组件
|
||
│ ├── SharedComponent/ # 共享组件
|
||
│ ├── Breadcrumb/ # 面包屑
|
||
│ ├── ScrollToTop/ # 回到顶部按钮
|
||
│ ├── NotFound/ # 404 组件
|
||
│ └── nextauth/ # NextAuth Provider
|
||
├── types/ # TypeScript 类型定义
|
||
│ ├── blog.ts # 博客类型
|
||
│ ├── menu.ts # 菜单类型
|
||
│ └── breadcrumb.ts # 面包屑类型
|
||
├── utils/ # 工具函数
|
||
│ ├── image.ts # 图片路径处理
|
||
│ ├── aos.tsx # AOS 动画初始化
|
||
│ ├── markdown.ts # Markdown 解析
|
||
│ ├── markdownToHtml.ts # Markdown 转 HTML
|
||
│ ├── validateEmail.ts # 邮箱验证
|
||
│ └── extendedConfig.ts # 扩展配置
|
||
└── Style/ # 样式文件
|
||
└── style.css # 组件样式
|
||
|
||
markdown/ # 博客内容 (MDX 格式)
|
||
└── Blog/
|
||
├── Blog_1.mdx
|
||
├── Blog_2.mdx
|
||
└── ...
|
||
|
||
public/ # 静态资源
|
||
└── images/
|
||
├── logo/ # Logo 图片
|
||
├── hero/ # Hero 区域图片
|
||
├── blog/ # 博客封面图
|
||
├── portfolio/ # 作品集图片
|
||
├── services/ # 服务图标
|
||
├── contact/ # 联系页图片
|
||
├── counter/ # 计数器图标
|
||
├── testimonial/ # 评价图片
|
||
├── footer/ # 页脚图标
|
||
└── documentation/ # 文档图片
|
||
```
|
||
|
||
## 路由配置
|
||
|
||
| 路径 | 页面 | 说明 |
|
||
|------|------|------|
|
||
| `/` | Home | 首页 (Hero + 服务 + 作品集 + 评价 + 联系) |
|
||
| `/about` | About | 关于我 |
|
||
| `/services` | Services | 服务介绍 |
|
||
| `/portfolio` | Portfolio | 作品集列表 |
|
||
| `/blog` | Blog | 博客列表 |
|
||
| `/contact` | Contact | 联系方式 |
|
||
| `/documentation` | Documentation | 模板文档 |
|
||
|
||
## 数据结构
|
||
|
||
### 菜单数据 (src/app/api/data.tsx)
|
||
|
||
```typescript
|
||
export const menuItems = [
|
||
{ name: "Home", href: "#home" },
|
||
{ name: "About", href: "#about" },
|
||
{ name: "Services", href: "#services" },
|
||
{ name: "Portfolio", href: "#portfolio" },
|
||
{ name: "Testimonials", href: "#testimonials" },
|
||
{ name: "Blog", href: "/#blog" },
|
||
];
|
||
```
|
||
|
||
### 服务数据 (src/app/api/data.tsx)
|
||
|
||
```typescript
|
||
export const Servicebox = [
|
||
{
|
||
icon: '/images/services/ux-design-product_1.svg',
|
||
title: 'UX & Product Design',
|
||
description: '服务描述...',
|
||
},
|
||
// ...
|
||
];
|
||
```
|
||
|
||
### 作品集数据 (src/app/api/data.tsx)
|
||
|
||
```typescript
|
||
export const portfolioinfo = [
|
||
{
|
||
image: '/images/portfolio/cozycasa.png',
|
||
alt: 'Portfolio',
|
||
title: 'Cozycasa',
|
||
slug: 'Cozycasa',
|
||
info: 'Designation',
|
||
Class: 'md:mt-0' // 布局样式
|
||
},
|
||
// ...
|
||
];
|
||
```
|
||
|
||
### 博客类型 (src/types/blog.ts)
|
||
|
||
```typescript
|
||
export type Blog = {
|
||
id?: number;
|
||
title?: string;
|
||
slug?: string;
|
||
excerpt?: string;
|
||
coverImage?: string;
|
||
date: string;
|
||
};
|
||
```
|
||
|
||
## 核心组件说明
|
||
|
||
### 布局系统
|
||
|
||
- `RootLayout` (src/app/layout.tsx): 根布局，包含主题Provider、认证Provider、Header和Footer
|
||
- 使用 `next-themes` 实现深色/浅色模式切换
|
||
- 使用 `next-auth` 实现用户认证
|
||
|
||
### 主题切换
|
||
|
||
主题通过 `next-themes` 的 `ThemeProvider` 管理，支持:
|
||
|
||
- `light` - 浅色主题
|
||
- `dark` - 深色主题
|
||
- `system` - 跟随系统
|
||
|
||
### 动画效果
|
||
|
||
使用 AOS (Animate On Scroll) 库，在 `src/utils/aos.tsx` 初始化
|
||
|
||
### 认证系统
|
||
|
||
使用 `next-auth` v4，配置文件位于 `src/app/api/auth/[...nextauth]/route.ts`。
|
||
|
||
启用社交登录需要：
|
||
|
||
1. 在 `.env.local` 中配置环境变量：
|
||
|
||
```bash
|
||
NEXTAUTH_SECRET=your-secret-key
|
||
NEXTAUTH_URL=http://localhost:3000
|
||
|
||
# Google 登录
|
||
GOOGLE_CLIENT_ID=your-google-client-id
|
||
GOOGLE_CLIENT_SECRET=your-google-client-secret
|
||
|
||
# GitHub 登录
|
||
GITHUB_ID=your-github-id
|
||
GITHUB_SECRET=your-github-secret
|
||
```
|
||
|
||
1. 在 `route.ts` 中取消对应 provider 的注释
|
||
|
||
## 常见修改任务
|
||
|
||
### 修改网站信息
|
||
|
||
1. 修改 `src/components/Layout/Header/index.tsx` 中的 Logo
|
||
2. 修改 `src/components/Layout/Footer/index.tsx` 中的版权信息
|
||
3. 修改 `src/app/layout.tsx` 中的 metadata
|
||
|
||
### 修改导航菜单
|
||
|
||
编辑 `src/app/api/data.tsx` 中的 `menuItems` 数组
|
||
|
||
### 添加新页面
|
||
|
||
1. 在 `src/app/(site)/` 目录下创建新文件夹和 `page.tsx`
|
||
2. 在 `menuItems` 中添加导航项
|
||
|
||
### 添加博客文章
|
||
|
||
1. 在 `markdown/Blog/` 目录下创建新的 `.mdx` 文件
|
||
2. 使用 frontmatter 定义标题、日期、封面图等
|
||
|
||
### 修改样式主题
|
||
|
||
1. 编辑 `src/app/globals.css` 中的 CSS 变量
|
||
2. 或修改 `tailwind.config.ts` 中的主题配置
|
||
|
||
### 修改服务/作品集数据
|
||
|
||
编辑 `src/app/api/data.tsx` 中对应的数据数组
|
||
|
||
## 图片资源
|
||
|
||
- 存放在 `public/images/` 目录
|
||
- 使用 `getImgPath()` 工具函数获取路径 (src/utils/image.ts)
|
||
- 引用路径：`/images/xxx.jpg`
|
||
|
||
## 安全说明
|
||
|
||
以下依赖版本已锁定以修复安全漏洞：
|
||
|
||
- **Next.js 15.5.9** - 锁定版本，修复漏洞编号为：CVE-2025-66478
|
||
- **React 19.2.3** - 修复 React Server Components 远程代码执行漏洞 (CVE-2025-55182)
|
||
|
||
请勿使用 `^` 或 `~` 前缀以避免自动升级到有漏洞的版本。
|