Vite+React+TypeScript构建个人作品集网站：从技术选型到GitHub Pages自动化部署

1. 项目概述：一个现代开发者如何构建自己的技术名片

最近刚把自己的个人作品集网站重构上线，地址是https://yucco-k.github.io。这不仅仅是一个展示作品的静态页面，更是一个我用来实践和整合现代前端技术栈的“游乐场”。对于开发者而言，个人网站就是一张动态的技术名片，它不仅要好看、好用，其背后的技术选型、工程化实践和部署流程，往往更能体现你的技术品味和工程能力。这次重构，我抛弃了传统的 Create-React-App 脚手架，拥抱了以Vite、TypeScript和React 19为核心的现代开发体验，并接入了GitHub Actions实现自动化部署到GitHub Pages。整个过程踩了不少坑，也积累了一些让开发流程更顺滑的心得，这篇文章就来详细拆解一下这个项目的构建思路、技术细节和那些文档里不会写的实操经验。

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

2.1 为什么是 Vite + React + TypeScript 这个组合？

在项目启动前，我对比了多个方案。传统的 CRA（Create-React-App）虽然稳定，但其基于 Webpack 的构建速度在项目稍大时就会成为开发体验的瓶颈，尤其是热更新（HMR）的反馈延迟，非常影响编码的心流。Vite的出现彻底改变了这一点。它利用原生 ES 模块，在开发阶段实现了秒级启动和毫秒级热更新，这种“所见即所得”的流畅感对提升开发效率至关重要。对于个人项目这种需要快速迭代和验证想法的场景，Vite 是毋庸置疑的首选。

React 19带来了许多前瞻性的优化，比如对并发特性的更好支持。虽然当前项目没有用到特别复杂的并发场景，但基于新版本构建能确保技术栈的长期可维护性，避免未来升级的阵痛。TypeScript则是大型项目（即使这个“大型”是相对的）的基石。它为组件属性、函数参数、API 响应等提供了严格的类型约束，将大量运行时错误提前到编译时暴露。在搭配 VSCode 或 Cursor 这类智能编辑器时，类型提示和自动补全能极大提升编码效率和准确性。这个组合构成了一个高性能、高可靠性的开发基础。

2.2 UI 与动画库：追求视觉表现与开发效率的平衡

视觉表现是作品集的门面。我选择了Styled-Components作为 CSS-in-JS 方案。相比于传统的 CSS 模块，它的优势在于能够将样式与组件逻辑深度绑定，支持基于props的动态样式，并且天然解决了样式隔离和命名冲突的问题。在需要创建主题切换等动态功能时，Styled-Components 的ThemeProvider用起来非常顺手。

对于动画，Framer Motion是 React 生态中目前最强大的动画库之一。它声明式的 API 设计让复杂的序列动画和手势交互变得非常简单。例如，实现一个元素在进入视口时从淡入到滑入的动画，只需要几行代码，而无需手动操作 CSS@keyframes或setTimeout。它的学习曲线平缓，但能力上限很高，足以应对作品集中常见的展示性动画需求。

最激进的选择可能是引入了@react-three/fiber和@react-three/drei。这是一个基于 Three.js 的 React 渲染器，允许你用声明式的 React 组件来编写 3D 场景。我在网站中尝试加入了一个简单的 3D 模型或粒子背景作为视觉亮点。虽然这增加了包体积，但对于一个旨在展示技术广度的作品集来说，适度地展示对 WebGL 和 3D 图形的理解是值得的。需要注意的是，要利用代码分割（React.lazy）来异步加载这个 3D 组件，避免影响首屏加载速度。

2.3 开发工具链：用自动化解放生产力

开发体验的另一个重要部分是工具链。ESLint配合 Airbnb 或 Standard 的规则集，能强制保持代码风格一致，避免一些低级错误。Prettier则负责自动格式化，让团队协作（或者未来的自己）无需在代码风格上争论。

我特别引入了Playwright进行端到端（E2E）测试。对于作品集网站，关键的用户流并不多，比如“导航到作品详情页”、“切换主题”、“表单提交（如果有）”。为这些核心路径编写 E2E 测试，能确保每次重构或添加新功能后，基本用户体验不会崩溃。Playwright 相比 Cypress 或 Selenium，其多浏览器支持（Chromium, Firefox, WebKit）和强大的自动等待机制给我留下了深刻印象。

编辑器方面，我尝试了Cursor。它深度集成了 AI 辅助编程，对于生成重复性代码、解释复杂逻辑、甚至基于自然语言描述创建组件原型都非常有帮助。它就像一个永远在线的结对编程伙伴，能显著减少查阅文档和调试的时间。

TaskMaster是我用来管理项目开发任务的自定义脚本集合（或指代类似npm scripts的自动化工具）。通过配置package.json中的 scripts 字段，将常用的命令如dev、build、lint、test:e2e封装起来，形成一套标准的开发指令，让团队任何成员都能快速上手。

3. 核心开发流程与工程化实践

3.1 项目初始化与结构规范

项目的第一步是搭建骨架。使用 Vite 的官方模板可以快速起步：

npm create vite@latest yucco-k.github.io -- --template react-ts cd yucco-k.github.io npm install

安装核心依赖：

npm install framer-motion styled-components npm install @react-three/fiber @react-three/drei three npm install react-router-dom npm install react-markdown npm install --save-dev @types/styled-components @types/three

项目结构组织清晰是关键。我采用了按功能分组的目录结构，而非按文件类型（如所有组件放一个文件夹）。src/components存放通用的、可复用的 UI 组件（如 Button、Card、Header）。src/pages则对应路由页面（如 Home、About、Projects）。src/hooks存放自定义 React Hooks，src/utils放工具函数，src/assets放图片、字体等静态资源。这种结构在项目规模增长时依然能保持良好的可维护性。

3.2 基于 Styled-Components 的主题与全局样式管理

在src目录下创建styles文件夹，定义主题和全局样式。首先创建一个theme.ts文件，定义颜色、字体、间距等设计令牌：

// src/styles/theme.ts export const lightTheme = { colors: { primary: '#0070f3', background: '#ffffff', text: '#333333', // ... 其他颜色 }, fonts: { body: `'Inter', sans-serif` }, spacing: (factor: number) => `${8 * factor}px`, }; export const darkTheme = { ... }; // 暗色主题定义

然后，在应用根组件（通常是main.tsx或App.tsx）中使用ThemeProvider：

import { ThemeProvider } from 'styled-components'; import { lightTheme } from './styles/theme'; function App() { return ( <ThemeProvider theme={lightTheme}> {/* 应用的其他部分 */} </ThemeProvider> ); }

在任何子组件中，都可以通过props.theme访问这些变量：

import styled from 'styled-components'; const StyledButton = styled.button` background-color: ${(props) => props.theme.colors.primary}; font-family: ${(props) => props.theme.fonts.body}; padding: ${(props) => props.theme.spacing(2)} ${(props) => props.theme.spacing(4)}; `;

实操心得：在 TypeScript 项目中，需要为styled-components声明默认主题的类型，否则在样式函数中访问props.theme会报类型错误。创建一个src/styles/styled.d.ts声明文件，并扩展DefaultTheme接口。

3.3 利用 Framer Motion 打造流畅交互动画

Framer Motion 的核心概念是motion组件。任何 HTML 或 SVG 元素都可以通过加上motion.前缀变成可动画元素。例如，让一个<div>在加载时淡入并向上移动：

import { motion } from 'framer-motion'; const AnimatedBox = () => ( <motion.div initial={{ opacity: 0, y: 20 }} // 初始状态 animate={{ opacity: 1, y: 0 }} // 动画结束状态 transition={{ duration: 0.5 }} // 过渡效果 > 我会动！ </motion.div> );

更强大的功能是whileHover、whileTap等手势动画，以及AnimatePresence组件处理元素的进入和退出动画。例如，实现一个卡片悬停放大效果：

<motion.article whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }} transition={{ type: 'spring', stiffness: 400, damping: 17 }} > {/* 卡片内容 */} </motion.article>

注意事项：动画虽好，但切忌滥用。过多的非必要动画会分散用户注意力，甚至引起不适。遵循“少即是多”的原则，动画应服务于功能引导（如指示状态变化）或提升愉悦感，而非炫技。同时，要确保动画性能，优先使用 CSS 属性（如opacity,transform），避免触发重排（如width,height）。

3.4 配置 React Router 实现客户端路由

对于单页应用（SPA），路由是核心。在App.tsx中配置路由：

import { BrowserRouter, Routes, Route } from 'react-router-dom'; import HomePage from './pages/Home'; import ProjectsPage from './pages/Projects'; import ProjectDetailPage from './pages/ProjectDetail'; import NotFoundPage from './pages/NotFound'; function App() { return ( <BrowserRouter> <Routes> <Route path="/" element={<HomePage />} /> <Route path="/projects" element={<ProjectsPage />} /> <Route path="/projects/:id" element={<ProjectDetailPage />} /> <Route path="*" element={<NotFoundPage />} /> </Routes> </BrowserRouter> ); }

这里有一个关键点：为了让动态路由在 GitHub Pages 这样的静态托管服务上正常工作，需要处理 404 重定向。我们稍后在部署部分会详细说明。

4. 自动化部署流水线：GitHub Actions 深度配置

4.1 GitHub Pages 部署原理与 SPA 适配挑战

GitHub Pages 本质上是一个静态文件托管服务。它将你指定分支（通常是gh-pages或main下的docs文件夹）里的 HTML、CSS、JS 文件直接提供给用户浏览器。这对于 Vite 构建出的dist目录是完美的。

然而，SPA 的路由带来了一个挑战：当用户直接访问https://yourname.github.io/projects/123时，GitHub Pages 服务器会去寻找projects/123/index.html这个文件，但显然不存在，于是返回 404。解决方案是：提供一个自定义的404.html页面，其内容与index.html完全相同，并加入一段 JavaScript 脚本，将请求重定向到 SPA 的入口。

Vite 社区有现成的插件vite-plugin-single-spa或vite-plugin-gh-pages可以处理这个，但手动配置也不复杂。在public目录下创建一个404.html，内容复制自index.html，然后在<head>标签后加入：

<script> // 单页应用 404 重定向 const segmentCount = 0; // 如果你的站点在 `https://username.github.io/repo/`，这里填 1 const l = window.location; l.replace( l.protocol + '//' + l.hostname + (l.port ? ':' + l.port : '') + l.pathname.split('/').slice(0, 1 + segmentCount).join('/') + '/?' + (l.pathname.split('/').slice(1 + segmentCount).join('/').replace(/&/g, '~and~') || '') + (l.search ? '&' + l.search.slice(1) : '') + l.hash ); </script>

4.2 编写高效的 GitHub Actions 工作流

自动化部署的核心是.github/workflows/deploy.yml文件。这个工作流定义了在代码推送到main分支后，自动执行构建和部署的步骤。

name: Deploy to GitHub Pages on: push: branches: [ main ] # 触发条件：main分支有push时 # 设置GITHUB_TOKEN的写入权限，这是部署的关键 permissions: contents: write pages: write id-token: write jobs: build-and-deploy: runs-on: ubuntu-latest # 在最新的Ubuntu虚拟机上运行 environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: # 1. 检出代码 - name: Checkout uses: actions/checkout@v4 # 2. 设置Node.js环境 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' # 使用与开发环境一致的Node版本 cache: 'npm' # 启用npm缓存，加速依赖安装 # 3. 安装依赖（使用npm ci保证依赖锁一致性） - name: Install Dependencies run: npm ci # 4. 运行代码检查（可选，但推荐） - name: Run Linter run: npm run lint # 5. 构建项目 - name: Build run: npm run build env: # 如果项目中有用到环境变量，可以在这里设置 VITE_APP_BASE_URL: '/' # 6. 配置404页面以支持SPA路由（关键步骤） - name: Setup SPA 404 page run: | cp ./dist/index.html ./dist/404.html # 7. 部署到GitHub Pages - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist # 发布dist目录的内容

这个工作流做了几件重要的事：

1. 缓存依赖：cache: 'npm'会缓存node_modules，下次运行工作流时如果package-lock.json没变，就直接使用缓存，将安装步骤从几十秒缩短到几秒。
2. 使用npm ci：在 CI 环境中，使用npm ci而不是npm install。它会根据package-lock.json精确安装依赖，确保每次构建的环境完全一致，避免因依赖版本浮动导致的构建失败。
3. SPA 适配：在构建后，将index.html复制一份并重命名为404.html。这样，任何未找到的路径（如/projects/123）都会由 GitHub Pages 返回这个404.html文件，其中的 JavaScript 代码（我们之前添加的）会接管并交给 React Router 处理。
4. 使用社区 Action：peaceiris/actions-gh-pages是一个经过广泛验证的、专门用于部署到 GitHub Pages 的 Action，它简化了流程，稳定可靠。

4.3 配置仓库设置与自定义域名（可选）

工作流配置好后，每次推送到main分支，GitHub Actions 都会自动运行。完成后，你可以在仓库的Settings->Pages页面看到部署状态和站点 URL。

如果你想使用自定义域名（如portfolio.yourname.com），需要：

1. 在域名注册商处添加一条CNAME记录，指向yourusername.github.io。
2. 在仓库根目录的public文件夹下创建一个名为CNAME的文件（无后缀），内容就是你的自定义域名（如portfolio.yourname.com）。
3. 在仓库的 GitHub Pages 设置页面，填入你的自定义域名。

重要提示：使用自定义域名后，需要更新 Vite 的构建基础路径（base）和 React Router 的basename配置，以确保资源路径正确。在vite.config.ts中设置base: '/'（如果托管在根目录）或base: '/repository-name/'（如果托管在子路径）。在 React Router 的BrowserRouter中设置basename属性与之匹配。

5. 开发、测试与优化实战记录

5.1 利用 Playwright 编写可靠的 E2E 测试

E2E 测试模拟真实用户操作，是保障核心功能稳定的最后一道防线。在项目根目录下运行npm init playwright@latest可以快速初始化 Playwright。

一个典型的测试用例（tests/homepage.spec.ts）如下：

import { test, expect } from '@playwright/test'; test('主页加载并显示关键内容', async ({ page }) => { // 1. 导航到首页 await page.goto('http://localhost:5173'); // 开发服务器地址 // 2. 断言页面标题包含特定文本 await expect(page).toHaveTitle(/Yucco-K/); // 3. 断言关键元素存在 const heading = page.getByRole('heading', { name: /欢迎来到我的作品集/i }); await expect(heading).toBeVisible(); // 4. 测试导航功能 const projectsLink = page.getByRole('link', { name: /项目/i }); await projectsLink.click(); await expect(page).toHaveURL(/.*projects/); await expect(page.getByText(/我的项目列表/i)).toBeVisible(); }); test('暗色模式切换', async ({ page }) => { await page.goto('http://localhost:5173'); // 假设有一个切换按钮 const themeToggle = page.getByLabel('切换主题'); const body = page.locator('body'); // 检查初始可能是亮色 await expect(body).toHaveCSS('background-color', 'rgb(255, 255, 255)'); // 白色背景 // 点击切换 await themeToggle.click(); // 检查是否切换到暗色 await expect(body).toHaveCSS('background-color', 'rgb(18, 18, 18)'); // 深色背景 });

在package.json中配置脚本：

{ "scripts": { "test:e2e": "playwright test", "test:e2e:ui": "playwright test --ui", "test:e2e:headed": "playwright test --headed" } }

实操心得：E2E 测试运行较慢，不应作为单元测试使用。只为最关键的用户流编写测试。使用page.getByRole()、page.getByText()等语义化选择器，它们比基于 CSS 选择器的page.locator(‘.btn-primary’)更稳定，即使样式类名改变，测试也不会轻易失败。在 CI 中运行测试时，确保开发服务器已经启动（可以使用npm run dev &后台启动，并等待其就绪）。

5.2 性能优化与构建分析

Vite 的生产构建已经做了很多优化（代码分割、异步加载等），但我们还可以做得更好。

1. 依赖分析：使用rollup-plugin-visualizer分析构建产物体积。

   npm install --save-dev rollup-plugin-visualizer

   在vite.config.ts中配置：

   import { visualizer } from 'rollup-plugin-visualizer'; export default defineConfig({ plugins: [..., visualizer({ open: true })], // 构建后自动打开分析报告 });

   构建后，会生成一个stats.html文件，用图表直观展示每个依赖包的大小，帮你找出可以优化的“体积大户”。

2. 图片优化：对于作品集网站，图片往往是体积最大的资源。务必使用压缩后的图片（如通过 Squoosh、TinyPNG 等工具）。对于复杂图标，优先使用 SVG。Vite 内置了对静态资源的处理，但可以考虑使用vite-plugin-imagemin在构建时自动压缩图片。

3. 懒加载组件：对于非首屏必需的组件，如某些复杂的 3D 场景、弹窗内的内容，使用React.lazy和Suspense进行懒加载。

   import { lazy, Suspense } from 'react'; const Heavy3DComponent = lazy(() => import('./components/Heavy3DComponent')); function MyPage() { return ( <div> <Suspense fallback={<div>加载中...</div>}> <Heavy3DComponent /> </Suspense> </div> ); }

5.3 利用 Cursor 等 AI 工具提升开发效率

在开发过程中，像Cursor这样的 AI 辅助编辑器能扮演多种角色：

• 代码生成：描述一个功能，如“创建一个接受onClick和children属性的 React 按钮组件，使用 Styled-Components，并带有悬停效果”，它能快速生成结构良好的样板代码。
• 代码解释：遇到不熟悉的第三方库代码，可以直接选中并让 AI 解释其工作原理。
• 错误调试：将错误信息粘贴进去，AI 能提供可能的原因和修复建议。
• 重构建议：可以要求 AI 帮你将组件重构得更简洁，或者提取自定义 Hook。

注意事项：AI 是强大的辅助，但不是替代品。它生成的代码需要你仔细审查，特别是业务逻辑部分。它有时会“幻觉”出不存在的 API 或给出过时的解决方案。将其视为一个知识渊博但偶尔会出错的实习生，最终的决策和代码质量责任仍在开发者本人。

6. 常见问题、排查记录与避坑指南

在构建和部署过程中，我遇到并解决了一些典型问题，这里记录下来供你参考。

6.1 GitHub Pages 部署后页面空白或资源加载 404

这是最常见的问题，通常由以下原因导致：

1. 构建基础路径（base）错误：

   • 症状：控制台报错Failed to load resource: net::ERR_ABORTED 404，指向.js或.css文件。
   • 原因：Vite 默认假设应用部署在域名根路径。如果你的仓库名是username.github.io，则部署在根路径，base应为‘/’。如果你的仓库名是project-name，则部署在username.github.io/project-name/子路径下，base必须设置为‘/project-name/’。
   • 解决：在vite.config.ts中正确设置base选项。可以设置为环境变量process.env.BASE_URL，并在 GitHub Actions 工作流中传递。

2. SPA 路由失效：

   • 症状：首页能打开，但手动输入或刷新子路由（如/projects）显示 GitHub 的 404 页面。
   • 原因：没有正确配置404.html重定向，或者404.html文件没有被正确复制到dist目录并上传。
   • 解决：确保部署工作流中包含cp ./dist/index.html ./dist/404.html这一步，并且public/404.html（如果手动创建了）也正确复制到了dist目录。

6.2 TypeScript 与第三方库的类型冲突

1. 症状：安装一个没有自带 TypeScript 类型定义的库（如某些较老的 npm 包）后，导入时出现Could not find a declaration file错误。
2. 解决：
   • 首先尝试安装社区维护的类型包：npm install --save-dev @types/package-name。
   • 如果不存在，可以在项目根目录或src目录下创建一个types文件夹，然后在该文件夹内创建一个package-name.d.ts文件，内容为：declare module ‘package-name’;。这是一种临时解决方案，意味着告诉 TypeScript“这个模块是存在的，别检查它”。
   • 对于更复杂的情况，可能需要自己编写完整的类型定义。

6.3 Styled-Components 在构建后类名闪烁（FOUC）

1. 症状：页面加载瞬间，样式未生效，看到无样式的 HTML（Flash of Unstyled Content），然后样式突然出现。
2. 原因：在服务器端渲染（SSR）场景下更常见，但在纯客户端渲染中，如果 JavaScript 加载较慢也可能发生。根本原因是样式是通过 JavaScript 动态注入到<style>标签的，在 JS 执行前样式不存在。
3. 解决：
   • 确保在 React 树的根部使用<StyleSheetManager>并设置enableVendorPrefixes属性（虽然 Vite 项目不常见）。
   • 对于关键的首屏样式，可以考虑使用 CSS 文件进行内联或预加载。但更根本的方法是使用 Styled-Components 的ServerStyleSheet进行 SSR，这对于静态站点生成（SSG）框架如 Next.js 是标准操作。在纯 Vite CSR 项目中，优化 JS 包的加载速度（代码分割、预加载）是缓解此问题的主要手段。

6.4 GitHub Actions 工作流运行失败排查

当 Actions 运行失败时，可以按以下步骤排查：

1. 查看日志：在仓库的Actions标签页，点击失败的工作流运行，仔细阅读红色错误信息。最常见的错误是npm install失败（网络问题）或npm run build失败（代码/类型错误）。
2. 本地复现：尝试在本地运行npm ci && npm run build，看是否能成功。CI 环境与本地环境高度一致（通过package-lock.json保证），本地能成功，CI 失败的概率就低。
3. 检查权限：确保工作流 YAML 文件中设置了正确的permissions，特别是contents: write，这是向gh-pages分支推送代码所必需的。
4. 缓存问题：如果怀疑是缓存了错误的依赖，可以在工作流运行界面点击“Re-run all jobs”并勾选“Enable debug logging”获取更详细的信息，或者临时在工作流步骤中禁用缓存。

整个项目从技术选型到自动化部署，是一次完整的现代前端开发实践。它不仅仅产出了一个展示性的网站，更构建了一套高效、可靠、可复用的开发工作流。这套流程和工具链同样适用于构建更复杂的 Web 应用。技术永远在迭代，但追求更优的开发体验和更稳健的交付流程，是每个开发者值得持续投入的方向。