React 18 + TypeScript + Vite 构建B2B AI产品战略官网全栈实践-平芜编程栈

1. 项目概述：一个面向B2B初创公司的AI产品战略官网

最近帮一个做AI产品战略咨询的朋友，把他的个人服务品牌“WANDERCODE”的官网给搭起来了。这哥们儿是个典型的“结果交付者”，专门服务那些有技术想法但缺产品落地经验的B2B初创公司，提供的不是按小时计费的顾问服务，而是一种叫“RaaS”（Results as a Service）的模式，简单说就是按最终交付的成果来收费。官网的核心任务很明确：清晰传达这种独特的价值定位，展示专业的服务矩阵，并最终高效地将访客转化为预约咨询的客户。

整个项目基于现代前端技术栈：React 18 + TypeScript 打底，用Vite和SWC追求极致的构建速度，UI层面则选择了Tailwind CSS搭配高度定制化的shadcn/ui组件库。部署在Vercel上，实现了Git推送即自动发布的丝滑流程。这个项目虽然从代码量上看不算庞大，但麻雀虽小五脏俱全，涉及从技术选型、用户体验设计到业务逻辑转化的完整链条，特别适合那些想为自己或小型工作室打造一个专业、高效且易于维护的展示型网站的开发者参考。无论你是独立开发者、自由职业者，还是小型团队的技术负责人，都能从中找到可以直接复用的思路和代码片段。

2. 技术栈选型与架构设计思路

2.1 为什么是React 18 + TypeScript + Vite？

在启动任何前端项目时，技术选型是地基。对于WANDERCODE这样一个内容相对稳定但交互和状态管理需要足够灵活的宣传官网，我选择了React 18 + TypeScript + Vite的组合，这是经过深思熟虑的。

首先，React 18的并发特性（Concurrent Features）如useTransition，虽然在这个内容型网站上可能不会用到其最复杂的部分，但它代表了框架的先进性和未来的兼容性。更重要的是，React庞大的生态和社区支持，意味着任何UI交互需求（如复杂的表单、动画过渡）都能找到成熟的解决方案或思路。TypeScript的加入则是为了项目的长期可维护性。即使项目初期只有一个人开发，明确的类型定义也能极大地减少因参数传递错误、API响应结构变更带来的运行时Bug。对于展示公司专业形象的官网来说，线上无类型的JavaScript错误是绝对要避免的。

构建工具选择Vite而非传统的Create React App，核心诉求是开发体验和构建速度。Vite基于ES模块的原生支持，在开发服务器启动和热更新（HMR）速度上具有碾压性优势。这意味着在调整样式或修改组件时，几乎能实现毫秒级的反馈，这对前端开发效率的提升是巨大的。同时，Vite在生产构建时使用Rollup，能生成优化程度很高的静态资源。配合SWC（Speedy Web Compiler）—— 一个用Rust编写的高性能编译器，来替代Babel进行TypeScript/JSX的转译，整个工具链的速度达到了极致。对于需要频繁微调、追求完美像素的官网项目，快速的反馈循环至关重要。

注意：Vite的配置虽然开箱即用，但如果你需要兼容非常旧的浏览器（如IE11），需要额外关注@vitejs/plugin-legacy等插件的配置。好在WANDERCODE的目标客户（B2B初创公司决策者）使用的都是现代浏览器，我们可以毫无负担地使用现代JavaScript特性。

2.2 样式方案：Tailwind CSS与shadcn/ui的化学反应

样式方案上，我放弃了传统的CSS-in-JS（如styled-components）或纯SCSS，而采用了Tailwind CSS。原因在于官网项目通常包含大量的一次性、高度定制化的样式组件，如独特的按钮、卡片、间距调整等。Tailwind的实用类（Utility-First）范式允许我在JSX中直接组合类名来完成样式，避免了在CSS文件和组件文件之间反复跳转，也省去了为每个微小样式命名的烦恼（比如.card-inner-shadow这种）。它的响应式设计前缀（如md:,lg:）也让构建自适应布局变得异常直观。

然而，纯Tailwind在构建复杂的、可复用的交互组件（如模态框、下拉菜单、表单）时，会显得有些冗长和重复。这就是shadcn/ui登场的原因。shadcn/ui不是一个传统的npm组件库，而是一套基于Tailwind和Radix UI的可复制粘贴的组件源代码。你可以通过一条命令（npx shadcn-ui@latest add button）将某个组件（如Button）的完整、类型安全的React代码直接添加到你的项目中。这意味着你拥有组件的全部所有权，可以对其进行任何程度的定制，同时它又提供了精心设计、无障碍（a11y）友好的交互逻辑基础。

这种组合带来了巨大优势：我们用Tailwind快速构建布局和基础样式，用shadcn/ui提供高质量的交互组件基石，再根据品牌设计进行深度定制。最终得到的是一套完全属于项目、零运行时开销、且与设计系统完美契合的组件库。例如，官网中的“Book a Call”按钮，就是在shadcn/ui的Button组件基础上，覆写了背景色、圆角、悬停效果，并集成了Cal.com的预约链接。

2.3 包管理器与部署策略：追求极致的开发体验

包管理器选择了bun。在Node.js生态中，npm、yarn、pnpm之争已久，bun作为一个后来者，其最大的卖点是速度。它不仅仅是一个包管理器，还是一个JavaScript运行时、打包器和测试运行器。在WANDERCODE项目中，我们主要利用其作为包管理器的能力。bun install的速度极快，这对于需要频繁初始化项目或在新环境中搭建的开发者来说体验提升明显。同时，在package.json的scripts中，使用bun run执行命令也比传统的npm更快。

部署毫无悬念地选择了Vercel。对于React/Vite构建的静态网站，Vercel提供了最无缝的体验。只需将Git仓库与之连接，任何推送到main分支的更改都会自动触发构建和部署。Vercel能自动识别出这是基于Vite的React项目，配置好构建命令（bun run build）和输出目录（dist）。更重要的是，它提供了全球CDN、自动SSL证书、预览环境等企业级功能，而这些对于个人或小团队项目几乎是免费的。这种“Git Push即上线”的流程，极大地简化了发布流程，让开发者可以专注于代码本身。

3. 核心页面结构与用户体验设计解析

3.1 信息架构与用户流设计

一个有效的官网，其页面结构必须服务于核心商业目标。WANDERCODE的目标是吸引B2B初创公司，展示专业能力，并引导他们预约咨询。因此，我们摒弃了复杂多层级的导航，采用了极其扁平和直接的信息架构。

核心页面只有四个：

首页：价值主张的“第一眼”。必须在3秒内让访客明白“你是谁”、“能解决我什么问题”、“为什么是你”。
服务页面：详细阐述“你怎么做”。将抽象的“AI产品战略”拆解为具体、可感知的服务模块。
关于页面：建立信任与共鸣。回答“你是谁”、“凭什么值得信赖”、“你的理念是什么”。
联系页面：转化漏斗的终点。提供最简单、最清晰的行动路径。

用户流的设计遵循“渐进式披露”和“多入口转化”原则。从首页开始，用户可以通过明显的“Our Services”按钮进入服务总览页，也可以直接通过导航栏访问。在服务页面，每个服务卡片都配有“Learn More”和“Get in Touch”的选项，满足不同决策阶段用户的需求。最重要的是，在每一个页面的醒目位置（通常是顶部导航栏和页面底部），都放置了同一个核心行动号召按钮：“Book a Discovery Call”。这确保了无论用户浏览到哪个环节，只要产生了兴趣，下一步动作就在手边，转化路径被缩短到极致。

3.2 首页：价值主张的黄金三秒

首页的设计是成败的关键。我们采用了经典的“英雄区域”布局，但内容上高度聚焦。

大标题与副标题：直接点明“Fractional AI Product Strategy for B2B Startups”，副标题则用一句话解释RaaS模式的核心：“We deliver results, not bills.” 避免使用“赋能”、“颠覆”等空洞词汇，直击客户痛点——害怕无底洞式的顾问工时费。
服务预览：在首屏下方，以三个简洁的图标卡片形式，预览“咨询”、“开发”、“培训”三大服务，并配有“View All Services”的链接。这既展示了业务广度，又不会在首页造成信息过载。
信任信号：在服务预览下方，设计了一个“信任专区”。这里可以放置客户Logo（如有）、简短的成功案例引述、或合作伙伴标识。对于新品牌，我们选择放置了“Expertise in:”标签，列出如“LLM”、“RAG”、“Product-Market Fit”等关键词，快速建立专业认知。

技术实现上，我们使用Tailwind的Flexbox和Grid系统实现响应式布局，确保在手机和桌面端都有良好表现。Hero区域的背景使用了一个非常 subtle 的渐变，并配合微妙的入场动画（使用Framer Motion或类似的库），在页面加载时让标题和按钮有一个淡入和轻微上浮的效果，吸引视觉焦点，但绝不花哨，以免分散对核心信息的注意力。

3.3 服务页面：将抽象能力转化为具体方案

服务页面是说服力的核心。很多技术型顾问容易犯的错误是罗列技术栈（“我会Python, GPT, RAG”），但这回答不了客户“这对我有什么用”的问题。我们的设计思路是“以客户为中心的场景化描述”。

我们将服务分为三大块：

战略咨询：描述为“从想法到清晰路线图”。内容聚焦于帮助客户定义问题、规划产品MVP、进行技术选型评估。我们避免说“提供咨询”，而是说“交付一个包含优先级排序、技术风险评估和6个月执行计划的详细战略文档”。
AI开发与集成：描述为“构建与交付可工作的AI功能”。这里可以适当展示技术深度，例如提到“使用LangChain构建RAG系统”、“为内部工作流集成Claude或GPT API”、“开发定制化微调模型”。但重点始终落在“交付可集成、可扩展的代码库和API”这个结果上。
团队培训与工作坊：描述为“提升团队的AI实战能力”。针对客户团队，提供关于Prompt工程、AI产品设计、LLM应用开发最佳实践的实战培训。强调成果是“团队能独立进行基础的AI原型开发”。

每个服务板块都采用统一的视觉结构：一个醒目的图标/图示、一个直击痛点的标题、一段场景化的描述、3-4个具体的交付物清单（如“1个经过验证的RAG架构设计”、“3场团队实战编程Session”），最后是明确的行动按钮。这种结构清晰、信息密度高，能让潜在客户迅速对号入座，评估这项服务是否匹配自己的需求。

3.4 关于与联系页面：建立信任与简化转化

关于页面的核心是讲好“人的故事”和“公司的理念”。布局上分为两大部分：

个人/团队介绍：用一段有温度的文字介绍背景，例如“前XX公司AI产品负责人，主导过从0到1的XX项目，深知在资源有限的情况下将AI想法落地的挑战”。配合一个专业但不失亲切的照片。
“为什么选择Fractional模式？”：这是一个非常重要的说服环节。我们用对比列表或信息图的形式，清晰对比“雇佣全职首席AI官”、“聘请传统按小时计费的咨询公司”和“我们的RaaS模式”在成本、灵活性、结果绑定度等方面的差异。这直接回应了潜在客户的预算和风险顾虑。

联系页面则要做到极致的简洁和高效。页面上只有三个核心元素：

预约日历嵌入：使用Cal.com或类似工具的iframe嵌入。访客可以直接查看可预约的时间段并完成预约，无需来回发邮件确认时间。这是转化率最高的设计。我们将其放在最显眼的位置。
备用联系信息：提供一个公司邮箱（如 hello@wandercode.ltd）和LinkedIn个人主页链接。这是为了满足那些喜欢先进行非正式沟通的用户的习惯。
公司法定信息：在页脚清晰展示公司名称（WANDERCODE LIMITED）和注册地（香港）。这增加了业务的正式感和可信度。

实操心得：在集成Cal.com这类第三方预约工具时，务必在其后台设置好“问题表单”，在用户预约时自动收集公司名称、关注领域等基本信息。这能让咨询电话开始前，你就对客户有个初步了解，极大提升沟通效率。同时，记得自定义预约确认邮件的模板，加入公司的品牌元素和通话前的准备建议，显得非常专业。

4. 开发环境搭建与核心脚本详解

4.1 从零开始初始化项目

让我们一步步拆解如何从零复现这个开发环境。首先，确保你的系统已经安装了Node.js（建议LTS版本）和bun。

# 1. 使用Vite官方模板创建React + TypeScript项目 # 这里我们直接用bun创建，速度更快 bun create vite wandercode-portfolio --template react-ts # 2. 进入项目目录 cd wandercode-portfolio # 3. 初始化git仓库（可选，但推荐） git init # 4. 安装Vite React项目的基础依赖（bun install会读取package.json自动安装） bun install

接下来，安装项目核心的样式和UI库：

# 5. 安装Tailwind CSS及其相关依赖 bun add -D tailwindcss postcss autoprefixer bunx tailwindcss init -p # 生成tailwind.config.js和postcss.config.js # 6. 配置Tailwind。编辑tailwind.config.js，添加内容路径 /** @type {import('tailwindcss').Config} */ export default { content: [ "./index.html", "./src/**/*.{js,ts,jsx,tsx}", ], theme: { extend: {}, }, plugins: [], } # 7. 在src/index.css中引入Tailwind指令 @tailwind base; @tailwind components; @tailwind utilities; # 8. 初始化shadcn/ui。首先安装其CLI工具 bun add -D shadcn-ui@latest # 运行初始化命令，按照提示选择配置（样式选择“Default”，颜色选择“Slate”等） bunx shadcn-ui@latest init # 初始化完成后，就可以添加组件了，例如添加一个按钮 bunx shadcn-ui@latest add button

4.2 关键配置文件解析

项目中有几个配置文件对开发体验影响巨大：

vite.config.ts：这是Vite的核心。我们通过plugins数组可以集成各种功能。一个基础的配置如下：

import { defineConfig } from 'vite' import react from '@vitejs/plugin-react-swc' // 使用SWC插件，更快 import path from 'path' export default defineConfig({ plugins: [react()], resolve: { alias: { '@': path.resolve(__dirname, './src'), // 设置路径别名，方便导入 }, }, server: { port: 8080, // 指定开发服务器端口 open: true, // 启动后自动打开浏览器 }, })

使用@vitejs/plugin-react-swc替代默认的@vitejs/plugin-react可以启用SWC进行转译，获得更快的热更新。

tsconfig.json：TypeScript配置。关键是要配置好paths，与Vite的alias对应。
```
{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] }, // ... 其他配置 } }
```
这样在代码中就可以使用import Button from '@/components/ui/button'这样的清晰路径。

package.json中的 scripts：这是开发工作流的枢纽。WANDERCODE项目定义了一套高效的脚本：

{ "scripts": { "dev": "vite", // 启动开发服务器 "build": "tsc && vite build", // 先做类型检查，再构建 "preview": "vite preview", // 本地预览生产构建 "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0", // 严格的代码检查 "typecheck": "tsc --noEmit", // 仅进行类型检查，不输出文件 "check": "bun run typecheck && bun run lint" // 组合命令，在提交代码前运行 } }

check命令非常实用，可以配置为Git的pre-commit钩子（使用husky工具），确保提交到仓库的代码没有类型错误和明显的代码风格问题。

4.3 开发、构建与质量保障流程

日常开发只需一个命令：bun dev。Vite会启动一个开发服务器，通常运行在http://localhost:8080。得益于Vite的基于ESM的HMR，你对组件、样式所做的修改几乎会实时反映在浏览器中，无需手动刷新。

当你完成一个功能或准备发布时，运行bun run build。这个命令会先执行tsc --noEmit（在scripts中已集成），确保没有TypeScript错误，然后启动Vite的生产构建流程。Vite会对代码进行树摇、压缩、分块，并将资源文件名哈希化（用于缓存破坏），最终输出到dist目录。你可以通过bun run preview命令，启动一个本地静态文件服务器来预览构建结果，模拟生产环境。

代码质量保障是专业项目的基石。我们配置了ESLint（通常由Vite模板预置）来强制执行代码规范。bun run lint命令会扫描所有.ts和.tsx文件。建议在IDE中安装ESLint插件，这样在编码时就能实时看到错误和警告。bun run typecheck是TypeScript的纯类型检查，它比Vite开发服务器中的类型检查更全面、更严格。将bun run check（即类型检查+代码检查）作为CI/CD流水线中的一个必过环节，能有效阻止有问题的代码进入生产环境。

避坑指南：有时，Vite的开发服务器（bun dev）运行正常，但生产构建（bun run build）却失败了。常见原因包括：
动态导入路径错误：在生产构建时，所有模块路径必须是静态可分析的。避免使用字符串拼接的动态导入。
未处理的类型错误：开发时TypeScript错误可能被忽略，但tsc命令会严格报错。确保在开发阶段就解决所有类型问题。
环境变量使用不当：确保生产环境变量正确配置，并且以VITE_开头的变量才能在客户端代码中通过import.meta.env访问。遇到构建失败，首先查看终端的错误信息，通常Vite会给出非常清晰的错误定位。

5. 核心组件实现与交互细节

5.1 导航栏与响应式菜单

导航栏是网站的门面，需要同时在桌面和移动端提供优秀的体验。我们使用一个固定在顶部的导航栏，背景采用轻微的半透明毛玻璃效果，增强现代感。

桌面端导航很简单，使用Flex布局将Logo、导航链接（Home, Services, About, Contact）和核心的“Book a Call”按钮水平排列。关键点是“Book a Call”按钮的样式要与其他链接有显著区别，通常使用更饱满的背景色和更强烈的召唤性文案。

移动端导航的实现稍复杂。我们使用一个汉堡菜单图标（通常用svg实现），点击后展开一个从顶部或侧面滑出的全屏或下拉菜单。这个交互可以使用纯CSS（:checked伪类 +transform）实现，但为了更好的动画控制和状态管理，我们选择使用React状态和一个简单的动画库（如framer-motion或@headlessui/react的Transition组件）。

// 简化示例：使用状态控制移动菜单 import { useState } from 'react'; import { Menu, X } from 'lucide-react'; // 引入图标库 const Navbar = () => { const [isMenuOpen, setIsMenuOpen] = useState(false); return ( <nav className="fixed top-0 w-full bg-white/80 backdrop-blur-sm z-50"> <div className="container mx-auto px-4 py-3 flex justify-between items-center"> {/* Logo */} <div>WANDERCODE</div> {/* Desktop Navigation - hidden on mobile */} <div className="hidden md:flex items-center space-x-8"> <a href="/services">Services</a> <a href="/about">About</a> <a href="/contact">Contact</a> <Button asChild> <a href="https://cal.com/wandercode/call">Book a Call</a> </Button> </div> {/* Mobile Menu Button */} <button className="md:hidden" onClick={() => setIsMenuOpen(!isMenuOpen)} > {isMenuOpen ? <X size={24} /> : <Menu size={24} />} </button> </div> {/* Mobile Menu Overlay */} {isMenuOpen && ( <div className="md:hidden absolute top-full left-0 w-full bg-white border-t shadow-lg"> <div className="flex flex-col p-4 space-y-4"> <a href="/services" onClick={() => setIsMenuOpen(false)}>Services</a> <a href="/about" onClick={() => setIsMenuOpen(false)}>About</a> <a href="/contact" onClick={() => setIsMenuOpen(false)}>Contact</a> <Button className="w-full" asChild> <a href="https://cal.com/wandercode/call" onClick={() => setIsMenuOpen(false)}>Book a Call</a> </Button> </div> </div> )} </nav> ); };

5.2 服务卡片的交互与数据驱动

服务页面上的卡片组件需要展示一致的信息结构，同时可能有悬停效果等交互。最好的实践是将卡片设计为纯展示型组件，通过Props接收数据。

首先，定义一个TypeScript接口来描述一项服务的数据结构：

// types/service.ts export interface ServiceItem { id: string; icon: React.ReactNode; // 可以是Lucide React图标组件 title: string; shortDescription: string; fullDescription: string; deliverables: string[]; // 交付物列表 ctaText: string; ctaLink: string; }

然后，创建一个ServiceCard组件：

// components/ServiceCard.tsx import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@/components/ui/card'; import { Button } from '@/components/ui/button'; import { ServiceItem } from '@/types/service'; import { ArrowRight } from 'lucide-react'; interface ServiceCardProps { service: ServiceItem; } const ServiceCard: React.FC<ServiceCardProps> = ({ service }) => { return ( <Card className="group hover:shadow-xl transition-all duration-300 hover:-translate-y-1"> <CardHeader> <div className="mb-4 p-3 bg-primary/10 w-fit rounded-lg"> {service.icon} </div> <CardTitle className="text-2xl">{service.title}</CardTitle> <CardDescription className="text-lg mt-2"> {service.shortDescription} </CardDescription> </CardHeader> <CardContent> <ul className="space-y-2"> {service.deliverables.map((item, index) => ( <li key={index} className="flex items-start"> <ArrowRight className="h-5 w-5 text-primary mr-2 mt-0.5 flex-shrink-0" /> <span>{item}</span> </li> ))} </ul> </CardContent> <CardFooter className="flex flex-col sm:flex-row gap-3"> <Button asChild variant="outline" className="w-full sm:w-auto"> <a href={`/services/${service.id}`}>Learn More</a> </Button> <Button asChild className="w-full sm:w-auto"> <a href={service.ctaLink}>{service.ctaText}</a> </Button> </CardFooter> </Card> ); };

最后，在服务页面，我们可以从一个数据文件中导入服务列表，并使用map函数渲染：

// pages/ServicesPage.tsx import ServiceCard from '@/components/ServiceCard'; import { servicesData } from '@/data/services'; // 假设这里导出了一个ServiceItem数组 const ServicesPage = () => { return ( <div className="container mx-auto px-4 py-16"> <h1 className="text-4xl font-bold text-center mb-12">Our Services</h1> <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8"> {servicesData.map((service) => ( <ServiceCard key={service.id} service={service} /> ))} </div> </div> ); };

这种数据驱动的方式使得维护和更新服务内容变得非常简单，只需修改servicesData数组即可，完全不需要改动组件代码。

5.3 集成第三方工具：以Cal.com为例

将预约系统无缝集成到网站中是提升转化率的关键。Cal.com提供了非常友好的嵌入方式。

在Cal.com上创建事件类型：登录Cal.com，创建一个新的“Discovery Call”事件类型，设置好时长（如30分钟）、可用时间段、提前通知时间等。
获取嵌入代码：在事件类型的设置中，找到“Embed”选项。Cal.com提供了多种嵌入方式：弹出窗口、浮动按钮、行内嵌入等。对于联系页面，我们选择“Inline Embed”，因为它能提供最无缝的体验，用户无需离开当前页面。
在React组件中嵌入：Cal.com会生成一段脚本代码和一个div容器。在React中，我们通常使用useEffect来动态加载第三方脚本，并确保组件卸载时清理。

// components/CalEmbed.tsx import { useEffect } from 'react'; const CalEmbed = () => { useEffect(() => { // 动态加载Cal.com的脚本 const script = document.createElement('script'); script.src = 'https://app.cal.com/embed/embed.js'; script.async = true; document.body.appendChild(script); // 组件卸载时清理脚本（可选，但保持整洁） return () => { document.body.removeChild(script); }; }, []); // 空依赖数组，只在组件挂载时执行一次 return ( <div className="my-8"> {/* Cal.com 生成的占位div，其id必须与脚本配置匹配 */} <div className="cal-embed" ><img src="/team-photo.jpg" alt="Our Team" loading="lazy" />

使用Vite的资产处理：Vite开箱即用地支持将小于某个阈值的图片转换为Base64内联，减少HTTP请求。对于更大的图片，它会生成带有哈希文件名的版本，并可以利用CDN长期缓存。只需将图片放在src/assets目录下，然后通过ES模块导入即可获得优化后的路径。

import logo from '@/assets/logo.svg'; <img src={logo} alt="Wandercode Logo" />

6.2 代码分割与按需加载

即使项目不大，良好的代码分割习惯也能提升初始加载速度。Vite和React Router结合，可以轻松实现基于路由的代码分割。

假设我们使用React Router DOM v6：

// main.tsx 或 App.tsx import { createBrowserRouter, RouterProvider } from 'react-router-dom'; import { lazy, Suspense } from 'react'; import HomePage from './pages/HomePage'; import LoadingSpinner from './components/LoadingSpinner'; // 使用lazy动态导入非首屏页面 const ServicesPage = lazy(() => import('./pages/ServicesPage')); const AboutPage = lazy(() => import('./pages/AboutPage')); const ContactPage = lazy(() => import('./pages/ContactPage')); const router = createBrowserRouter([ { path: '/', element: <HomePage />, }, { path: '/services', element: ( <Suspense fallback={<LoadingSpinner />}> <ServicesPage /> </Suspense> ), }, { path: '/about', element: ( <Suspense fallback={<LoadingSpinner />}> <AboutPage /> </Suspense> ), }, { path: '/contact', element: ( <Suspense fallback={<LoadingSpinner />}> <ContactPage /> </Suspense> ), }, ]); function App() { return <RouterProvider router={router} />; }

这样，当用户访问首页时，只会加载HomePage的代码。只有当用户点击导航跳转到/services时，才会开始加载ServicesPage的代码包。Suspense组件提供了一个加载中的回退界面（如一个旋转的加载器），保证了用户体验的连贯性。

6.3 部署到Vercel的完整流程

代码推送至Git仓库：确保所有代码已提交并推送至GitHub、GitLab或Bitbucket仓库。
登录Vercel：访问 vercel.com ，使用GitHub等账户登录。
导入项目：在Dashboard点击“Add New...” -> “Project”，从列表中选择你的代码仓库。
配置项目：Vercel会自动检测到这是一个Vite项目，并预设好构建命令（bun run build）和输出目录（dist）。通常你不需要修改任何配置。但可以在这里设置环境变量（如果项目需要）。
部署：点击“Deploy”。Vercel会开始拉取代码、安装依赖、执行构建命令，并将生成的dist目录内容部署到其全球CDN上。
自定义域名：部署完成后，Vercel会分配一个*.vercel.app的临时域名。你可以在项目设置的“Domains”部分添加自己的自定义域名（如wandercode.ltd）。按照指引去你的域名注册商那里添加Vercel提供的CNAME记录即可。
自动化：至此，自动化流程已建立。以后任何推送到你所选分支（通常是main）的代码，都会自动触发一次新的部署。Vercel还会为每个Pull Request生成一个独立的预览URL，方便团队在合并前进行测试。

生产环境检查清单：在部署前，请务必进行以下检查：
[ ] 运行bun run build本地构建成功，无错误或警告。
[ ] 运行bun run preview本地预览，检查所有功能是否正常（链接、表单、嵌入内容等）。
[ ] 使用浏览器开发者工具的“灯塔”或PageSpeed Insights进行性能测试，确保核心Web指标（LCP, FID, CLS）达标。
[ ] 检查所有链接，确保没有404错误。
[ ] 在移动设备和不同尺寸的桌面浏览器上进行响应式测试。
[ ] 确认所有环境变量（如分析工具ID、API密钥）已在Vercel项目设置中正确配置，且未将敏感信息硬编码在客户端代码中。

7. 常见问题排查与维护技巧

7.1 开发服务器常见问题

问题：bun dev启动后，页面空白或报错“Failed to resolve import”。
- 排查：这通常是因为路径别名（@/）配置不正确，或者依赖包未正确安装。
- 解决：
  1. 检查vite.config.ts和tsconfig.json中的alias/paths配置是否一致且指向正确的src目录。
  2. 删除node_modules文件夹和bun.lockb文件，重新运行bun install。
  3. 检查导入语句的拼写和大小写是否正确（Linux/macOS系统是大小写敏感的）。
问题：热更新不工作，每次修改都需要手动刷新。
- 排查：可能是某些文件扩展名不被Vite的HMR监听，或者是防病毒软件/文件系统监视器的问题。
- 解决：
  1. 确保文件在vite.config.ts的server.watch配置内（通常默认包含）。
  2. 尝试在Vite配置中增加server.watch.usePolling: true，这在某些网络文件系统或Docker环境中可能有效。
  3. 临时关闭防病毒软件的文件实时监控功能试试。

7.2 样式与Tailwind相关

问题：修改了Tailwind类名，但样式没有生效。
- 排查：Tailwind是基于内容文件生成CSS的。如果新添加的类名所在的文件路径没有被tailwind.config.js中的content数组包含，则不会生成对应的CSS。
- 解决：检查tailwind.config.js文件，确保content数组包含了你的所有模板文件路径，例如：./src/**/*.{js,ts,jsx,tsx}。如果添加了新的文件目录（如./components/**/*.tsx），需要将其加入。
问题：shadcn/ui组件样式被覆盖或不起作用。
- 排查：CSS特异性冲突，或者Tailwind的base样式重置了某些属性。
- 解决：
  1. 检查浏览器开发者工具，查看目标元素上应用的最终样式，以及哪些样式被划掉了。这能帮你定位冲突来源。
  2. shadcn/ui组件的样式通常有较高的特异性。如果必须覆盖，可以使用更具体的选择器，或者在Tailwind类前加上!important（如!text-red-500），但这应是最后的手段。
  3. 确保你的自定义CSS没有在@tailwind base之后错误地重置了边框、背景等属性。

7.3 构建与部署问题

问题：本地bun run build成功，但Vercel部署失败。
- 排查：最常见的原因是环境差异。Vercel的构建环境可能使用了不同的Node.js版本，或者某些依赖需要原生编译（node-gyp）。
- 解决：
  1. 在项目根目录创建.vercelrc或vercel.json，指定构建命令和Node版本。
```
{ "buildCommand": "bun run build", "devCommand": "bun dev", "installCommand": "bun install", "framework": "vite" }
```
  2. 在package.json中指定engines字段，锁定Node和bun版本。
```
"engines": { "node": ">=18", "bun": ">=1.0" }
```
  3. 查看Vercel部署日志（在项目控制台的“Deployments”标签页），错误信息通常非常详细，会直接指出是哪个依赖或哪行代码出了问题。
问题：网站部署后，部分资源（图片、字体）加载404。
- 排查：资源路径错误。在开发环境使用绝对路径（如/src/assets/logo.svg）可能可行，但在生产环境，资源路径是相对于部署根目录的。
- 解决：
  1. 绝对最佳实践：使用ES模块导入资源，让Vite处理路径。如import logo from '@/assets/logo.svg'，然后在src属性中使用logo变量。
  2. 如果必须使用公共文件夹（public），请使用绝对路径/logo.svg（以/开头），Vite在构建时会将其复制到输出根目录。避免使用相对路径。

7.4 内容更新与SEO基础维护

对于一个展示型官网，内容的定期更新和基础的SEO设置很重要。

更新内容：由于我们采用了数据驱动的方式（如将服务列表放在src/data/services.ts中），更新内容只需修改对应的数据文件，然后推送代码即可。Vercel的自动部署会让更新在几分钟内上线。

基础SEO：在每个页面组件中，使用React Helmet（或Vite更推荐的react-helmet-async）来动态设置<title>和<meta name="description">标签。这对于搜索引擎和社交媒体分享预览至关重要。

// 在页面组件中 import { Helmet } from 'react-helmet-async'; const ServicesPage = () => { return ( <> <Helmet> <title>AI Product Strategy Services | WANDERCODE</title> <meta name="description" content="Fractional AI product strategy, development, and training services for B2B startups. Get results, not bills." /> </Helmet> {/* 页面内容 */} </> ); };

性能监控：在Vercel项目中，可以集成像Speed Insights这样的工具，它会定期测试你的网站性能并给出报告。也可以考虑添加简单的分析工具如Plausible或Umami，以匿名方式了解访客行为，而不侵犯隐私。

这个项目从技术选型到部署上线的全过程，体现了一种务实、高效的现代前端开发哲学：用最合适的工具解决具体问题，注重开发体验和最终性能，并且让维护变得简单。无论是用于个人品牌展示，还是小型商业服务，这套架构和思路都具有很强的可复制性和扩展性。在实际操作中，最大的体会是“约定大于配置”——合理利用像Vite、Tailwind、shadcn/ui这样有强约定的工具链，能让你从繁琐的配置中解放出来，更专注于业务逻辑和用户体验本身。