1. 项目概述一个技能展示页面的诞生最近在整理个人项目时我重构了一个名为homes-skills-page-web的仓库。这个项目说白了就是一个用来展示个人或团队技能栈的静态网页。听起来很简单对吧但恰恰是这种看似简单的“门面”项目最能体现一个前端开发者的综合能力与审美品味。它不像复杂的后台系统那样有海量逻辑也不像数据可视化大屏那样需要处理庞杂的数据流它的核心目标非常纯粹清晰、美观、高效地将“我会什么”和“我能做什么”传达给访客。无论是用于个人简历的在线补充、开源项目的主页还是作为团队技术栈的展示窗口一个精心设计的技能页面都能起到事半功倍的效果。homes-skills-page-web这个项目就是基于这样的需求诞生的。它不仅仅是一堆技术图标Icon的堆砌更是一个涉及前端工程化、UI/UX设计、性能优化和部署运维的综合性练手项目。通过拆解它我们能聊的远不止如何写几个HTML标签和CSS样式而是如何从零开始构建一个既专业又易于维护的现代前端静态站点。2. 核心设计思路与技术选型2.1 为什么选择静态站点生成SSG在项目启动时我们面临第一个选择采用传统的服务端渲染SSR、客户端渲染CSR还是静态站点生成SSG对于技能展示页这种内容相对固定、更新频率较低、但对加载速度和SEO有要求的场景SSG几乎是毋庸置疑的最佳选择。SSG的核心思想是在构建时Build Time就生成完整的HTML页面而不是在用户请求时动态生成。这意味着极致的加载速度用户访问时服务器直接返回预先生成的HTML、CSS、JS文件无需等待数据库查询或服务端计算首屏加载时间FCP, LCP指标会非常漂亮。出色的SEO搜索引擎爬虫抓取到的是完整的HTML内容所有技能信息、描述文本都能被直接索引这对于个人品牌曝光至关重要。低成本与高可用生成的静态文件可以托管在任何静态资源服务器上如GitHub Pages、Vercel、Netlify等这些平台通常提供免费的CDN和SSL证书部署简单运维成本几乎为零。安全性高没有数据库没有服务端运行时攻击面大大减少。在homes-skills-page-web中我们虽然没有使用像 Next.js、Nuxt.js 这样的全功能框架但其构建思路与SSG一脉相承。我们通过现代化的前端工具链如Vite进行构建和打包最终输出一个纯粹的、优化过的静态资源目录。2.2 技术栈的权衡React TypeScript Tailwind CSS确定了SSG的方向后具体的技术栈选型就需要仔细权衡。这个项目我选择了React TypeScript Tailwind CSS的组合。React作为目前最主流的前端UI库其组件化思想非常适合构建这种由多个独立技能卡片、导航栏、页脚等部分组成的页面。每个技能项都可以被抽象为一个SkillCard组件数据通过Props传入逻辑清晰复用性强。虽然对于单页应用来说有点“杀鸡用牛刀”但其生态和开发者体验的优势明显。TypeScript在这样一个规模不大的项目中引入TS主要目的是提升代码的健壮性和可维护性。我们可以为技能数据定义清晰的接口Interface例如ISkill明确每个技能对象必须包含name、level、category、icon等属性。这样在开发过程中编辑器就能提供智能提示和类型检查避免出现skill.levl这样的拼写错误或者在迭代时忘记更新某个属性的调用处。Tailwind CSS这是本项目的点睛之笔。传统的CSS编写方式如BEM或CSS-in-JS方案在需要快速迭代样式、保持设计一致性时往往会带来不小的认知负担。Tailwind 的实用工具类Utility-First理念允许我们直接在HTML/JSX中通过类名组合来定义样式。对于技能页面这种需要精细调整间距、颜色、响应式布局的场景Tailwind 的效率极高。例如一个技能卡片的样式可能只需要className“p-6 bg-white rounded-xl shadow-md hover:shadow-lg transition-shadow duration-300”这样一行代码就能搞定内边距、背景、圆角、阴影及悬停效果。这个技术栈组合保证了开发效率、代码质量和最终视觉效果的三重提升。2.3 数据结构与内容管理技能数据是页面的灵魂。如何组织这些数据决定了代码的清晰度和后续更新的便利性。一个糟糕的设计是把所有技能信息硬编码在组件的JSX里这会导致内容与样式高度耦合难以维护。在homes-skills-page-web中我采用了数据与视图分离的策略。具体做法是在src/data/目录下创建一个skills.ts或skills.json文件。在这个文件中导出一个技能数据数组每个元素都是一个符合ISkill接口的对象。在主要的页面组件中导入这个数据数组使用Array.map()方法遍历并渲染出每一个SkillCard组件。// src/data/skills.ts export interface ISkill { id: number; name: string; category: frontend | backend | tool | design; proficiency: number; // 1-5 icon: string; // 图标名称或SVG路径 description?: string; // 可选描述 } export const skillsData: ISkill[] [ { id: 1, name: React, category: frontend, proficiency: 5, icon: RiReactjsLine, description: 构建用户界面的JavaScript库 }, { id: 2, name: TypeScript, category: frontend, proficiency: 4, icon: SiTypescript, description: JavaScript的超集添加了静态类型 }, { id: 3, name: Node.js, category: backend, proficiency: 4, icon: FaNodeJs, description: JavaScript运行时环境 }, // ... 更多技能 ];// src/components/SkillsSection.tsx import { skillsData } from ../data/skills; import SkillCard from ./SkillCard; const SkillsSection () { return ( div classNamegrid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 {skillsData.map((skill) ( SkillCard key{skill.id} skill{skill} / ))} /div ); };这种方式的好处是当你需要添加、删除或修改某个技能时只需要编辑skills.ts这个数据文件完全不需要动组件代码。未来如果考虑接入无头CMS如Strapi、Contentful来管理内容这个结构也能轻松适配。3. 关键实现细节与组件设计3.1 技能卡片SkillCard组件的精细化设计SkillCard是页面的核心视觉单元。一个好的卡片设计应该在有限的空间内清晰地传达多项信息技能名称、所属类别、熟练程度、图标以及可选的简短描述。视觉层次与布局图标与名称通常图标放置在最左侧或顶部技能名称紧邻其右或下方使用较大的字体和醒目的颜色形成第一视觉焦点。类别标签使用一个小的、色彩柔和的徽章Badge来展示类别如“前端”、“后端”。这有助于访客快速分类浏览。可以用Tailwind的bg-{color}-100 text-{color}-800来实现。熟练度指示器这是设计的难点和亮点。避免使用简单的文本“精通”、“熟悉”。更直观的方式是采用视觉化评分例如星级评分渲染5个星形图标根据proficiency值填充对应数量的星星。进度条一个横向的细长条填充比例对应熟练度百分比。等级描述颜色将1-5的数值映射为“入门”、“进阶”、“熟练”、“精通”、“专家”等文本并用从浅到深的颜色梯度表示。交互与动效 静态的卡片略显呆板。添加轻微的交互能提升用户体验。悬停效果使用Tailwind的hover:前缀为卡片添加阴影提升 (hover:shadow-lg)、轻微上移 (hover:-translate-y-1) 或背景色变化。点击效果如果技能需要链接到更详细的说明或项目可以为卡片添加cursor-pointer和点击后的缩放效果 (active:scale-95)。过渡动画为所有变换属性添加transition-all duration-200 ease-in-out让交互变得平滑。3.2 技能分类过滤与搜索功能当技能数量较多时比如超过20项全部平铺展示会显得杂乱。实现分类过滤和搜索功能能极大提升页面的可用性。分类过滤从skillsData中提取所有不重复的category值动态生成一组过滤按钮。使用React的useState钩子来管理当前选中的分类如activeCategory初始值为‘all’。在渲染技能列表前根据activeCategory对skillsData进行过滤const filteredSkills activeCategory ‘all’ ? skillsData : skillsData.filter(skill skill.category activeCategory);将filteredSkills用于渲染。客户端搜索在页面顶部添加一个搜索输入框。使用useState管理搜索关键词searchTerm。在过滤逻辑中加入搜索过滤skillsData.filter(skill skill.name.toLowerCase().includes(searchTerm.toLowerCase()) || skill.description?.toLowerCase().includes(searchTerm.toLowerCase()))。为了提升体验可以结合使用useMemo来缓存过滤结果避免在每次渲染时都重新计算。注意对于纯静态站点搜索和过滤功能必须在客户端完成。这意味着初次加载时需要将全部技能数据下载到浏览器。如果数据量巨大数百条需要考虑分页或虚拟滚动。但对于个人技能页数据量通常很小客户端过滤是完全可行的。3.3 图标系统的选择与集成图标是技能页面的视觉语言的重要组成部分。选择一套统一、美观的图标库至关重要。方案对比React Icons这是最推荐的选择。它聚合了Font Awesome、Material Design Icons、Feather、Remix Icon等十多个流行图标库安装一个包即可使用所有。它按需引入Tree Shaking最终打包体积小。用法简单import { FaReact } from ‘react-icons/fa’;。SVG Sprite如果对图标有极高的自定义需求如修改路径、颜色渐变可以手动管理SVG文件并通过svguse xlinkHref“#icon-name” //svg的方式引用。这种方式最灵活但管理成本较高。图标字体如Font Awesome传统方案通过CSS类名使用。优点是使用简单缺点是所有图标会打包进一个字体文件即使只用了几个图标也可能加载数百KB的资源对性能不友好。在homes-skills-page-web中我选择了React Icons。因为它完美平衡了丰富性、易用性和性能。在skills.ts中icon字段存储的就是对应图标的导入名如‘FaReact’在SkillCard组件中可以动态渲染图标这需要一些额外的映射逻辑或者更简单地直接在数据中引用组件。3.4 响应式布局的实现技能页面必须在从手机到宽屏显示器的所有设备上都有良好的表现。Tailwind CSS的响应式工具类让这一切变得非常简单。核心策略移动端优先默认样式针对小屏幕设计然后使用md:、lg:、xl:等前缀来覆盖大屏幕的样式。网格布局使用grid布局来控制技能卡片的排列。例如div className“grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 md:gap-6”这表示在手机上单列显示在中等屏幕双列大屏幕三列超大屏幕四列。间距gap也随着屏幕尺寸增大而增加。Flexbox辅助用于控制卡片内部元素的排列如图标和文字的垂直或水平居中。字体与间距响应文字大小和内外边距也应响应式调整。例如标题在手机上用text-2xl在桌面上可以用text-3xl或text-4xl。测试要点开发过程中必须频繁使用浏览器的开发者工具切换设备模拟器进行测试确保没有内容溢出、布局错乱或触摸目标过小的问题。4. 性能优化与部署实践4.1 构建阶段的优化使用Vite或Webpack等现代构建工具本身已经做了很多优化。但我们还可以主动做更多代码分割Code Splitting虽然本项目是单页但如果引入了较大的第三方库如图表库用于技能雷达图可以考虑使用动态导入import()进行按需加载。资源优化图片如果使用了背景图或非图标图片务必进行压缩可使用工具如Squoosh、ImageOptim并转换为现代格式WebP。Vite在构建时可以对资源进行优化。字体如果使用了自定义字体使用font-display: swap;CSS属性避免文字渲染阻塞。并尽可能使用woff2格式。Tree Shaking确保ES模块导入以便打包工具能正确剔除未使用的代码。React Icons和Tailwind CSS在这方面都做得很好。4.2 部署到GitHub Pages与自定义域名GitHub Pages是托管此类静态项目的绝佳选择免费且与GitHub仓库无缝集成。部署步骤在package.json中配置构建命令和输出目录Vite默认是dist。安装gh-pages包npm install --save-dev gh-pages。在package.json中添加部署脚本“scripts”: { “build”: “vite build”, “predeploy”: “npm run build”, “deploy”: “gh-pages -d dist” }运行npm run deploy。这会将dist目录的内容推送到仓库的gh-pages分支。在仓库的Settings - Pages页面选择源分支为gh-pages和根目录几分钟后站点即可通过https://username.github.io/repo-name/访问。绑定自定义域名在域名注册商处为你的域名添加一条CNAME记录指向username.github.io。在项目的public或static目录下创建一个名为CNAME的文件无后缀内容就是你的域名例如skills.yourname.com。重新运行npm run deploy部署。回到GitHub仓库的Pages设置在“Custom domain”栏输入你的域名并保存。GitHub会自动为你配置SSL证书HTTPS。4.3 持续集成与自动部署手动运行部署命令还是太麻烦。我们可以利用GitHub Actions实现自动化每次向main分支推送代码时自动构建并部署到GitHub Pages。在项目根目录创建.github/workflows/deploy.yml文件name: Deploy to GitHub Pages on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: ‘18’ cache: ‘npm’ - name: Install Dependencies run: npm ci - name: Build run: npm run build - name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这样每次提交后你只需要等待几分钟网站就会自动更新。这实现了真正意义上的“Git工作流”开发体验非常流畅。5. 常见问题与排查实录在开发和部署homes-skills-page-web这类项目时我遇到并解决了一些典型问题这里记录下来供你参考。5.1 样式在构建后丢失或不生效问题描述本地开发时一切正常但运行npm run build部署后页面样式混乱Tailwind的类名似乎没起作用。原因与排查PurgeCSS/Tailwind CSS 内容配置Tailwind在生产构建时会使用PurgeCSS来移除未使用的样式以减小文件体积。如果配置不当它可能会错误地删除正在使用的样式。检查tailwind.config.js确保content字段正确包含了项目中所有使用Tailwind类名的文件路径。module.exports { content: [ ‘./index.html’, ‘./src/**/*.{js,ts,jsx,tsx}’, // 确保包含了你的组件文件 ], // ... }动态类名如果你使用了字符串拼接来生成动态类名如className{bg-${skill.color}-500}PurgeCSS可能无法识别。应改为完整类名映射const colorMap { react: ‘blue’, node: ‘green’ }; div className{bg-${colorMap[skill.name]}-500} / // 错误无法被Purge div className{colorMap[skill.name] ? ‘bg-‘ colorMap[skill.name] ‘-500’ : ‘’} / // 仍然不保险 // 最佳实践完整列出所有可能 const colorClass { ‘react’: ‘bg-blue-500’, ‘node’: ‘bg-green-500’, }[skill.name];5.2 GitHub Pages 部署后显示404或空白页问题描述部署脚本执行成功但访问页面显示404或一片空白控制台有资源加载失败的错误。排查步骤检查仓库设置确认GitHub Pages的源分支是gh-pages或你指定的分支并且目录是/ (root)。检查dist目录结构构建后dist目录下应有index.html以及assets等文件夹。如果index.html在子目录下需要在Pages设置中指定子目录或者在Vite配置中调整base和build.outDir。检查资源路径这是最常见的问题。如果你的项目不是部署在根路径例如https://username.github.io/repo-name/那么所有资源的相对路径都会出错。解决方案在vite.config.ts中设置base选项export default defineConfig({ base: process.env.NODE_ENV ‘production’ ? ‘/repo-name/’ : ‘/’, // 替换为你的仓库名 // ... });对于React Router如果用了也需要配置相应的basename。查看浏览器控制台打开部署后的页面按F12打开开发者工具查看“Console”和“Network”标签页。通常会有明确的404错误指出哪个JS或CSS文件加载失败。根据错误信息修正路径配置。5.3 图标在部署后不显示问题描述本地开发时图标正常部署后图标变成空白方块或显示占位符。排查步骤图标库的打包问题确保你使用的图标库支持生产环境。对于React Icons通常没有问题。动态图标加载如果你尝试用字符串动态加载图标组件例如通过eval或React.createElement在生产构建的优化过程中可能会出问题。更稳健的方式是使用映射对象import { FaReact, FaNodeJs, SiTypescript } from ‘react-icons/fa’; import { SiJavascript } from ‘react-icons/si’; const iconComponents { ‘FaReact’: FaReact, ‘FaNodeJs’: FaNodeJs, ‘SiTypescript’: SiTypescript, ‘SiJavascript’: SiJavascript, }; const SkillCard ({ skill }) { const Icon iconComponents[skill.icon]; return ( div {Icon Icon className“text-2xl” /} {/* ... */} /div ); };字体图标如果使用如果使用了字体图标如Font Awesome确保通过CDN链接或正确打包的字体文件能被访问。检查Network面板中字体文件的加载状态。5.4 移动端触摸体验不佳问题描述在手机上按钮难以点击卡片滑动不跟手。优化建议确保触摸目标足够大WAI-ARIA指南建议最小触摸目标尺寸为44x44像素。为可点击元素如过滤按钮、卡片添加足够的padding。禁用用户缩放谨慎使用如果页面是纯信息展示不需要缩放可以在index.html的head中添加meta name“viewport” content“widthdevice-width, initial-scale1, maximum-scale1, user-scalableno”。但请注意这可能会影响可访问性需根据实际情况决定。优化滚动性能确保没有在滚动容器上使用昂贵的CSS属性如box-shadow过度模糊。对于技能列表如果项目极多考虑使用虚拟滚动库如react-window但这对简单技能页通常不是必须的。这个项目虽然不大但贯穿了现代前端开发的完整链路从技术选型、组件设计、状态管理到性能优化、自动化部署和问题排查。它像一个精致的样板间展示了如何用当前主流且高效的技术栈快速构建一个高质量、可维护的静态产品。下次当你需要为自己或团队打造一个技术名片时不妨从这里开始然后注入你自己的创意和细节。
React+TypeScript+Tailwind构建静态技能展示页：从SSG原理到GitHub Pages部署
1. 项目概述一个技能展示页面的诞生最近在整理个人项目时我重构了一个名为homes-skills-page-web的仓库。这个项目说白了就是一个用来展示个人或团队技能栈的静态网页。听起来很简单对吧但恰恰是这种看似简单的“门面”项目最能体现一个前端开发者的综合能力与审美品味。它不像复杂的后台系统那样有海量逻辑也不像数据可视化大屏那样需要处理庞杂的数据流它的核心目标非常纯粹清晰、美观、高效地将“我会什么”和“我能做什么”传达给访客。无论是用于个人简历的在线补充、开源项目的主页还是作为团队技术栈的展示窗口一个精心设计的技能页面都能起到事半功倍的效果。homes-skills-page-web这个项目就是基于这样的需求诞生的。它不仅仅是一堆技术图标Icon的堆砌更是一个涉及前端工程化、UI/UX设计、性能优化和部署运维的综合性练手项目。通过拆解它我们能聊的远不止如何写几个HTML标签和CSS样式而是如何从零开始构建一个既专业又易于维护的现代前端静态站点。2. 核心设计思路与技术选型2.1 为什么选择静态站点生成SSG在项目启动时我们面临第一个选择采用传统的服务端渲染SSR、客户端渲染CSR还是静态站点生成SSG对于技能展示页这种内容相对固定、更新频率较低、但对加载速度和SEO有要求的场景SSG几乎是毋庸置疑的最佳选择。SSG的核心思想是在构建时Build Time就生成完整的HTML页面而不是在用户请求时动态生成。这意味着极致的加载速度用户访问时服务器直接返回预先生成的HTML、CSS、JS文件无需等待数据库查询或服务端计算首屏加载时间FCP, LCP指标会非常漂亮。出色的SEO搜索引擎爬虫抓取到的是完整的HTML内容所有技能信息、描述文本都能被直接索引这对于个人品牌曝光至关重要。低成本与高可用生成的静态文件可以托管在任何静态资源服务器上如GitHub Pages、Vercel、Netlify等这些平台通常提供免费的CDN和SSL证书部署简单运维成本几乎为零。安全性高没有数据库没有服务端运行时攻击面大大减少。在homes-skills-page-web中我们虽然没有使用像 Next.js、Nuxt.js 这样的全功能框架但其构建思路与SSG一脉相承。我们通过现代化的前端工具链如Vite进行构建和打包最终输出一个纯粹的、优化过的静态资源目录。2.2 技术栈的权衡React TypeScript Tailwind CSS确定了SSG的方向后具体的技术栈选型就需要仔细权衡。这个项目我选择了React TypeScript Tailwind CSS的组合。React作为目前最主流的前端UI库其组件化思想非常适合构建这种由多个独立技能卡片、导航栏、页脚等部分组成的页面。每个技能项都可以被抽象为一个SkillCard组件数据通过Props传入逻辑清晰复用性强。虽然对于单页应用来说有点“杀鸡用牛刀”但其生态和开发者体验的优势明显。TypeScript在这样一个规模不大的项目中引入TS主要目的是提升代码的健壮性和可维护性。我们可以为技能数据定义清晰的接口Interface例如ISkill明确每个技能对象必须包含name、level、category、icon等属性。这样在开发过程中编辑器就能提供智能提示和类型检查避免出现skill.levl这样的拼写错误或者在迭代时忘记更新某个属性的调用处。Tailwind CSS这是本项目的点睛之笔。传统的CSS编写方式如BEM或CSS-in-JS方案在需要快速迭代样式、保持设计一致性时往往会带来不小的认知负担。Tailwind 的实用工具类Utility-First理念允许我们直接在HTML/JSX中通过类名组合来定义样式。对于技能页面这种需要精细调整间距、颜色、响应式布局的场景Tailwind 的效率极高。例如一个技能卡片的样式可能只需要className“p-6 bg-white rounded-xl shadow-md hover:shadow-lg transition-shadow duration-300”这样一行代码就能搞定内边距、背景、圆角、阴影及悬停效果。这个技术栈组合保证了开发效率、代码质量和最终视觉效果的三重提升。2.3 数据结构与内容管理技能数据是页面的灵魂。如何组织这些数据决定了代码的清晰度和后续更新的便利性。一个糟糕的设计是把所有技能信息硬编码在组件的JSX里这会导致内容与样式高度耦合难以维护。在homes-skills-page-web中我采用了数据与视图分离的策略。具体做法是在src/data/目录下创建一个skills.ts或skills.json文件。在这个文件中导出一个技能数据数组每个元素都是一个符合ISkill接口的对象。在主要的页面组件中导入这个数据数组使用Array.map()方法遍历并渲染出每一个SkillCard组件。// src/data/skills.ts export interface ISkill { id: number; name: string; category: frontend | backend | tool | design; proficiency: number; // 1-5 icon: string; // 图标名称或SVG路径 description?: string; // 可选描述 } export const skillsData: ISkill[] [ { id: 1, name: React, category: frontend, proficiency: 5, icon: RiReactjsLine, description: 构建用户界面的JavaScript库 }, { id: 2, name: TypeScript, category: frontend, proficiency: 4, icon: SiTypescript, description: JavaScript的超集添加了静态类型 }, { id: 3, name: Node.js, category: backend, proficiency: 4, icon: FaNodeJs, description: JavaScript运行时环境 }, // ... 更多技能 ];// src/components/SkillsSection.tsx import { skillsData } from ../data/skills; import SkillCard from ./SkillCard; const SkillsSection () { return ( div classNamegrid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 {skillsData.map((skill) ( SkillCard key{skill.id} skill{skill} / ))} /div ); };这种方式的好处是当你需要添加、删除或修改某个技能时只需要编辑skills.ts这个数据文件完全不需要动组件代码。未来如果考虑接入无头CMS如Strapi、Contentful来管理内容这个结构也能轻松适配。3. 关键实现细节与组件设计3.1 技能卡片SkillCard组件的精细化设计SkillCard是页面的核心视觉单元。一个好的卡片设计应该在有限的空间内清晰地传达多项信息技能名称、所属类别、熟练程度、图标以及可选的简短描述。视觉层次与布局图标与名称通常图标放置在最左侧或顶部技能名称紧邻其右或下方使用较大的字体和醒目的颜色形成第一视觉焦点。类别标签使用一个小的、色彩柔和的徽章Badge来展示类别如“前端”、“后端”。这有助于访客快速分类浏览。可以用Tailwind的bg-{color}-100 text-{color}-800来实现。熟练度指示器这是设计的难点和亮点。避免使用简单的文本“精通”、“熟悉”。更直观的方式是采用视觉化评分例如星级评分渲染5个星形图标根据proficiency值填充对应数量的星星。进度条一个横向的细长条填充比例对应熟练度百分比。等级描述颜色将1-5的数值映射为“入门”、“进阶”、“熟练”、“精通”、“专家”等文本并用从浅到深的颜色梯度表示。交互与动效 静态的卡片略显呆板。添加轻微的交互能提升用户体验。悬停效果使用Tailwind的hover:前缀为卡片添加阴影提升 (hover:shadow-lg)、轻微上移 (hover:-translate-y-1) 或背景色变化。点击效果如果技能需要链接到更详细的说明或项目可以为卡片添加cursor-pointer和点击后的缩放效果 (active:scale-95)。过渡动画为所有变换属性添加transition-all duration-200 ease-in-out让交互变得平滑。3.2 技能分类过滤与搜索功能当技能数量较多时比如超过20项全部平铺展示会显得杂乱。实现分类过滤和搜索功能能极大提升页面的可用性。分类过滤从skillsData中提取所有不重复的category值动态生成一组过滤按钮。使用React的useState钩子来管理当前选中的分类如activeCategory初始值为‘all’。在渲染技能列表前根据activeCategory对skillsData进行过滤const filteredSkills activeCategory ‘all’ ? skillsData : skillsData.filter(skill skill.category activeCategory);将filteredSkills用于渲染。客户端搜索在页面顶部添加一个搜索输入框。使用useState管理搜索关键词searchTerm。在过滤逻辑中加入搜索过滤skillsData.filter(skill skill.name.toLowerCase().includes(searchTerm.toLowerCase()) || skill.description?.toLowerCase().includes(searchTerm.toLowerCase()))。为了提升体验可以结合使用useMemo来缓存过滤结果避免在每次渲染时都重新计算。注意对于纯静态站点搜索和过滤功能必须在客户端完成。这意味着初次加载时需要将全部技能数据下载到浏览器。如果数据量巨大数百条需要考虑分页或虚拟滚动。但对于个人技能页数据量通常很小客户端过滤是完全可行的。3.3 图标系统的选择与集成图标是技能页面的视觉语言的重要组成部分。选择一套统一、美观的图标库至关重要。方案对比React Icons这是最推荐的选择。它聚合了Font Awesome、Material Design Icons、Feather、Remix Icon等十多个流行图标库安装一个包即可使用所有。它按需引入Tree Shaking最终打包体积小。用法简单import { FaReact } from ‘react-icons/fa’;。SVG Sprite如果对图标有极高的自定义需求如修改路径、颜色渐变可以手动管理SVG文件并通过svguse xlinkHref“#icon-name” //svg的方式引用。这种方式最灵活但管理成本较高。图标字体如Font Awesome传统方案通过CSS类名使用。优点是使用简单缺点是所有图标会打包进一个字体文件即使只用了几个图标也可能加载数百KB的资源对性能不友好。在homes-skills-page-web中我选择了React Icons。因为它完美平衡了丰富性、易用性和性能。在skills.ts中icon字段存储的就是对应图标的导入名如‘FaReact’在SkillCard组件中可以动态渲染图标这需要一些额外的映射逻辑或者更简单地直接在数据中引用组件。3.4 响应式布局的实现技能页面必须在从手机到宽屏显示器的所有设备上都有良好的表现。Tailwind CSS的响应式工具类让这一切变得非常简单。核心策略移动端优先默认样式针对小屏幕设计然后使用md:、lg:、xl:等前缀来覆盖大屏幕的样式。网格布局使用grid布局来控制技能卡片的排列。例如div className“grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 md:gap-6”这表示在手机上单列显示在中等屏幕双列大屏幕三列超大屏幕四列。间距gap也随着屏幕尺寸增大而增加。Flexbox辅助用于控制卡片内部元素的排列如图标和文字的垂直或水平居中。字体与间距响应文字大小和内外边距也应响应式调整。例如标题在手机上用text-2xl在桌面上可以用text-3xl或text-4xl。测试要点开发过程中必须频繁使用浏览器的开发者工具切换设备模拟器进行测试确保没有内容溢出、布局错乱或触摸目标过小的问题。4. 性能优化与部署实践4.1 构建阶段的优化使用Vite或Webpack等现代构建工具本身已经做了很多优化。但我们还可以主动做更多代码分割Code Splitting虽然本项目是单页但如果引入了较大的第三方库如图表库用于技能雷达图可以考虑使用动态导入import()进行按需加载。资源优化图片如果使用了背景图或非图标图片务必进行压缩可使用工具如Squoosh、ImageOptim并转换为现代格式WebP。Vite在构建时可以对资源进行优化。字体如果使用了自定义字体使用font-display: swap;CSS属性避免文字渲染阻塞。并尽可能使用woff2格式。Tree Shaking确保ES模块导入以便打包工具能正确剔除未使用的代码。React Icons和Tailwind CSS在这方面都做得很好。4.2 部署到GitHub Pages与自定义域名GitHub Pages是托管此类静态项目的绝佳选择免费且与GitHub仓库无缝集成。部署步骤在package.json中配置构建命令和输出目录Vite默认是dist。安装gh-pages包npm install --save-dev gh-pages。在package.json中添加部署脚本“scripts”: { “build”: “vite build”, “predeploy”: “npm run build”, “deploy”: “gh-pages -d dist” }运行npm run deploy。这会将dist目录的内容推送到仓库的gh-pages分支。在仓库的Settings - Pages页面选择源分支为gh-pages和根目录几分钟后站点即可通过https://username.github.io/repo-name/访问。绑定自定义域名在域名注册商处为你的域名添加一条CNAME记录指向username.github.io。在项目的public或static目录下创建一个名为CNAME的文件无后缀内容就是你的域名例如skills.yourname.com。重新运行npm run deploy部署。回到GitHub仓库的Pages设置在“Custom domain”栏输入你的域名并保存。GitHub会自动为你配置SSL证书HTTPS。4.3 持续集成与自动部署手动运行部署命令还是太麻烦。我们可以利用GitHub Actions实现自动化每次向main分支推送代码时自动构建并部署到GitHub Pages。在项目根目录创建.github/workflows/deploy.yml文件name: Deploy to GitHub Pages on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: ‘18’ cache: ‘npm’ - name: Install Dependencies run: npm ci - name: Build run: npm run build - name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这样每次提交后你只需要等待几分钟网站就会自动更新。这实现了真正意义上的“Git工作流”开发体验非常流畅。5. 常见问题与排查实录在开发和部署homes-skills-page-web这类项目时我遇到并解决了一些典型问题这里记录下来供你参考。5.1 样式在构建后丢失或不生效问题描述本地开发时一切正常但运行npm run build部署后页面样式混乱Tailwind的类名似乎没起作用。原因与排查PurgeCSS/Tailwind CSS 内容配置Tailwind在生产构建时会使用PurgeCSS来移除未使用的样式以减小文件体积。如果配置不当它可能会错误地删除正在使用的样式。检查tailwind.config.js确保content字段正确包含了项目中所有使用Tailwind类名的文件路径。module.exports { content: [ ‘./index.html’, ‘./src/**/*.{js,ts,jsx,tsx}’, // 确保包含了你的组件文件 ], // ... }动态类名如果你使用了字符串拼接来生成动态类名如className{bg-${skill.color}-500}PurgeCSS可能无法识别。应改为完整类名映射const colorMap { react: ‘blue’, node: ‘green’ }; div className{bg-${colorMap[skill.name]}-500} / // 错误无法被Purge div className{colorMap[skill.name] ? ‘bg-‘ colorMap[skill.name] ‘-500’ : ‘’} / // 仍然不保险 // 最佳实践完整列出所有可能 const colorClass { ‘react’: ‘bg-blue-500’, ‘node’: ‘bg-green-500’, }[skill.name];5.2 GitHub Pages 部署后显示404或空白页问题描述部署脚本执行成功但访问页面显示404或一片空白控制台有资源加载失败的错误。排查步骤检查仓库设置确认GitHub Pages的源分支是gh-pages或你指定的分支并且目录是/ (root)。检查dist目录结构构建后dist目录下应有index.html以及assets等文件夹。如果index.html在子目录下需要在Pages设置中指定子目录或者在Vite配置中调整base和build.outDir。检查资源路径这是最常见的问题。如果你的项目不是部署在根路径例如https://username.github.io/repo-name/那么所有资源的相对路径都会出错。解决方案在vite.config.ts中设置base选项export default defineConfig({ base: process.env.NODE_ENV ‘production’ ? ‘/repo-name/’ : ‘/’, // 替换为你的仓库名 // ... });对于React Router如果用了也需要配置相应的basename。查看浏览器控制台打开部署后的页面按F12打开开发者工具查看“Console”和“Network”标签页。通常会有明确的404错误指出哪个JS或CSS文件加载失败。根据错误信息修正路径配置。5.3 图标在部署后不显示问题描述本地开发时图标正常部署后图标变成空白方块或显示占位符。排查步骤图标库的打包问题确保你使用的图标库支持生产环境。对于React Icons通常没有问题。动态图标加载如果你尝试用字符串动态加载图标组件例如通过eval或React.createElement在生产构建的优化过程中可能会出问题。更稳健的方式是使用映射对象import { FaReact, FaNodeJs, SiTypescript } from ‘react-icons/fa’; import { SiJavascript } from ‘react-icons/si’; const iconComponents { ‘FaReact’: FaReact, ‘FaNodeJs’: FaNodeJs, ‘SiTypescript’: SiTypescript, ‘SiJavascript’: SiJavascript, }; const SkillCard ({ skill }) { const Icon iconComponents[skill.icon]; return ( div {Icon Icon className“text-2xl” /} {/* ... */} /div ); };字体图标如果使用如果使用了字体图标如Font Awesome确保通过CDN链接或正确打包的字体文件能被访问。检查Network面板中字体文件的加载状态。5.4 移动端触摸体验不佳问题描述在手机上按钮难以点击卡片滑动不跟手。优化建议确保触摸目标足够大WAI-ARIA指南建议最小触摸目标尺寸为44x44像素。为可点击元素如过滤按钮、卡片添加足够的padding。禁用用户缩放谨慎使用如果页面是纯信息展示不需要缩放可以在index.html的head中添加meta name“viewport” content“widthdevice-width, initial-scale1, maximum-scale1, user-scalableno”。但请注意这可能会影响可访问性需根据实际情况决定。优化滚动性能确保没有在滚动容器上使用昂贵的CSS属性如box-shadow过度模糊。对于技能列表如果项目极多考虑使用虚拟滚动库如react-window但这对简单技能页通常不是必须的。这个项目虽然不大但贯穿了现代前端开发的完整链路从技术选型、组件设计、状态管理到性能优化、自动化部署和问题排查。它像一个精致的样板间展示了如何用当前主流且高效的技术栈快速构建一个高质量、可维护的静态产品。下次当你需要为自己或团队打造一个技术名片时不妨从这里开始然后注入你自己的创意和细节。
