前言
说来惭愧，做了这么多年开发，个人主页这件事一直搁置着。不是没想过，总觉得「以后再说」，结果一拖就是好几年。
网站地址：zhengz.cc
程序员做个人主页，就像厨师给自己做一顿饭——可以不用在意菜单，尽情整活。见过太多千篇一律的简历网站：白色背景 + 头像 + 时间轴 + 技能进度条，看多了真的会审美疲劳。
所以我想：为什么不做一个好玩的？
作为一个从小玩马里奥长大的 90 后，答案显而易见——把它做成超级马里奥的风格。
我的开发方式：先写文档，再 Vibe Coding
作为写了 9 年代码的开发者，这个项目我选择了 Vibe Coding 的方式来完成，「会写代码，所以更懂得如何让 AI 写好」。
如果你想把 AI 用好，最重要的是学会写设计文档。
我的开发流程是这样的：
需求想法 → 写 MD 设计文档 → 把文档丢给 AI → AI 生成代码 → 自己审查微调
听起来简单，但关键在第一步。如果你直接跟 AI 说"帮我做一个马里奥风格的个人网站"，出来的东西大概率是平庸的。但如果你花时间写了一份详细的设计文档，结果会完全不同。
我写了哪些文档？
这个项目我一共写了几份文档：
Mario UI 规范文档（mario-ui-spec.md）—— 定义了整个组件库的视觉风格、配色、组件接口。比如 MarioBlock 支持哪些变体（question / brick / ground / used），MarioCoin 的旋转动画帧数，MarioPipe 的高度和方向参数等。
职业关卡地图策划文档（Career-Platformer-设计文档.md）—— 把职业经历映射成马里奥关卡，定义了角色奔跑动画、视差滚动分层、旗帜触发流程、金币收集逻辑，甚至连角色跑过地面时脚底的像素烟雾粒子都写进去了。
具体实现记录文档—— 记录每个阶段的实现细节，方便后续迭代时回顾。
这些文档加起来有上千字，但正是因为文档足够详细，AI 才能精准地产出符合预期的代码。
为什么文档比 Prompt 重要？
很多人用 AI 写代码的痛点是：生成的代码不符合预期，改来改去，最后还不如自己写。
问题的本质是：你的需求没有想清楚。
写设计文档的过程，其实是在逼自己把需求想清楚：
- 这个组件有几个状态？
- 颜色用马里奥的哪个经典色值？
- 动画是几帧循环？触发条件是什么？
- 移动端怎么适配？
当你在文档里把这些都写明白了，AI 拿到的是一份明确的、可执行的规格说明，产出质量会高得多。
所以我的结论是：Vibe Coding 的核心能力不是写 Prompt，是写文档。
最终效果
打开网站，你看到的不是一个传统的个人主页，而是一个马里奥游戏关卡：
- 天蓝色背景 + 像素云朵缓缓飘动
- 管道作为区域分隔符
- 问号砖块可以点击，弹出金币
- 技能徽章像道具一样收集升级
- 整个页面持续统计你的金币得分
技术架构
这个项目在技术选型上用了目前最新的技术栈：
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | 16 | React 全栈框架 |
| React | 19 | UI 库 |
| TypeScript | 5 | 类型安全 |
| Tailwind CSS | v4 | 原子化样式 |
| Framer Motion | - | 动画交互 |
全部部署在 Cloudflare Pages 上，全球 CDN 加速，加载速度极快。
设计思路
1. 关卡式职业展示
职业经历不再是枯燥的时间轴，而是马里奥的关卡地图：
- World 1-1：前端起步阶段（天空蓝主题）
- World 2-1：快速成长（草地绿主题）
- World 3-1：agent工程师（紫色城堡主题）
每一段经历都有对应的关卡配色，让阅读过程像在闯关。
2. 游戏化交互
我加入了大量可交互的游戏元素：
问号砖块：点击弹金币，增加得分
技能徽章：点击可以升级星星等级，满级后不再响应
金币计数器：页面右上角实时统计，浏览互动越多得分越高
WARP ZONE：底部管道区，点击文字可以复制联系方式
这些交互不是为了炫技，而是让访客在浏览信息的过程中产生参与感。
3. 像素风组件库
我封装了一套完整的 Mario UI 组件库，所有视觉元素都遵循经典马里奥的像素风格：
- MarioBlock - 砖块卡片
- MarioPipe - 绿色管道
- MarioCoin - 旋转金币动画
- MarioCloud - 像素云朵
- MarioTitle - 游戏字体标题
每个组件都支持自定义尺寸和样式，方便复用。
4. 细节打磨
一些可能不容易注意到但花了不少心思的细节：
字体选择：全部使用 Courier New 等宽字体模拟像素感，配合textShadow营造游戏氛围
CSS 变量主题：所有颜色通过 CSS 变量管理，切换主题只需改几个变量
响应式：移动端、平板、桌面三种布局自适应
滚动动画：每个区域进入视口时有渐入效果（Framer Motion）
侧边装饰：每个 section 都有云朵、金币等点缀，避免大面积留白
SEO 优化：sitemap、robots.txt、Open Graph 元信息全部配置齐全
实现亮点
数据驱动
所有内容集中在resume-data.ts一个文件中管理，修改个人信息只需要改数据，不需要动组件：
export const resumeData = {
personal: {
name: '郑壮',
title: 'AI全栈工程师',
bio: '9年开发经验...',
},
skills: [
{ name: 'React', level: 'expert', category: 'frontend' },
// ...
],
}
动画系统
使用 Framer Motion 的whileInView实现滚动触发动画，配合viewport={{ once: true }}确保只播放一次，既流畅又不会让页面变得卡顿。
金币系统
通过 React Context 实现了一个全局金币计数器，跨组件共享状态。点击砖块、浏览不同区域都能获得金币，给整个浏览过程增加了游戏反馈。
遇到的挑战
像素感 vs 现代审美的平衡
纯像素风在手机上可能会显得粗糙。我的做法是：保留像素元素的灵魂（砖块、管道、金币），但在布局和间距上遵循现代设计规范，确保可读性和美观度。
移动端适配
马里奥的横向关卡天然适合宽屏，但手机是竖屏。最终选择了竖向滚动的关卡模式，将横版过关变成「纵向闯关」，在移动端反而更有沉浸感。
Vibe Coding 的调试
AI 生成的代码不完全符合预期是常态。好在我本身是做开发的，能快速定位问题出在哪——是 CSS 层级问题、状态管理遗漏还是动画参数不对。发现问题后直接告诉 AI 具体哪里不对，让它修复。比如管道对齐偏了、金币动画卡顿、移动端布局溢出——这些都是我在审查时发现并逐一修正的。
有开发经验的人用 Vibe Coding，优势不在于能让 AI 一次写对，而在于能快速判断哪里不对、怎么改。
写在最后
这次终于下定决心搞了，但说实话，如果不是 Vibe Coding 降低了实现成本，可能还会继续拖下去。AI 帮我加速了开发，但设计思路和技术决策还是得靠自己。文档怎么写、架构怎么定、验收标准是什么——这些是 9 年开发经验给的底气。
这个项目花了不少周末时间，时间主要花在写文档、审查代码和打磨细节上。
做个人主页的意义不在于它有多复杂，而在于它能不能表达你是谁。我是个喜欢游戏、喜欢折腾技术的人，所以马里奥风格再合适不过了。
如果你也一直想做个个人主页但还没动手，或者也想用 Vibe Coding 做自己的项目，我的建议是：别再等了，先把文档写好。文档写好了，代码水到渠成。
PRESS START BUTTON!
我是郑壮，一个用代码打怪升级的 AI 全栈工程师。
如果你喜欢这个项目，欢迎关注 GitHub ：github.com/zhengzhuang…
