企业官网建设流程全解析

Easy-Vibe 德文版首页实践：VitePress Home 布局、多语言路由与 HomeFeatures 主题组件

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

docs/de-de/index.md 是 Easy-Vibe 课程文档站德文版（de-de）的入口文件。它用 VitePress 的home布局配置了一个德语 Hero 区域，并通过自定义主题组件<HomeFeatures />渲染出整站的学习路径卡片、用户故事和语言切换入口。读懂这个文件及其背后的 HomeFeatures.vue、HomeI18n.js 和 config.mjs，你就能掌握一个多语言 VitePress 文档站“入口页 + 自定义首页”的完整实现方式。

一、文件定位：德文版的站点入口

Easy-Vibe 是一个多语言课程站，每种语言对应一个站点子目录：zh-cn、en、de-de、ja-jp、ko-kr等，全部由同一套 VitePress 配置驱动。德文版的入口就是 docs/de-de/index.md，全文只有两段内容：一段 frontmatter 和一行自定义组件标签。这个“短文件”实际上是典型的 VitePress 首页写法——静态元信息放在 frontmatter 里，页面主体交给主题组件动态渲染。

frontmatter 声明layout: home后，VitePress 会启用内置首页布局，并消费其中的hero配置；而页面正文部分没有任何 Markdown 内容，只有一行：

<HomeFeatures />

这表示 Hero 区以下的所有内容（课程阶段卡片、用户故事、页脚等）都由 HomeFeatures.vue 这个 905 行的 Vue 组件承担。下面先逐字段拆解 frontmatter，再看组件内部如何为德语用户提供完整体验。

二、frontmatter 逐字段解析：Hero 区是如何配置的

以下是 docs/de-de/index.md 中完整的 frontmatter，所有德语文案均原样保留：

--- layout: home hero: name: 'Easy-Vibe' text: 'KI-Coding-Guide von Grund auf' tagline: 'Ein neues Coding-Paradigma für alle. Egal ob PM oder Full Stack Dev, finde hier deinen KI-Coding-Pfad.' typingTagline: - Coding, neu gedacht. - Komplexität, vereinfacht. - Jeder Schritt, genau richtig. - Denken. Bauen. - Dein Tempo. AI hält mit. - Vom ersten Zeichen zum kompletten System. - Weniger Reibung. Mehr Kreation. - So sollte Programmieren sich anfühlen. actions: - theme: brand text: Zusammen vibe starten! link: /de-de/stage-1/learning-map/ - theme: alt text: Kursübersicht link: /de-de/stage-1/learning-map/ ---

各字段的作用如下：

几个值得注意的实现细节：

1. typingTagline是 VitePress 特有的扩展字段。标准hero只有name/text/tagline，而typingTagline会让 Hero 副标题区以打字机动画循环播放列表中的每一句文案。这里配置了 8 句德语短句，从“Coding, neu gedacht.”（重新构想编程）到“So sollte Programmieren sich anfühlen.”（编程本该如此），形成一组营销式但技术导向的口号轮播。
2. 两个 action 指向同一个目标：/de-de/stage-1/learning-map/。这说明首页的转化目标非常单一——把所有访客（无论点击“开始 Vibe”还是“课程概览”）都引导到 docs/de-de/stage-1/learning-map/index.md 这份德文学习地图。该文档的 frontmatter 标题为 “So lernst du mit diesem Kurs”（如何使用本课程学习），是 Stage 1 的导读页，正文开头即介绍 Vibe Coding 概念与 Product Engineer 培养路径。
3. 路由全部带/de-de前缀。多语言站点中每个 locale 都挂载在独立的 URL 前缀下，de-de前缀既用于导航路由，也用于 hreflang/OG 语言标记（见下文配置节）。

三、<HomeFeatures />：首页主体的组件化实现

<HomeFeatures />标签引用的是主题目录下的 HomeFeatures.vue（VitePress 约定theme/components下的组件可在任意 Markdown 中以标签形式直接使用）。从源码结构看，这个组件是整站首页的“渲染引擎”，核心机制包括：

3.1 按 locale 加载德语文案

组件顶部通过useData()拿到当前lang，并用内部函数normalizeLocaleCode把语言码归一化后，从 HomeI18n.js 中取出对应语言的文案对象：

const t = computed(() => { const code = normalizeLocaleCode(lang.value) const result = i18n[code] || i18n['en'] result._locale = code return result })

归一化逻辑（源码第 30-39 行附近）会容忍DE-DE、de_de等写法，找不到匹配时回退到en，再兜底zh-cn。HomeI18n.js中的'de-de'文案块（约从第 1196 行开始）就是首页德语内容的“单一数据源”，涵盖：

• 导航项（nav）：Startseite（主页）、Nutzergeschichten（用户故事）、Produktmanager / Junior Dev / Senior Dev（三条角色路径）、Anhang（附录）；
• 用户故事区（stories）：4 个真实用户案例的德语标题与作者，例如 Grundschullehrer（小学教师）帮助乡村儿童用 AI“赶鸟”的故事，以及 Lkw-Fahrer（卡车司机）连夜构建国际 AI 工具站的故事；
• 三个学习阶段的卡片（stage1/stage2/stage3）：
  • Stage 1（Anfänger & PM）：卡片为“KI PM”“Gamifizierte Intro”“Vibe Coding”，链接统一指向/de-de/stage-1/learning-map/；
  • Stage 2（Junior/Mid Dev）：卡片为“Full Stack”“Echte Projekte”“Deployment”，指向/de-de/stage-2/；
  • Stage 3（Senior Dev）：卡片为“WeChat Mini-App”等跨端与 AI 进阶方向，指向/de-de/stage-3/。

这些链接与 docs/de-de/ 目录实际结构一一对应：stage-1/、stage-2/、stage-3/、appendix/、guide/均真实存在，卡片点击后落到对应的德文课程页。

3.2 防止“未翻译页面 404”的安全路由

源码中还有一个与 index 文件直接相关的细节：hasBuiltLocalePath与resolveSafeLocalePath两个函数。它们通过 VitePress 构建时生成的window.__VP_HASH_MAP__检查某个 locale 下某个相对路径是否真的编译进了站点，如果某个德文页面缺失，则把导航安全地降级回/de-de/首页而不是给出 404。这对多语言课程站很关键——不同语言的翻译进度并不一致，入口页必须保证任何情况下导航都可点。

3.3 页签与交互状态

组件用activeTab（默认'home'）管理页签切换，用showLangMenu控制语言切换菜单，另有一组topPromo*状态管理顶部提示条的动画进度。也就是说，德文首页的交互（页签、语言菜单、提示条）都不依赖 index.md，全部由这一个组件自包含地渲染。

四、与站点级配置的联动：localeMap、Base 路径与语言重定向

docs/de-de/index.md并非孤立工作，它依赖三处站点级配置：

4.1 config.mjs 中的德文元数据

docs/.vitepress/config.mjs 定义了每个 locale 的 SEO 元数据，德文条目为：

'de-de': { ogLocale: 'de_DE', twitterSite: '@datawhale', lang: 'de-DE', hreflang: 'de' }

这意味着由docs/de-de/index.md构建出的首页会输出<html lang="de-DE">、og:locale=de_DE以及hreflang=de的 SEO 标签——这正是“让搜索引擎正确理解这个德语首页”的关键一步。同一文件还处理了BASE环境变量与 Vercel/EdgeOne/GitHub Pages 三种部署环境下的 Base 路径和站点 URL（getSiteUrl函数），保证/de-de/前缀路由在任何部署环境下都能正确解析。

4.2 根 index 的语言探测重定向

docs/index.md 是整个站点的根入口，内嵌一段 Vue 脚本：读取navigator.language，通过langMap把浏览器语言映射到对应 locale 路径（其中'de': '/de-de/'、'de-de': '/de-de/'），首次访问且未看过欢迎页时跳转到/welcome?next=<locale路径>，否则直接location.replace到对应语言首页。也就是说，一位浏览器语言为德语的访客，最终落地的正是本文所讲的docs/de-de/index.md渲染出的页面。

4.3 本地开发与构建

从 package.json 可以看到站点（easy-vibe，vitepress ^2.0.0-alpha.16）提供以下命令：

构建脚本还支持VITEPRESS_BUILD_LOCALE/VITEPRESS_BUILD_LOCALES_ACTIVE环境变量按语言选择性构建（config.mjs 中读取），适合像de-de这样按需单独发布的 locale。

五、小结与延伸阅读

docs/de-de/index.md用不到 30 行文件定义了整个德文版首页的“门面”：layout: home+hero（name / text / tagline / typingTagline / actions）负责 Hero 区的静态展示与转化入口，<HomeFeatures />则依托 HomeFeatures.vue 与 HomeI18n.js 中的'de-de'文案块，动态渲染出与 docs/de-de/stage-1/learning-map/index.md、docs/de-de/stage-2/index.md、docs/de-de/stage-3/index.md 等真实课程目录相链接的学习路径卡片。若你想为 Easy-Vibe 新增一种语言，照葫芦画瓢即可：新建docs/<locale>/index.md（复制本文 frontmatter 并翻译）、在HomeI18n.js增加同结构的 locale 块、在config.mjs的localeMap与docs/index.md的langMap中各加一条映射，德文版的这套模式就能完整复刻。

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe