logo
0
0
WeChat Login

English | 简体中文

Portfolio - 作品集展示网站

主题 Next.js React TypeScript

Auth cnb

一个现代化的作品集展示网页,采用卡片堆叠伸展特效,支持悬停预览、点击展开、排序筛选等功能。



✨ 项目特性

  • 🎴 卡片堆叠特效:卡片以堆叠方式排列,悬停时平滑展开
  • 🖱️ 智能交互:悬停预览、点击固定展开、点击空白收起
  • 🎯 无抖动切换:使用容器级事件追踪,彻底解决边界抖动问题
  • 📱 响应式设计:完美适配桌面端和移动端
  • 优雅动画:CSS3 Transform + 弹性动画

🛠 技术栈

技术版本说明
Next.js16.1.1React 全栈框架
React19.2.3UI 库
TypeScript5.x类型安全
Tailwind CSS4.x原子化 CSS
shadcn/uilatestUI 组件库
Lucide React0.468.0图标库

📁 项目结构

portfolio/
├── .coze                    # Coze CLI 配置文件
├── package.json             # 项目依赖配置
├── tsconfig.json            # TypeScript 配置
├── next.config.ts           # Next.js 配置
├── postcss.config.mjs       # PostCSS 配置
├── .npmrc                   # npm/pnpm 配置
├── .gitignore               # Git 忽略文件
│
├── public/                  # 静态资源
│   └── *.svg                # SVG 图标
│
├── scripts/                 # 脚本文件
│   ├── build.sh             # 构建脚本
│   ├── dev.sh               # 开发启动脚本
│   ├── start.sh             # 生产启动脚本
│   └── prepare.sh           # 准备脚本
│
└── src/
    ├── app/                 # Next.js App Router
    │   ├── layout.tsx       # 根布局
    │   ├── page.tsx         # 主页面
    │   ├── globals.css      # 全局样式
    │   ├── favicon.ico      # 网站图标
    │   └── robots.ts        # 爬虫配置
    │
    ├── components/          # React 组件
    │   ├── ProjectCard.tsx  # 项目卡片组件
    │   └── ui/              # shadcn/ui 组件库
    │
    ├── data/                # 静态数据
    │   └── projects.ts      # 项目数据
    │
    ├── types/               # TypeScript 类型定义
    │   └── project.ts       # 项目类型
    │
    ├── hooks/               # React Hooks
    │   └── use-mobile.ts    # 移动端检测
    │
    ├── lib/                 # 工具函数
    │   └── utils.ts         # 通用工具
    │
    └── server.ts            # 自定义服务器

🚀 快速开始

环境要求

  • Node.js: >= 20.x (推荐 24.x)
  • pnpm: >= 9.0.0

安装 pnpm

# 使用 npm 安装
npm install -g pnpm

# 或使用 corepack
corepack enable
corepack prepare pnpm@latest --activate

安装依赖

pnpm install

开发模式

pnpm dev

访问 http://localhost:5000

生产构建

pnpm build

生产运行

pnpm start

💾 无服务器配置

本项目是一个纯前端静态网站,不需要后端服务器和数据库。

为什么不需要服务器?

  1. 静态数据源:项目数据存储在 src/data/projects.ts
  2. 客户端渲染:所有交互在浏览器端完成
  3. 无 API 调用:不需要连接数据库或外部 API

如何修改项目数据?

编辑 src/data/projects.ts 文件:

export const projects: Project[] = [
  {
    id: '1',
    title: '项目标题',
    description: '项目描述',
    image: 'https://example.com/image.jpg',
    tags: ['React', 'TypeScript'],
    category: 'web',
    date: '2024-01-01',
    link: 'https://example.com',
    github: 'https://github.com/example',
  },
  // 添加更多项目...
];

如何使用外部图片?

修改 next.config.ts 添加图片域名:

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-image-domain.com',
        pathname: '/**',
      },
    ],
  },
};

🗄️ 无数据库配置

本项目不需要数据库。如果未来需要添加数据库,可以:

方案一:使用本地 JSON 文件

// src/data/projects.json
[
  { "id": "1", "title": "项目1", ... },
  { "id": "2", "title": "项目2", ... }
]

// 在组件中导入
import projects from '@/data/projects.json';

方案二:使用 Supabase(如需动态数据)

项目已预装 @supabase/supabase-js,需要时可以:

// 创建 src/lib/supabase.ts
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

export default supabase;

📝 项目管理

添加新项目

src/data/projects.ts 中添加:

{
  id: 'unique-id',           // 唯一标识
  title: '项目名称',          // 项目标题
  description: '项目描述',    // 详细描述
  image: '图片URL',          // 封面图片
  tags: ['技术标签'],        // 技术标签数组
  category: 'web',           // 分类: web/mobile/design/other
  date: '2024-01-01',        // 项目日期
  link: 'https://...',       // 项目链接(可选)
  github: 'https://...',     // GitHub 链接(可选)
}

修改分类

src/types/project.ts 中修改:

export type Category = 'web' | 'mobile' | 'design' | 'other';

修改每页显示数量

src/app/page.tsx 中修改:

const CARDS_PER_PAGE = 5;  // 修改为你想要的数量

自定义样式

  • 全局样式: src/app/globals.css
  • 主题颜色: Tailwind CSS 类名
  • 组件样式: 各组件文件中的 Tailwind 类名

📦 构建部署

方式一:Vercel 部署(推荐)

  1. 推送代码到 GitHub
  2. Vercel 导入项目
  3. 自动检测 Next.js,点击 Deploy

方式二:Docker 部署

创建 Dockerfile:

FROM node:24-alpine AS builder

WORKDIR /app

# 安装 pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

# 复制依赖文件
COPY package.json pnpm-lock.yaml ./

# 安装依赖
RUN pnpm install --frozen-lockfile

# 复制源码
COPY . .

# 构建
RUN pnpm build

# 生产镜像
FROM node:24-alpine AS runner

WORKDIR /app

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
ENV PORT=5000

EXPOSE 5000

CMD ["node", "dist/server.js"]

构建并运行:

docker build -t portfolio .
docker run -p 5000:5000 portfolio

方式三:静态导出部署

修改 next.config.ts:

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,  // 静态导出需要
  },
};

构建:

pnpm build

生成的静态文件在 out/ 目录,可部署到任何静态托管服务。

方式四:Node.js 服务器部署

# 构建
pnpm build

# 运行
PORT=5000 pnpm start

🔧 环境变量

本项目默认不需要环境变量。如需配置,创建 .env.local:

# 如需使用 Supabase
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# 如需自定义端口
PORT=5000

❓ 常见问题

Q: 图片加载失败?

A: 确保图片域名已添加到 next.config.tsremotePatterns 中。

Q: 样式不生效?

A: 检查 Tailwind CSS 类名是否正确,确保 globals.css 已导入。

Q: 如何添加新页面?

A: 在 src/app/ 目录下创建新文件夹和 page.tsx 文件。

Q: 如何修改卡片样式?

A: 编辑 src/components/ProjectCard.tsx 中的样式。


⚡ 性能优化

  • ✅ 图片使用 Next.js Image 组件自动优化
  • ✅ 组件使用 useCallback 优化重渲染
  • ✅ 鼠标事件使用 RAF 节流
  • ✅ CSS 动画使用 GPU 加速(transform、opacity)

🌐 浏览器支持

  • Chrome >= 90
  • Firefox >= 88
  • Safari >= 14
  • Edge >= 90

📄 License

MIT License


🤝 贡献

欢迎提交 Issue 和 Pull Request!


Fork 历史趋势图

About

基于Next.js+React+TypeScript的现代化作品集展示网站,搭载无抖动卡片堆叠特效与全端响应式适配,支持智能交互与内容管理。

现代化作品集卡片堆叠特效悬停预览排序筛选响应式设计
Language
TypeScript93.1%
CSS5.8%
Shell0.8%
JavaScript0.3%