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 这个组合在项目启动前我对比了多个方案。传统的 CRACreate-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 设计让复杂的序列动画和手势交互变得非常简单。例如实现一个元素在进入视口时从淡入到滑入的动画只需要几行代码而无需手动操作 CSSkeyframes或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 vitelatest 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 Hookssrc/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中使用ThemeProviderimport { 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 ); /script4.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/checkoutv4 # 2. 设置Node.js环境 - name: Setup Node.js uses: actions/setup-nodev4 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-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist # 发布dist目录的内容这个工作流做了几件重要的事缓存依赖cache: npm会缓存node_modules下次运行工作流时如果package-lock.json没变就直接使用缓存将安装步骤从几十秒缩短到几秒。使用npm ci在 CI 环境中使用npm ci而不是npm install。它会根据package-lock.json精确安装依赖确保每次构建的环境完全一致避免因依赖版本浮动导致的构建失败。SPA 适配在构建后将index.html复制一份并重命名为404.html。这样任何未找到的路径如/projects/123都会由 GitHub Pages 返回这个404.html文件其中的 JavaScript 代码我们之前添加的会接管并交给 React Router 处理。使用社区 Actionpeaceiris/actions-gh-pages是一个经过广泛验证的、专门用于部署到 GitHub Pages 的 Action它简化了流程稳定可靠。4.3 配置仓库设置与自定义域名可选工作流配置好后每次推送到main分支GitHub Actions 都会自动运行。完成后你可以在仓库的Settings-Pages页面看到部署状态和站点 URL。如果你想使用自定义域名如portfolio.yourname.com需要在域名注册商处添加一条CNAME记录指向yourusername.github.io。在仓库根目录的public文件夹下创建一个名为CNAME的文件无后缀内容就是你的自定义域名如portfolio.yourname.com。在仓库的 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 playwrightlatest可以快速初始化 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 的生产构建已经做了很多优化代码分割、异步加载等但我们还可以做得更好。依赖分析使用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文件用图表直观展示每个依赖包的大小帮你找出可以优化的“体积大户”。图片优化对于作品集网站图片往往是体积最大的资源。务必使用压缩后的图片如通过 Squoosh、TinyPNG 等工具。对于复杂图标优先使用 SVG。Vite 内置了对静态资源的处理但可以考虑使用vite-plugin-imagemin在构建时自动压缩图片。懒加载组件对于非首屏必需的组件如某些复杂的 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这是最常见的问题通常由以下原因导致构建基础路径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 工作流中传递。SPA 路由失效症状首页能打开但手动输入或刷新子路由如/projects显示 GitHub 的 404 页面。原因没有正确配置404.html重定向或者404.html文件没有被正确复制到dist目录并上传。解决确保部署工作流中包含cp ./dist/index.html ./dist/404.html这一步并且public/404.html如果手动创建了也正确复制到了dist目录。6.2 TypeScript 与第三方库的类型冲突症状安装一个没有自带 TypeScript 类型定义的库如某些较老的 npm 包后导入时出现Could not find a declaration file错误。解决首先尝试安装社区维护的类型包npm install --save-dev types/package-name。如果不存在可以在项目根目录或src目录下创建一个types文件夹然后在该文件夹内创建一个package-name.d.ts文件内容为declare module ‘package-name’;。这是一种临时解决方案意味着告诉 TypeScript“这个模块是存在的别检查它”。对于更复杂的情况可能需要自己编写完整的类型定义。6.3 Styled-Components 在构建后类名闪烁FOUC症状页面加载瞬间样式未生效看到无样式的 HTMLFlash of Unstyled Content然后样式突然出现。原因在服务器端渲染SSR场景下更常见但在纯客户端渲染中如果 JavaScript 加载较慢也可能发生。根本原因是样式是通过 JavaScript 动态注入到style标签的在 JS 执行前样式不存在。解决确保在 React 树的根部使用StyleSheetManager并设置enableVendorPrefixes属性虽然 Vite 项目不常见。对于关键的首屏样式可以考虑使用 CSS 文件进行内联或预加载。但更根本的方法是使用 Styled-Components 的ServerStyleSheet进行 SSR这对于静态站点生成SSG框架如 Next.js 是标准操作。在纯 Vite CSR 项目中优化 JS 包的加载速度代码分割、预加载是缓解此问题的主要手段。6.4 GitHub Actions 工作流运行失败排查当 Actions 运行失败时可以按以下步骤排查查看日志在仓库的Actions标签页点击失败的工作流运行仔细阅读红色错误信息。最常见的错误是npm install失败网络问题或npm run build失败代码/类型错误。本地复现尝试在本地运行npm ci npm run build看是否能成功。CI 环境与本地环境高度一致通过package-lock.json保证本地能成功CI 失败的概率就低。检查权限确保工作流 YAML 文件中设置了正确的permissions特别是contents: write这是向gh-pages分支推送代码所必需的。缓存问题如果怀疑是缓存了错误的依赖可以在工作流运行界面点击“Re-run all jobs”并勾选“Enable debug logging”获取更详细的信息或者临时在工作流步骤中禁用缓存。整个项目从技术选型到自动化部署是一次完整的现代前端开发实践。它不仅仅产出了一个展示性的网站更构建了一套高效、可靠、可复用的开发工作流。这套流程和工具链同样适用于构建更复杂的 Web 应用。技术永远在迭代但追求更优的开发体验和更稳健的交付流程是每个开发者值得持续投入的方向。