基于Next.js与基础推荐算法构建智能水果推荐系统实践

1. 项目概述：从“猜你喜欢”到亲手实现

每次打开淘宝，首页那些“猜你喜欢”的商品推荐，是不是总能精准地戳中你的购物欲？你可能刚和朋友聊过想吃榴莲，下一秒App里就出现了猫山王的推送。这背后，就是推荐系统在默默工作。作为一个前端开发者，我常常好奇，这种看似“智能”的推荐，我们是否也能用现代前端技术栈来模拟和实现一个入门级的版本？答案是肯定的。

这个项目，就是一个用 Next.js 构建的智能水果推荐 Demo。它不追求淘宝、京东那种亿级用户和商品的复杂算法，而是聚焦于核心逻辑的落地：如何根据用户的行为（比如点击、浏览），动态地调整和生成个性化的推荐列表。我们将使用 Next.js 这个全栈框架来处理前后端，结合一些基础的推荐算法思想，构建一个可以运行、可以交互的完整应用。无论你是想学习 Next.js 的全栈能力，还是对推荐系统的原理感到好奇，亦或是想为自己的作品集增加一个“智能化”的亮点，这个项目都能提供一个清晰的实践路径。整个过程，我们会从零开始，涵盖项目初始化、数据模拟、算法实现、UI交互到部署上线的完整闭环。

2. 项目整体设计与技术选型思路

2.1 为什么选择 Next.js 作为全栈基石？

在决定技术栈时，我首先排除了传统的前后端分离方案（如 React + Express）。对于一个强调快速原型验证和一体化开发的 Demo 项目，Next.js 提供了开箱即用的全栈能力，这极大地简化了开发流程。其核心优势在于：

1. 一体化开发体验 ：我们可以在同一个项目中编写 React 前端页面和 API 路由（位于 pages/api 或 app/api 目录）。这意味着处理用户点击事件的前端组件，和计算推荐结果的服务器端逻辑，物理距离很近，心智负担小。调试和逻辑追踪非常直观。
2. 服务端渲染（SSR）与静态生成（SSG）的灵活性 ：对于推荐系统，首屏内容很关键。我们可以利用 Next.js 的 getServerSideProps 或 App Router 中的 Server Component，在用户请求页面时，在服务器端就根据初始信息（如会话 Cookie）计算出第一版推荐结果，直接塞入 HTML 中返回。这避免了首页先出现一个空白或加载态，再通过客户端 JavaScript 去获取数据的体验断层，对用户体验和 SEO 都更友好。
3. API Routes 的便捷性 ：所有推荐算法的核心计算逻辑，我都放在 API Routes 中。这相当于一个内置的、无需额外配置的 Node.js 后端。前端通过 fetch 调用这些接口，接口内部进行算法运算并返回 JSON 数据。这种模式清晰地将数据准备（服务器）与数据展示（客户端）分离，同时又保持了项目的统一性。
4. 蓬勃的生态与部署友好 ：Vercel 作为 Next.js 的“亲爹”，提供了极其平滑的部署体验。基本上 git push 后就自动完成构建和全球分发。这对于展示 Demo 至关重要，你可以轻松获得一个可公开访问的链接。

2.2 模拟数据与推荐算法的轻量化设计

真实的推荐系统依赖海量的用户行为日志和商品特征数据。对于 Demo，我们需要一个轻量级但能体现核心原理的设计。

数据层设计 ： 我创建了一个模拟的“水果数据库”，它是一个 JSON 数组，每件水果包含： id （唯一标识）、 name （名称）、 category （类别，如“浆果类”、“热带水果”）、 tags （标签数组，如[“甜”, “多汁”, “维生素C高”]）、 price （价格）和 image （图片URL）。同时，模拟一个“用户行为记录表”，记录用户对水果的 view （浏览）、 click （点击）、 purchase （购买，Demo中可能简化为“加入购物车”）等行为，并附带时间戳。

算法层设计（核心） ： 我们不会引入复杂的机器学习模型，而是实现两种经典的、易于理解的推荐逻辑：

1. 基于内容的推荐 ：这是本 Demo 的重点。原理是“你喜欢A，那么和A相似的东西你可能也喜欢”。如何定义“相似”？我们利用水果的 category 和 tags 。当用户频繁点击“蓝莓”（标签：[“浆果”, “甜”, “抗氧化”]）时，算法会计算其他水果与“蓝莓”的标签相似度（如Jaccard相似系数或简单的共同标签计数），将相似度高的水果推荐出来。
2. 协同过滤的简化版 ：由于我们没有多用户数据，这里做一个“单用户”的简化模拟。原理是“你点击了A和B，那么其他和A、B经常被一起点击的水果C，可能你也喜欢”。这需要维护一个“物品-物品”的共现矩阵。例如，用户历史行为中，“香蕉”和“牛奶”经常在同一个会话中被浏览，那么当用户再次查看“香蕉”时，就推荐“牛奶”。在Demo中，我们可以初始化一个小的共现关系表来模拟这种关联。

在实际API中，我会将两种算法的结果按一定权重（比如内容推荐占70%，协同过滤占30%）进行混合，然后去重，最终生成一个推荐列表返回给前端。

2.3 前端交互与状态管理规划

前端需要完成两件事：展示水果列表/详情，以及收集用户行为。

我选择使用 React 的 Context API 或 Zustand 这样轻量的状态库来管理全局的“用户行为日志”。每当用户在客户端进行点击、浏览详情等操作时，不仅会更新UI，还会立即向专用的行为记录API（如 POST /api/behavior ）发送一条日志。同时，这个行为也会触发一个获取新推荐列表的请求（如 GET /api/recommendations ）。

UI 布局上，计划设计一个主展示区，可能是网格布局的水果卡片。一个侧边栏或顶部区域，用于展示“根据你的喜好推荐”的动态列表。这个推荐列表会随着用户交互而实时更新，从而直观地体现“智能”感。使用 SWR 或 React Query 来管理推荐数据的获取、缓存和重新验证，可以极大地简化数据同步的逻辑，确保用户体验的流畅性。

3. 核心细节解析与实操要点

3.1 项目初始化与基础结构搭建

首先，使用 Next.js 官方脚手架快速创建项目。我倾向于使用 create-next-app 并选择 TypeScript 模板，因为类型系统能在开发阶段帮我们规避很多数据格式错误。

npx create-next-app@latest fruit-recommendation-demo --typescript --tailwind --app
cd fruit-recommendation-demo
npm install zustand swr

这里我同时安装了 Tailwind CSS 用于快速样式构建，以及 Zustand（状态管理）和 SWR（数据获取）。选择 App Router 是因为它是 Next.js 未来的方向，提供了更灵活的服务器/客户端组件组合能力。

项目的基础目录结构会是这样：

fruit-recommendation-demo/
├── app/
│   ├── api/
│   │   ├── behavior/
│   │   │   └── route.ts      # 处理用户行为日志上报
│   │   ├── recommendations/
│   │   │   └── route.ts      # 核心推荐算法接口
│   │   └── fruits/
│   │       └── route.ts      # 获取所有水果数据
│   ├── layout.tsx
│   ├── page.tsx              # 首页
│   └── globals.css
├── lib/
│   ├── data.ts               # 模拟的水果数据和行为数据
│   ├── algorithms.ts         # 推荐算法实现
│   └── store.ts              # Zustand 状态存储
├── components/               # 可复用组件
│   ├── FruitCard.tsx
│   ├── RecommendationSidebar.tsx
│   └── ...
└── public/                   # 静态资源

在 lib/data.ts 中，我会定义模拟数据。这里的关键是设计好水果的特征向量。例如：

// lib/data.ts
export interface Fruit {
  id: string;
  name: string;
  category: string;
  tags: string[]; // 这是关键，用于内容推荐
  price: number;
  imageUrl: string;
}

export const mockFruits: Fruit[] = [
  { id: '1', name: '蓝莓', category: '浆果类', tags: ['甜', '抗氧化', '小颗粒'], price: 25, imageUrl: '/images/blueberry.jpg' },
  { id: '2', name: '草莓', category: '浆果类', tags: ['甜', '多汁', '维生素C高'], price: 30, imageUrl: '/images/strawberry.jpg' },
  { id: '3', name: '芒果', category: '热带水果', tags: ['甜', '香', '纤维多'], price: 15, imageUrl: '/images/mango.jpg' },
  { id: '4', name: '香蕉', category: '热带水果', tags: ['甜', '便携', '能量高'], price: 6, imageUrl: '/images/banana.jpg' },
  { id: '5', name: '橙子', category: '柑橘类', tags: ['酸甜', '多汁', '维生素C高'], price: 8, imageUrl: '/images/orange.jpg' },
  // ... 更多水果
];

// 模拟一个简单的物品共现关系（用于简化版协同过滤）
export const mockCoOccurrence: Record<string, string[]> = {
  '1': ['2', '5'], // 买了蓝莓的人，也常看草莓和橙子
  '2': ['1', '3'],
  '3': ['2', '4'],
  // ...
};

注意 ： tags 的设计至关重要，它直接决定了内容推荐算法的准确度和可解释性。标签应该尽量客观、可区分，避免过于笼统。初期可以少而精，后续再根据效果调整。

3.2 推荐算法接口的详细实现

推荐算法的核心在 app/api/recommendations/route.ts 中。这是一个 Next.js App Router 的 API Route。

// app/api/recommendations/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { mockFruits, mockCoOccurrence } from '@/lib/data';
import { calculateRecommendations } from '@/lib/algorithms';

export async function GET(request: NextRequest) {
  // 1. 获取用户标识（这里简化使用URL参数，实际应用可用Cookie或Session）
  const searchParams = request.nextUrl.searchParams;
  const userId = searchParams.get('userId') || 'anonymous';
  
  // 2. 模拟获取该用户的历史行为（实际应从数据库读取）
  // 这里我们假设有一个函数 getUserBehavior 返回用户最近点击的水果ID数组
  const userViewedFruitIds = await getMockUserBehavior(userId); // 例如返回 ['1', '3']
  
  if (userViewedFruitIds.length === 0) {
    // 如果用户无历史行为，退回热门或随机推荐
    const popularFruits = mockFruits.sort(() => Math.random() - 0.5).slice(0, 5);
    return NextResponse.json({ recommendations: popularFruits });
  }
  
  // 3. 调用算法计算推荐结果
  const recommendedFruits = calculateRecommendations(userViewedFruitIds, mockFruits, mockCoOccurrence);
  
  // 4. 返回JSON数据
  return NextResponse.json({ recommendations: recommendedFruits });
}

// 模拟获取用户行为
async function getMockUserBehavior(userId: string): Promise<string[]> {
  // 这里应该连接数据库查询。Demo中我们返回一个固定值或简单逻辑。
  // 例如，可以存在一个全局的Map在内存中（注意：服务器重启会丢失）
  return ['1', '3']; // 模拟用户看过蓝莓和芒果
}

真正的算法逻辑在 lib/algorithms.ts 中实现。这里展示一个混合推荐的简单示例：

// lib/algorithms.ts
import { Fruit } from './data';

export function calculateRecommendations(
  viewedIds: string[],
  allFruits: Fruit[],
  coOccurrence: Record<string, string[]>
): Fruit[] {
  
  // 1. 基于内容的推荐
  const contentBasedScores = new Map<string, number>(); // fruitId -> score
  
  viewedIds.forEach(viewedId => {
    const viewedFruit = allFruits.find(f => f.id === viewedId);
    if (!viewedFruit) return;
    
    allFruits.forEach(fruit => {
      if (viewedIds.includes(fruit.id)) return; // 排除已经看过的
      
      // 计算相似度：共同标签的数量
      const commonTags = fruit.tags.filter(tag => viewedFruit.tags.includes(tag)).length;
      const totalTags = new Set([...fruit.tags, ...viewedFruit.tags]).size;
      const similarity = totalTags > 0 ? commonTags / totalTags : 0;
      
      const currentScore = contentBasedScores.get(fruit.id) || 0;
      contentBasedScores.set(fruit.id, currentScore + similarity);
    });
  });
  
  // 2. 基于协同过滤（简化版）的推荐
  const cfScores = new Map<string, number>();
  viewedIds.forEach(viewedId => {
    const relatedIds = coOccurrence[viewedId] || [];
    relatedIds.forEach(relatedId => {
      if (viewedIds.includes(relatedId)) return; // 排除已经看过的
      const currentScore = cfScores.get(relatedId) || 0;
      cfScores.set(relatedId, currentScore + 1); // 每共现一次加一分
    });
  });
  
  // 3. 混合评分
  const finalScores = new Map<string, number>();
  const contentWeight = 0.7;
  const cfWeight = 0.3;
  
  allFruits.forEach(fruit => {
    let score = 0;
    score += (contentBasedScores.get(fruit.id) || 0) * contentWeight;
    score += (cfScores.get(fruit.id) || 0) * cfWeight;
    if (score > 0) {
      finalScores.set(fruit.id, score);
    }
  });
  
  // 4. 按分数排序并返回水果对象
  const sortedFruitIds = Array.from(finalScores.entries())
    .sort((a, b) => b[1] - a[1])
    .map(entry => entry[0])
    .slice(0, 6); // 取Top 6
  
  return sortedFruitIds.map(id => allFruits.find(f => f.id === id)!);
}

这个算法虽然简单，但完整地演绎了推荐系统的两个核心思想。你可以通过调整 contentWeight 和 cfWeight 来观察推荐结果的变化，这本身就是理解推荐系统调优的一个很好实践。

3.3 前端交互与行为收集的实现

前端需要让用户能与水果卡片交互，并悄无声息地收集这些行为。我们在 lib/store.ts 中创建一个 Zustand Store 来管理用户行为日志，并封装上报逻辑。

// lib/store.ts
import { create } from 'zustand';

interface BehaviorLog {
  fruitId: string;
  action: 'view' | 'click' | 'add_to_cart';
  timestamp: number;
}

interface BehaviorStore {
  logs: BehaviorLog[];
  logBehavior: (fruitId: string, action: BehaviorLog['action']) => Promise<void>;
}

export const useBehaviorStore = create<BehaviorStore>((set, get) => ({
  logs: [],
  logBehavior: async (fruitId, action) => {
    const newLog: BehaviorLog = { fruitId, action, timestamp: Date.now() };
    
    // 1. 更新本地状态（用于即时反馈或去重）
    set((state) => ({ logs: [...state.logs, newLog] }));
    
    // 2. 上报到服务器API
    try {
      await fetch('/api/behavior', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newLog),
      });
    } catch (error) {
      console.error('Failed to log behavior:', error);
      // 在实际项目中，这里可能需要将日志暂存到IndexedDB等本地存储，待网络恢复后重试
    }
    
    // 3. （可选）行为上报后，主动触发一次推荐更新
    // 这个逻辑可以放在调用logBehavior的组件中，更清晰
  },
}));

然后，在水果卡片组件中集成这个行为记录：

// components/FruitCard.tsx
import { Fruit } from '@/lib/data';
import { useBehaviorStore } from '@/lib/store';

interface FruitCardProps {
  fruit: Fruit;
}

export default function FruitCard({ fruit }: FruitCardProps) {
  const logBehavior = useBehaviorStore((state) => state.logBehavior);
  
  const handleClick = () => {
    // 1. 记录点击行为
    logBehavior(fruit.id, 'click');
    // 2. 这里可以跳转到详情页或执行其他UI逻辑
    console.log(`Selected fruit: ${fruit.name}`);
  };
  
  const handleMouseEnter = () => {
    // 记录浏览行为（可做防抖处理，避免过于频繁上报）
    logBehavior(fruit.id, 'view');
  };
  
  return (
    <div 
      className="border rounded-lg p-4 shadow hover:shadow-lg transition-shadow cursor-pointer"
      onClick={handleClick}
      onMouseEnter={handleMouseEnter}
    >
      <img src={fruit.imageUrl} alt={fruit.name} className="w-full h-48 object-cover rounded-md mb-3"/>
      <h3 className="font-semibold text-lg">{fruit.name}</h3>
      <p className="text-gray-600 text-sm mb-2">{fruit.tags.join(', ')}</p>
      <div className="flex justify-between items-center">
        <span className="font-bold text-red-600">¥{fruit.price}</span>
        <button 
          className="bg-blue-500 text-white px-3 py-1 rounded text-sm hover:bg-blue-600"
          onClick={(e) => {
            e.stopPropagation(); // 防止触发卡片的点击事件
            logBehavior(fruit.id, 'add_to_cart');
            alert(`已添加${fruit.name}到购物车`);
          }}
        >
          加入购物车
        </button>
      </div>
    </div>
  );
}

这样，每当用户与卡片交互时，行为都会被记录并上报。 /api/behavior 接口的实现就是简单地接收这些日志，并将其存储到数据库或内存中（Demo 阶段可以用全局变量或简单数据库如 SQLite 模拟）。

3.4 推荐侧边栏与数据实时更新

推荐侧边栏组件需要动态展示推荐结果。我们将使用 SWR 这个库来实现数据的获取、缓存和自动重新验证。SWR 的 useSWR hook 会帮我们管理请求状态（加载中、错误、成功），并可以在焦点重新回到页面时自动刷新数据。

// components/RecommendationSidebar.tsx
import useSWR from 'swr';
import { Fruit } from '@/lib/data';
import FruitCard from './FruitCard';

const fetcher = (url: string) => fetch(url).then(res => res.json());

export default function RecommendationSidebar() {
  // 假设我们有一个全局状态或上下文来获取当前用户的ID，这里先用固定值
  const userId = 'user-123';
  
  const { data, error, isLoading, mutate } = useSWR<{ recommendations: Fruit[] }>(
    `/api/recommendations?userId=${userId}`,
    fetcher,
    {
      refreshInterval: 30000, // 每30秒自动刷新一次推荐（可选）
      revalidateOnFocus: true, // 窗口聚焦时重新验证
    }
  );
  
  // 我们可以提供一个手动刷新的按钮，在用户完成一系列操作后调用
  const handleRefresh = () => {
    mutate(); // 这会触发数据的重新获取
  };
  
  if (isLoading) return <div className="p-4">正在为您生成推荐...</div>;
  if (error) return <div className="p-4 text-red-500">推荐加载失败</div>;
  
  return (
    <div className="w-80 border-l p-6">
      <div className="flex justify-between items-center mb-4">
        <h2 className="text-xl font-bold">猜你喜欢</h2>
        <button 
          onClick={handleRefresh}
          className="text-sm text-blue-500 hover:text-blue-700"
        >
          刷新推荐
        </button>
      </div>
      <p className="text-gray-500 text-sm mb-6">根据您的浏览和点击行为实时优化</p>
      <div className="space-y-4">
        {data?.recommendations.map(fruit => (
          <div key={fruit.id} className="border-b pb-4">
            <FruitCard fruit={fruit} compact /> {/* 可以设计一个紧凑模式的FruitCard */}
          </div>
        ))}
        {(!data || data.recommendations.length === 0) && (
          <div className="text-center text-gray-400 py-8">
            暂无推荐，快去浏览一些水果吧！
          </div>
        )}
      </div>
    </div>
  );
}

现在，只要将 RecommendationSidebar 组件布局到主页面的侧边，一个能够根据用户隐式反馈（浏览、点击）而动态更新的推荐系统 Demo 就初具雏形了。用户的所有交互都会通过 API 影响下一次的推荐结果。

4. 实操过程与核心环节实现

4.1 从零开始：项目环境搭建与启动

让我们一步步把项目跑起来。首先确保你的开发环境已安装 Node.js（建议 LTS 版本）和 npm/yarn/pnpm。

1. 创建项目 ：打开终端，执行我们之前提到的命令。使用 --tailwind 标志可以让样式开发更快。 --app 标志指定使用 App Router。

   npx create-next-app@latest fruit-ai-recommendation --typescript --tailwind --app
   cd fruit-ai-recommendation
   

2. 安装额外依赖 ：除了框架，我们还需要状态管理和数据获取库。

   npm install zustand swr
   # 如果需要更逼真的模拟，可以安装一个轻量级的内存数据库或ORM，但非必须
   # npm install lowdb 或 npm install prisma sqlite3
   

3. 启动开发服务器 ：

   npm run dev
   

   访问 http://localhost:3000 ，你应该能看到 Next.js 的默认欢迎页面。

4. 清理与初始化 ：删除 app/page.tsx 和 app/globals.css 中的默认内容，按照我们的设计开始构建。在 app/layout.tsx 中，我们可以设置一个基本的布局结构，包含主内容区和侧边推荐栏。

4.2 数据模拟与 API Route 的联调

在真实开发中，我习惯先搭建后端（API）的逻辑，并用工具测试通过后，再开发前端来消费它。这样前后端契约清晰。

1. 创建模拟数据文件 ：在 lib/data.ts 中，按照之前的设计，填充至少10-15种水果的详细信息。图片可以先使用网络上的免费图库链接，或者下载到 public/images/ 目录下使用相对路径。

2. 实现算法文件 ：在 lib/algorithms.ts 中，完整实现 calculateRecommendations 函数。为了调试方便，可以先写一个简单的测试脚本：

   // lib/test-algo.ts (临时文件)
   import { mockFruits, mockCoOccurrence } from './data';
   import { calculateRecommendations } from './algorithms';
   
   const result = calculateRecommendations(['1', '3'], mockFruits, mockCoOccurrence);
   console.log('推荐结果：', result.map(f => f.name));
   

   在终端运行 npx tsx lib/test-algo.ts （需要安装 tsx ）或配置一个 npm script，确保算法逻辑按预期工作。

3. 实现 API Routes ：

   • app/api/fruits/route.ts : 简单返回所有水果数据。用于首页列表展示。
   • app/api/behavior/route.ts : 接收 POST 请求，将行为日志打印到控制台或存入一个全局数组（注意：服务器重启会丢失）。在生产中，这里应连接数据库。
   • app/api/recommendations/route.ts : 整合算法，返回推荐列表。

   使用 curl 、Postman 或浏览器直接访问 http://localhost:3000/api/fruits 和 http://localhost:3000/api/recommendations?userId=test 来测试 API 是否正常工作。

4.3 前端页面的集成与状态联动

API 就绪后，前端页面的集成就是组装乐高。

1. 构建主页布局 ：修改 app/page.tsx ，使用 Flexbox 或 Grid 布局，左侧是水果主列表，右侧是 RecommendationSidebar 组件。

   // app/page.tsx
   import FruitList from '@/components/FruitList';
   import RecommendationSidebar from '@/components/RecommendationSidebar';
   
   export default async function HomePage() {
     // 使用 Server Component 获取初始水果列表，利于SEO和首屏加载
     const initialFruits = await getInitialFruits();
     
     return (
       <div className="flex min-h-screen">
         <main className="flex-1 p-8">
           <h1 className="text-3xl font-bold mb-8">新鲜水果商城</h1>
           <FruitList initialFruits={initialFruits} />
         </main>
         <aside className="w-96 border-l">
           <RecommendationSidebar />
         </aside>
       </div>
     );
   }
   
   async function getInitialFruits() {
     // 这里可以直接导入 mockFruits，或者调用内部API（注意：在Server Component中调用内部API是可行的）
     const res = await fetch('http://localhost:3000/api/fruits', { cache: 'no-store' });
     return res.json();
   }
   

2. 实现 FruitList 组件 ：这个组件接收初始水果列表，并使用 SWR 来维护一个可能被搜索或过滤的客户端状态。它负责渲染多个 FruitCard 。

3. 连接行为记录 ：确保每个 FruitCard 都正确绑定了 onClick 和 onMouseEnter 事件，并调用从 Zustand Store 中获取的 logBehavior 方法。

4. 测试交互流程 ：这是最关键的一步。打开浏览器，打开开发者工具的 Network 面板。

   • 刷新页面：观察是否请求了 /api/fruits 和 /api/recommendations 。
   • 鼠标悬停在水果卡片上：观察是否向 /api/behavior 发送了 POST 请求（payload 应为 {“fruitId”: “1”, “action”: “view”, …} ）。
   • 点击不同水果：观察行为日志和推荐接口的调用。推荐结果是否会变化？侧边栏的推荐列表是否会更新？（可能需要手动点击“刷新推荐”按钮，或通过 SWR 的 mutate 在行为记录后自动触发）。

实操心得 ：在开发初期，不要急于美化界面。先用最朴素的样式（甚至只用边框和文字）把整个数据流跑通。确保“行为记录 -> 算法计算 -> 推荐更新”这个核心闭环是 work 的。样式可以最后用 Tailwind 快速美化。这个习惯能帮你快速定位问题是出在逻辑层还是表现层。

4.4 样式优化与部署上线

核心功能完成后，用 Tailwind CSS 快速美化界面。可以参考一些电商网站的卡片设计，添加阴影、圆角、悬停效果。确保移动端适配（Tailwind 的响应式工具非常方便）。

最后，将项目部署到 Vercel，让所有人都能访问你的 Demo。

1. 推送代码到 GitHub ：在项目根目录初始化 git，并关联到 GitHub 仓库。

   git init
   git add .
   git commit -m “initial commit”
   git branch -M main
   git remote add origin <你的仓库URL>
   git push -u origin main
   

2. 在 Vercel 上部署 ：

   • 访问 vercel.com ，用 GitHub 账号登录。
   • 点击 “Add New…” -> “Project”，导入你的 GitHub 仓库。
   • Vercel 会自动检测到是 Next.js 项目，配置保持默认即可。
   • 点击 “Deploy”。几十秒后，你的项目就会有一个 *.vercel.app 的在线地址。

3. 检查线上功能 ：打开部署后的链接，重复本地测试的交互流程。特别注意：

   • API Routes 在服务器端环境是否正常工作？
   • 因为是无服务器函数，注意行为日志的存储。我们 Demo 用的内存变量在 Vercel 的 Serverless 环境下 无法持久化 ，每次请求可能访问到不同的服务器实例。这意味着你的推荐可能看起来不“连续”。要解决这个问题，需要连接一个真实的数据库（如 Vercel Postgres、Supabase、MongoDB Atlas 等）。对于 Demo，你可以注释掉行为记录对推荐的影响，或者使用一个固定的模拟行为序列，专注于展示推荐逻辑本身。

5. 常见问题与排查技巧实录

在实现这个 Demo 的过程中，你几乎一定会遇到下面这些问题。这里记录了我的排查思路和解决方案。

5.1 推荐结果不变化或总是相同

问题现象 ：无论我怎么点击不同的水果，侧边栏的推荐列表始终不变。 排查步骤 ：

1. 检查行为记录是否成功上报 ：打开浏览器开发者工具的“网络(Network)”标签页，筛选 XHR/Fetch 请求。当你与水果卡片交互时，应该能看到对 /api/behavior 的 POST 请求。如果没有，问题出在前端事件绑定或 Zustand Store 的 logBehavior 函数。
2. 检查行为记录 API 是否正常工作 ：点击那个 POST 请求，查看响应状态码。如果是 500，查看服务器终端（运行 npm run dev 的窗口）的错误日志。常见错误是请求体解析问题，确保 route.ts 中使用了 await request.json() 。
3. 检查推荐算法是否接收到行为数据 ：在 app/api/recommendations/route.ts 的 getMockUserBehavior 函数中打印日志，或直接返回一个固定的包含新水果ID的数组，测试推荐结果是否会变。如果会变，说明问题在于 getMockUserBehavior 没有从“存储”中读取到最新的行为日志。
4. Demo 环境下的存储问题 ：这是最常见的原因。在无服务器环境或开发服务器热重载后，内存中的模拟数据（如一个全局数组 userBehaviorLogs ）会被重置。 解决方案 ：对于 Demo，一个简单的方法是放弃“实时根据行为更新推荐”，改为在推荐接口中，根据传入的 userId 返回一个 基于该ID的固定随机序列 。这样至少不同用户（不同ID）看到的推荐是不同的，可以模拟出个性化效果。真正的持久化需要引入数据库。

5.2 页面刷新后推荐侧边栏加载慢或闪烁

问题现象 ：页面加载后，主内容先出现，侧边栏要等一会儿才显示推荐结果，中间有加载态。 分析与解决 ：

• 原因 ：这是因为 RecommendationSidebar 组件在客户端使用 useSWR 获取数据，必然有一个从加载中到完成的阶段。
• 优化方案1（SSR） ：将主页 app/page.tsx 改为异步 Server Component，并在其中获取初始推荐数据，然后通过 props 传递给 RecommendationSidebar 。这样，HTML 中就直接包含了首屏推荐，无闪烁。 RecommendationSidebar 内部仍可使用 useSWR 进行后续的客户端更新。

  // app/page.tsx
  export default async function HomePage() {
    const initialFruits = await getInitialFruits();
    const initialRecs = await getInitialRecommendations('user-123'); // 调用内部函数获取
    return (
      <div>
        <FruitList fruits={initialFruits} />
        <RecommendationSidebar initialRecs={initialRecs} />
      </div>
    );
  }
  

• 优化方案2（Skeleton） ：如果不想用 SSR，设计一个精美的骨架屏（Skeleton）作为加载态，提升用户体验。

5.3 算法效果不理想，推荐不“准”

问题现象 ：感觉推荐的水果和我点击的没什么关系。 调试与调优 ：

1. 检查数据基础 ：水果的 tags 设计是否合理？“甜”这个标签可能出现在80%的水果上，区分度就太低了。尝试增加更具体的标签，如“高纤维”、“需剥皮”、“即食”、“适合榨汁”等。
2. 可视化算法中间结果 ：在 calculateRecommendations 函数中，将 contentBasedScores 和 cfScores 两个 Map 打印出来。看看你点击的水果，到底给其他水果输出了多少分数？是不是分数都集中在某几个标签特别多的水果上？
3. 调整算法权重 ： contentWeight 和 cfWeight 的默认比例是 7:3。尝试极端情况，比如设为 1:0（纯内容推荐）和 0:1（纯协同过滤），观察结果如何变化。理解每种算法的倾向性。
4. 引入随机性 ：在最终推荐列表的末尾，混入一两个随机的水果。这被称为“探索与利用”的平衡，可以避免推荐系统陷入信息茧房，在 Demo 中也能让结果看起来更多样。
5. 实现简单的“去重”和“已读过滤” ：确保推荐列表中不会出现用户刚刚点击过的水果，并且当前主列表正在展示的水果也最好能过滤掉。

5.4 部署到 Vercel 后 API 返回 404 或 500 错误

问题排查 ：

1. 检查构建日志 ：在 Vercel 项目的部署详情页，查看构建日志是否有错误。Next.js 的 API Routes 在构建时一般没问题，但如果有 TypeScript 错误可能会失败。
2. 检查路由文件位置和命名 ：确保你的 API Route 文件路径是 app/api/[endpoint]/route.ts ，并且使用标准的 GET , POST 等函数导出。 app/router 的规则与 pages/api 不同。
3. 检查环境变量和敏感信息 ：如果你的代码中硬连接了本地数据库地址，在 Vercel 上肯定会失败。所有环境相关的配置（如数据库连接字符串）都应使用 Vercel 的环境变量功能设置。
4. 查看运行时日志 ：Vercel 提供了函数运行时日志。在项目控制台的“函数(Functions)”标签页下，找到出错的 API 端点，查看具体的错误信息，这通常是解决问题的关键。

5.5 性能与扩展性思考（虽然只是 Demo）

即使是一个 Demo，思考如何扩展也能加深理解：

• 算法优化 ：当水果数量增加到几百上千时，每次推荐都遍历全量计算相似度效率低下。可以考虑预先计算好水果之间的相似度矩阵并缓存。
• 行为日志处理 ：用户行为上报应该是异步、非阻塞的，并且要能应对网络失败。前端可以采用队列+重试机制，或者使用像 navigator.sendBeacon 这样的 API 在页面卸载时也能可靠发送。
• 数据库选择 ：如果真要持久化，对于这类读写频繁但结构相对简单的行为日志，文档型数据库（如 MongoDB）或时序数据库可能比传统关系型数据库更合适。Vercel 集成的 Vercel Postgres 也是一个极佳的选择。

这个项目麻雀虽小，五脏俱全。它串联起了现代前端开发的全栈技能点：从 React 组件交互、状态管理，到 Next.js 的 API 路由、服务端渲染，再到基础算法实现和简单的系统设计。完成它，你收获的不仅仅是一个 Demo，更是一套解决一类问题的完整方法论。