企业官网建设流程全解析

如何克隆 easy-vibe 仓库并在本地第一次跑通 VitePress 文档站

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

easy-vibe（Easy-Vibe）是一个基于 VitePress 的文档站项目，内容是"vibe coding 101"课程的多语言教程。如果你克隆了这个仓库，通常的目标是在本机把文档站跑起来：看到首页、能切换语言和侧边栏、能正常浏览各个章节。这条路径只需要四步：确认 Node 版本、克隆仓库、安装依赖、启动开发服务器，然后按文档给出的方式验证页面可访问。

准备工作：确认 Node.js 版本

仓库 package.json 在engines字段中声明了"node": ">=18.0.0"，AGENTS.md 也明确写道：本项目是 VitePress（Vue 3）文档项目，Requires Node.js>= 18。启动前请先确认本机 Node.js 版本不低于 18，否则依赖安装或构建可能失败。

克隆仓库并进入目录

git clone https://gitcode.com/GitHub_Trending/ea/easy-vibe cd easy-vibe

克隆完成后，文档站源码位于docs/目录（Markdown 内容、多语言站点目录、docs/.vitepress/配置与主题都在这下面），站点级脚本在 scripts/ 目录，这是后文构建命令会调用到的部分。

安装依赖

在仓库根目录执行：

npm install

这一步会安装 package.json 中的依赖，其中与本地运行直接相关的是vitepress（^2.0.0-alpha.16）和vue（^3.5.0）。首次运行只需执行一次。

启动开发服务器

npm run dev

dev脚本的实际内容是vitepress dev docs（见 package.json），即以docs/为根启动 VitePress 开发服务器，AGENTS.md 将其描述为"start local docs server (hot reload)"，编辑文档后页面会自动热更新。

服务器启动后，用浏览器打开终端中打印的 Local 地址。关于端口，仓库文档之间存在两处不同说法：

• README.md 的 "Run Locally" 章节写的是http://localhost:3000；
• CLAUDE.md 写的是http://localhost:5173（VitePress 默认端口），docs/DEPLOYMENT.md 的环境对照表同样列出本地开发地址形如http://localhost:5173/easy-vibe/en/stage-1/...。

以终端实际输出的 URL 为准。

验证站点是否正常跑通

本地开发环境的 base 路径为/easy-vibe/。判断逻辑在 docs/.vitepress/config.mjs：设置了BASE环境变量时优先使用；检测到 Vercel 或 EdgeOne 环境时用/；否则（包括本地开发）使用/easy-vibe/。因此本地访问课程页面时，路径需要带上这个前缀，例如http://localhost:5173/easy-vibe/或任意语言目录下的章节页。

验证时可以依次确认 docs/DEPLOYMENT.md 中"Post-Deploy Checklist"列出的检查项：

• 首页能加载；
• 顶部导航栏链接可以正常跳转；
• 语言切换可用（站点包含 zh-cn、en、zh-tw、ja-jp、ko-kr、es-es、fr-fr、de-de、ar-sa、vi-vn 等多语言目录）；
• 图片能正常显示。

以上检查项在 docs/DEPLOYMENT.md 中是针对部署后验收给出的，本地第一次跑通时同样适用，用来确认整站资源加载没有缺失。

可选：构建生产版本并本地预览

如果你想验证"构建后的站点"而不是开发服务器，CLAUDE.md 给出的流程是：

npm run build npm run preview

两点需要注意：

• npm run build实际执行的是 scripts/build-locales.mjs，它会按语言逐个构建并合并输出到docs/.vitepress/dist，构建时间比单语言构建长；
• 本地预览地址按 docs/DEPLOYMENT.md 的对照表为http://localhost:4173/easy-vibe/...，base 同样是/easy-vibe/。

遇到常见 404 时

docs/DEPLOYMENT.md 给出了两条与 base 路径相关的排查结论，本地或部署后遇到整站 404、路径带/easy-vibe/却打不开时可以参考：

• 原因是 base 路径不匹配：非 Vercel/EdgeOne 环境下 base 应为/easy-vibe/；
• 如果自定义了BASE环境变量，它以最高优先级生效，检查该值是否指向了你实际部署或访问的路径。

仓库是文档型项目，AGENTS.md 指出本仓库没有专门的测试框架，npm run build是主要正确性检查手段。本地第一次跑通后，后续编辑docs/下的内容时用npm run dev热更新验证即可。

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