1. 从零开始：理解VitePress的首页布局哲学
很多朋友第一次接触VitePress，看到那个简洁的默认页面，可能会觉得有点“素”。别急，这正是它的设计哲学——给你一张干净的白纸，让你自由发挥。我刚开始用的时候也犯嘀咕，这玩意儿能做出好看的博客首页吗？但折腾了几次之后发现，它的这套“约定大于配置”的体系，其实非常高效，尤其是当你理解了它的几个核心布局选项后，一切就豁然开朗了。
VitePress默认主题提供了几种布局，你可以把它想象成装修房子的几种基础户型图。layout: doc是最常用的，也是默认的“文档”户型。你写的Markdown内容会被自动套上一个清爽的文档样式，有合适的字体、间距和代码高亮，非常适合写技术文档、API手册。layout: page则像是一个“毛坯房”，它只负责解析你的Markdown语法，但几乎不附加任何默认样式，给你最大的自定义空间。而layout: home，就是我们今天要重点聊的“精装样板间”，它预置了Hero区域、Features区域等结构，让你能快速搭建出一个有模有样的博客门户或产品首页。
这里有个我踩过的坑得提醒你：这个layout配置是写在每个Markdown文件的Frontmatter里的。Frontmatter就是文件顶部用三个短横线---包裹起来的那块区域，专门用来放页面元数据。你必须在index.md这个首页文件的顶部，明确写上layout: home，告诉VitePress：“嘿，这个页面请用首页布局来渲染。” 如果你忘了写，或者写错了位置，它就会默默退回到默认的doc布局，你的首页可能就变成一篇普通的文章样子了，之前我因为缩进不对就折腾了半天。
所以，第一步永远是在你的docs目录下的index.md文件里，打下这个基础：
--- layout: home ---写完这个，你的首页才算是拿到了“精装修”的入场券。接下来，我们就可以在这个基础上，开始添置家具——也就是配置hero和features了。你会发现，VitePress的配置方式非常直观，就像在填一个JSON对象，层级清晰，改起来也方便。
2. 打造吸睛门面：Hero区域的深度配置与视觉优化
Hero区域，顾名思义，就是首页的“英雄区域”，位于页面最顶部，是访客第一眼看到的地方。它的配置直接决定了你博客给人的第一印象。VitePress的Hero配置项设计得很贴心，基本上你想要的元素它都考虑到了。
最基础的配置包括name、text和tagline。name通常放你的博客名或品牌名，会以大号字体突出显示。text可以理解为一个副标题，用来说明你的博客是干嘛的。tagline则是一句更详细的标语或描述，字体稍小，用于补充信息。我建议你把name写得响亮一点，text和tagline则要清晰传达你的博客价值，比如“一个专注于前端工程化实践的博客”、“分享AI应用开发中的实战经验”等等。
但光有文字还不够，视觉冲击力很重要。image配置项就是用来放Logo或者主视觉图的。这里有个细节：图片路径。VitePress默认的静态资源目录是docs/public，你把图片（比如logo.png）放在这个目录下，在配置里引用时直接用/logo.png就行。我遇到过有人把图片放在docs根目录或者别的子目录里，然后路径写不对导致图片出不来。记住，public目录下的文件在构建后会直接被复制到根目录，所以用绝对路径/开头引用是最稳妥的。
按钮（actions）是Hero区域的点睛之笔，引导用户进行下一步操作。VitePress提供了两种主题色：brand（品牌色，默认是绿色）和alt（替代色，默认是灰色）。你可以根据按钮的重要性来分配。比如，“快速开始”用醒目的brand主题，“查看GitHub”用alt主题。link可以指向站内页面，也可以指向外部链接。指向站内时，路径是基于docs目录的。如果你想链接到docs/guide/getting-started.md，那么link可以写成/guide/getting-started（可以省略.md后缀）。
下面是一个我常用的、比较完整的Hero配置示例，你可以直接参考这个结构来修改：
--- layout: home hero: image: src: /hero-logo.svg alt: 我的技术博客 name: 代码与咖啡 text: 专注于现代Web开发实战 tagline: 分享Vue 3、Vite、TypeScript以及性能优化等一线开发心得，拒绝空谈理论。 actions: - theme: brand text: 阅读最新文章 link: /blog/latest - theme: alt text: 关于我 link: /about - theme: alt text: 在GitHub上关注 link: https://github.com/yourname ---配置好后，你可能觉得默认的样式还是太“主题化”了，想微调一下。这时候就需要一点CSS魔法了。VitePress允许你通过.vitepress/theme目录下的index.js或style.css文件来自定义样式。比如，你觉得Hero区域的标题颜色太淡，可以在style.css里这样覆盖：
/* .vitepress/theme/style.css */ :root { --vp-home-hero-name-color: #1890ff; /* 将主标题改为蓝色 */ --vp-home-hero-text-color: #333; /* 将副标题改为深灰色 */ } .vp-hero .image { max-width: 180px !important; /* 调整Logo最大宽度 */ }通过调整这些CSS变量，你可以轻松地让Hero区域更贴合你的品牌色。记住，自定义样式时最好在浏览器开发者工具里先找到对应的类名或CSS变量，再进行覆盖，这样效率最高。
3. 内容展示核心：Features模块的灵活运用与高级技巧
如果说Hero区域是门面，那么Features区域就是客厅，用来展示你这个博客的“几室几厅”——也就是核心内容或特色板块。VitePress的Features配置非常灵活，每个Feature项就像一个信息卡片，可以展示一个技术栈、一个项目模块或者一系列文章分类。
每个Feature卡片最基本的元素是title（标题）和details（详情描述）。标题要简短有力，比如“Vue 3 实战”、“性能优化”。详情描述则用一两句话概括这个板块的内容，让用户一眼就知道这里面有什么干货。我建议描述不要写得太长，保持简洁明了。
为了让卡片更生动，可以加上icon。VitePress内置支持了一些图标集，但你也可以使用自定义的SVG图标。更实用的功能是link和linkText。这相当于给每个卡片加了一个“了解更多”的入口，可以直接链接到对应的分类页面、系列文章目录或者外部官网。比如，你有一个“TypeScript进阶”的Feature，link就可以指向/categories/typescript，linkText写成“阅读系列文章”。
Features的配置是一个数组，这意味着你可以轻松地增减、排序。下面是一个展示技术栈的配置例子，我把它做成了一个可复用的模块：
features: - icon: ⚡️ title: 极速构建 details: 基于Vite，享受闪电般的启动与热更新速度，提升开发体验。 link: /guide/why-vitepress linkText: 了解原理 - icon: 🛠️ title: 深入Vue 3 details: 从Composition API到渲染机制，剖析Vue 3核心原理与最佳实践。 link: /categories/vue - icon: 📦 title: 工程化实践 details: 分享前端构建、部署、监控等完整的工程化解决方案。 link: /tags/engineering - icon: 🔐 title: 全栈安全 details: 探讨前后端常见的安全漏洞与防御策略，构建可靠应用。配置完之后，你可能会觉得默认的卡片布局（比如一行显示3个）不符合你的预期。这时候，又轮到自定义CSS出场了。你可以通过覆盖Features容器的网格布局样式来调整。例如，想在桌面端一行显示4个卡片，可以这样写：
/* .vitepress/theme/style.css */ :root { --vp-features-grid-cols: 4; /* 默认是3，改为4 */ } @media (max-width: 768px) { :root { --vp-features-grid-cols: 2; /* 在小屏幕下改为2列 */ } }除了展示技术栈，Features区域还有更多创意用法。比如，你可以用它来做“最新文章”预览，动态展示最近更新的3篇文章标题和摘要（这通常需要结合一些构建脚本或API）。或者，做成“项目展示”墙，每个卡片展示一个开源项目的简介、技术栈和GitHub链接。它的灵活性远超简单的“特性”展示，完全可以成为你首页的内容聚合中心。
4. 导航栏定制：从基础配置到高级交互
导航栏是网站的“中枢神经系统”，用户靠它在不同内容间穿梭。VitePress的导航栏配置在.vitepress/config.js的themeConfig.nav选项中，功能相当强大。
最基础的导航项就是一个带文本和链接的对象：{ text: '首页', link: '/' }。但更多时候，我们需要下拉菜单。VitePress用items数组来配置下拉菜单，每个item对象里同样包含text和link。这里有个非常实用的技巧：你可以把导航配置单独抽离成一个模块，比如nav.js，然后在config.js里导入，这样主配置文件会更清晰，也方便多人协作。
我通常这样组织导航配置，把不同类型的链接归类：
// .vitepress/config/nav.js export default [ { text: '技术文章', items: [ { text: 'Vue 3 系列', link: '/vue/' }, { text: 'React 深入', link: '/react/' }, { text: '性能优化', link: '/performance/' }, { text: 'TypeScript', link: '/typescript/' } ] }, { text: '项目实战', items: [ { text: '开源项目', link: '/projects/open-source' }, { text: '案例分析', link: '/projects/case-study' } ] }, { text: '关于', link: '/about' } ]然后在主配置文件中引入：
// .vitepress/config.js import nav from './config/nav.js' export default { themeConfig: { nav, // 使用导入的导航配置 logo: '/logo.svg', // 可以同时配置Logo siteTitle: false // 隐藏Logo旁边的站点标题，让导航更简洁 } }关于Logo，除了配置路径，你还可以通过CSS微调其大小和位置。比如，觉得Logo太大了，可以加一条规则：.VPNavBarTitle .logo { height: 24px; }。
导航栏的交互细节也值得关注。比如“激活状态”——当前页面属于哪个导航项时，该项会高亮。VitePress会自动根据路由匹配。但这里有个巨坑，我亲身踩过：如果你的导航链接指向一个目录下的index.md文件（比如/about/index.md），在某些情况下，激活状态可能会失效！这是因为路由匹配逻辑的问题。一个可靠的解决办法是，避免使用index.md作为导航的终端页面。比如，把/about/index.md改名为/about/me.md，然后导航链接指向/about/me，这样激活状态就稳了。或者，确保你的侧边栏配置也正确地关联到了这个路径。
5. 侧边栏与全局配置：构建内容骨架的协同作战
导航栏是横向的通道，侧边栏则是纵向的内容地图，对于文档型博客尤其重要。侧边栏的配置在themeConfig.sidebar里，它的结构比导航栏稍复杂一些，因为它需要表达层级关系。
最简单的侧边栏是一个数组，每个元素代表一个导航组。每个组有text（组标题）和items（组内链接列表）。items里的每个链接对象，除了text和link，还有一个很常用的属性collapsed，用于控制这个组默认是展开还是折叠。对于内容很多的文档，我习惯将非核心章节默认折叠起来，保持界面清爽。
更常见的需求是根据不同的路径（路由）显示不同的侧边栏。VitePress支持以对象形式配置sidebar，键是路径前缀，值是对应的侧边栏配置数组。这简直是大型文档站的福音。比如：
// .vitepress/config.js export default { themeConfig: { sidebar: { '/guide/': [ { text: '入门指南', items: [ { text: '快速开始', link: '/guide/getting-started' }, { text: '配置详解', link: '/guide/configuration' } ] } ], '/reference/': [ { text: 'API 参考', items: [ { text: 'CLI 命令', link: '/reference/cli' }, { text: '运行时 API', link: '/reference/runtime-api' } ] } ] } } }这样，当用户访问/guide/下的页面时，看到的是“入门指南”侧边栏；访问/reference/下的页面时，则切换到“API 参考”侧边栏。你可以把不同侧边栏的配置也拆分成单独的文件（比如sidebar-guide.js,sidebar-reference.js），然后在主配置文件中导入并组装，管理起来井井有条。
导航栏和侧边栏需要协同工作。通常，导航栏的一级项（或下拉项）会对应一个大的内容板块，而这个板块下的详细目录则由侧边栏来展示。在规划时，最好先画一个简单的站点结构图，明确哪些是顶级分类（放导航栏），哪些是子分类和文章（放侧边栏）。这样配置起来思路清晰，用户体验也会更好。
最后，别忘了还有一些有用的全局配置可以提升体验。比如themeConfig.lastUpdatedText可以自定义“最后更新”显示的文字；themeConfig.editLink可以配置“编辑此页”的链接，指向你的GitHub仓库对应文件，方便读者贡献内容。这些细节都能让你的博客显得更专业、更友好。把这些配置都打磨好，你的VitePress博客就有了坚实、好用的内容骨架，接下来就是往里面填充优质内容了。
