English | 简体中文

---

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

---

技术	版本	说明
Next.js	16.1.1	React 全栈框架
React	19.2.3	UI 库
TypeScript	5.x	类型安全
Tailwind CSS	4.x	原子化 CSS
shadcn/ui	latest	UI 组件库
Lucide React	0.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

# 使用 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: '/**',
      },
    ],
  },
};

---

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

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

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

项目已预装 @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 类名

---

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

创建 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/ 目录，可部署到任何静态托管服务。

# 构建
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

---

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

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

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

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

---

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

---

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

---

MIT License

---

欢迎提交 Issue 和 Pull Request！

---