- 教程
- 文档
【免费下载链接】easy-vibe
从 0 到 1 学会 vibe coding,项目制学习
本篇技术指南围绕 easy-vibe 项目(Datawhale 出品的"从 0 到 1 学会 vibe coding"项目制教程)附录中《前端项目架构原理》一文展开,系统讲解前端项目架构如何随项目规模与技术复杂度演进:从个人博客级的 HTML/CSS/JS 单页,到中小型企业的 Vue/React 工程化项目,再到大型平台的微前端与 Monorepo 架构。读完本文,你将掌握三级架构的选型依据、各层级推荐的目录结构与代码组织原则,并能结合 easy-vibe 仓库中的真实示例(examples 目录下的入门级游戏、工程化 3D 游戏项目)理解每一级架构在实际代码中的落地形态。
1. 架构演进:从简单到复杂
前端项目的架构应当与项目复杂度相匹配。easy-vibe 将项目划分为三个复杂度级别,划分依据是两个核心维度:技术复杂度与用户规模。
| 级别 | 技术栈 | 用户规模 | 典型场景 | 核心关注点 |
|---|---|---|---|---|
| 入门级 | HTML/CSS/JS | 个人/小团队 | 个人博客、宣传页、简单工具 | 快速上线、简单维护 |
| 进阶级 | Vue/React + 构建工具 | 中小型企业 | 管理系统、电商前台、SaaS | 组件复用、状态管理 |
| 企业级 | 框架 + 微前端/SSR | 大型应用 | 大型平台、复杂业务系统 | 性能优化、团队协作、可扩展性 |
选择原则只有一条:不要过度设计。很多项目从简单的 HTML 开始,随着需求增长逐步引入框架和工具:
- 个人项目 → 入门级
- 创业公司 MVP → 入门级或进阶级
- 企业管理系统 → 进阶级
- 大型互联网平台 → 企业级
这一点在 easy-vibe 的课程设计中体现得很明显:阶段一(docs/zh-cn/stage-1)要求学员用 AI 从零构建原型,大量作业(如 trae-block-game)直接以单个 HTML 文件交付;而到了阶段二(docs/zh-cn/stage-2/frontend),课程内容全面转向 Vue 工程化、组件库、设计稿转代码等进阶主题。这正是"先简单、随需求演进"思想的课程化表达。
2. 入门级:HTML/CSS/JS 项目
2.1 适用场景
- 个人博客、简历页面
- 产品宣传页(Landing Page)
- 简单的工具页面(计算器、转换器等)
- 原型验证、快速 Demo
入门级项目的核心诉求是快速上线、简单维护,因此不引入任何构建工具、框架或包管理器,浏览器直接打开即可运行。
2.2 推荐目录结构
my-simple-project/ ├── index.html # 首页 ├── about.html # 关于页面(如有) ├── css/ │ ├── reset.css # 重置样式 │ ├── variables.css # CSS 变量(颜色、字体等) │ ├── components.css # 组件样式(按钮、卡片等) │ └── main.css # 主样式文件 ├── js/ │ ├── utils.js # 工具函数 │ ├── api.js # 简单的 API 调用 │ └── main.js # 主逻辑 ├── assets/ │ ├── images/ # 图片资源 │ └── fonts/ # 字体文件 └── README.md # 项目说明这个结构的关键在于按文件类型(type)分目录:样式统一进css/,脚本统一进js/,静态资源统一进assets/。目录虽小,却为后续升级到框架项目保留了清晰的迁移边界——css/variables.css对应框架项目的主题变量,js/api.js对应框架项目的services/层。
2.3 代码组织原则
HTML:语义化标签,清晰的结构
<!-- index.html --> <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>我的个人博客</title> <link rel="stylesheet" href="css/reset.css"> <link rel="stylesheet" href="css/variables.css"> <link rel="stylesheet" href="css/components.css"> <link rel="stylesheet" href="css/main.css"> </head> <body> <header class="site-header"> <nav class="main-nav"> <a href="index.html">首页</a> <a href="about.html">关于</a> </nav> </header> <main class="content"> <article class="blog-post"> <h1>文章标题</h1> <p>文章内容...</p> </article> </main> <footer class="site-footer"> <p>© 2024 我的博客</p> </footer> <script src="js/utils.js"></script> <script src="js/main.js"></script> </body> </html>CSS:使用 CSS 变量管理主题
/* variables.css */ :root { --primary-color: #3498db; --text-color: #333; --bg-color: #fff; --spacing-sm: 8px; --spacing-md: 16px; --spacing-lg: 24px; --font-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; } /* components.css - 可复用的组件样式 */ .btn { padding: var(--spacing-sm) var(--spacing-md); border: none; border-radius: 4px; background: var(--primary-color); color: white; cursor: pointer; } .card { padding: var(--spacing-md); border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }JavaScript:模块化组织(ES6 modules 或简单拆分)
// utils.js const utils = { // 简化 DOM 操作 $(selector) { return document.querySelector(selector); }, // 简单防抖(debounce) debounce(fn, delay) { let timer; return function(...args) { clearTimeout(timer); timer = setTimeout(() => fn.apply(this, args), delay); }; }, // 本地存储封装 storage: { get(key) { return JSON.parse(localStorage.getItem(key) || 'null'); }, set(key, value) { localStorage.setItem(key, JSON.stringify(value)); } } }; // main.js document.addEventListener('DOMContentLoaded', () => { // 页面初始化逻辑 initNavigation(); loadBlogPosts(); });2.4 最佳实践
✅应该做:
- 使用语义化 HTML 标签
- 用 CSS 变量管理颜色和间距
- 压缩图片并使用懒加载(lazy loading)
- 添加基础的 SEO 标签
❌应该避免:
- 内联样式(
style="...") - 污染全局变量
- 重复代码(复制粘贴)
2.5 仓库实证:入门级单文件到目录化拆分
easy-vibe 的 examples/trae-block-game/index.html 是一个典型的入门级产物:一个完整的"方块小游戏"被封装在单个 HTML 文件中,CSS 通过<style>内联、JS 通过<script>内联,浏览器直接打开即可游玩。从源码看(index.html),该文件包含:
- 页头区域:
#title、#gameContainer(画布 + 物品栏#hotbar)、#info操作说明; - 游戏逻辑以 IIFE(立即执行函数)包裹,将
BLOCKS(方块类型枚举)、BLOCK_COLORS(配色表)、genWorld()(地形生成)、updatePlayer()(物理与碰撞)、render()(渲染循环)等逻辑收拢在独立函数内,避免污染全局变量——这正是第 2.4 节"避免污染全局变量"原则的实践。
当这个单文件项目需要增长时(增加配置页、多关卡、音效资源),按照 2.2 节的目录结构拆分为css/、js/、assets/就是最自然的下一步;而当交互复杂度进一步提升,就需要引入框架,进入下一级别。
3. 进阶级:Vue/React 框架项目
3.1 适用场景
- 企业管理系统(ERP、CRM、OA)
- 电商前台与后台
- SaaS 应用
- 需要复杂交互的 Web 应用
进阶级项目的标志是引入框架 + 构建工具(Vite/Webpack),核心关注点转为组件复用与状态管理。
3.2 推荐 Vue 项目结构
my-vue-project/ ├── public/ # 静态资源 │ ├── index.html │ └── favicon.ico ├── src/ │ ├── assets/ # 样式、图片、字体 │ │ ├── styles/ │ │ │ ├── variables.scss │ │ │ ├── mixins.scss │ │ │ └── global.scss │ │ └── images/ │ ├── components/ # 通用组件 │ │ ├── common/ # 跨业务通用组件(Button、Modal 等) │ │ │ ├── Button/ │ │ │ │ ├── index.vue │ │ │ │ └── Button.scss │ │ │ └── Modal/ │ │ └── business/ # 业务组件(UserCard 等) │ ├── views/ # 页面组件 │ │ ├── Home/ │ │ ├── User/ │ │ │ ├── List.vue │ │ │ └── Detail.vue │ │ └── Product/ │ ├── router/ # 路由配置 │ │ └── index.js │ ├── stores/ # 状态管理 Pinia/Vuex │ │ ├── user.js │ │ └── app.js │ ├── services/ # API 服务 │ │ ├── request.js # axios 封装 │ │ ├── user.js │ │ └── product.js │ ├── utils/ # 工具函数 │ │ ├── format.js │ │ ├── validate.js │ │ └── storage.js │ ├── composables/ # 组合式函数 │ │ ├── useAuth.js │ │ └── useLoading.js │ ├── constants/ # 常量定义 │ │ └── index.js │ ├── App.vue │ └── main.js ├── tests/ # 测试文件 ├── .env # 环境变量 ├── vite.config.js ├── package.json └── README.md3.3 推荐 React 项目结构
my-react-project/ ├── public/ ├── src/ │ ├── assets/ │ ├── components/ │ │ ├── common/ # 通用组件 │ │ │ ├── Button/ │ │ │ │ ├── index.jsx │ │ │ │ └── Button.module.css │ │ │ └── Modal/ │ │ └── business/ # 业务组件 │ ├── pages/ # 页面组件 │ │ ├── Home/ │ │ ├── User/ │ │ └── Product/ │ ├── hooks/ # 自定义 Hooks │ │ ├── useAuth.js │ │ └── useFetch.js │ ├── services/ # API 服务 │ │ ├── api.js │ │ └── userService.js │ ├── store/ # 状态管理 Redux/Zustand │ │ ├── slices/ │ │ └── index.js │ ├── utils/ │ ├── constants/ │ ├── App.jsx │ └── main.jsx ├── tests/ └── package.json对比可见,Vue 与 React 工程化的目录哲学高度一致:components/(common 通用 + business 业务)、页面视图层、状态层(stores/vsstore/)、服务层(services/)、工具与常量层一应俱全,只是命名习惯不同(views/vspages/、composables/vshooks/)。
3.4 核心概念详解
组件设计原则:单一职责
单一职责(Single Responsibility):每个组件只做一件事。这是组件复用的前提。
<!-- ❌ 反面示例:组件做了太多事情 --> <template> <div> <form @submit="handleSubmit"> <!-- 表单内容 --> </form> <table> <!-- 数据表格 --> </table> <div class="charts"> <!-- 统计图表 --> </div> </div> </template> <!-- ✅ 正面示例:拆分为独立组件 --> <template> <div> <UserForm @submit="fetchData" /> <UserTable :data="users" /> <UserStats :data="users" /> </div> </template>拆分的收益是双向的:UserForm、UserTable、UserStats各自可独立测试、独立复用,且通过 props/events 的显式契约通信,耦合度显著下降。
状态管理策略
不同性质的状态应存放在不同层级,避免"所有状态一股脑进全局 Store":
| 状态类型 | 存放位置 | 示例 |
|---|---|---|
| 全局状态 | Pinia/Redux | 用户信息、登录状态、主题设置 |
| 页面状态 | 页面组件内 | 列表筛选条件、分页信息 |
| 组件状态 | 组件内部 | 表单输入、弹窗显隐 |
| 服务端状态 | TanStack Query/SWR | 服务端数据、缓存 |
关键判断:只有被多个无关组件共享、或需要跨页面持久化的状态,才值得放进全局 Store;页面局部状态留在页面组件,纯展示状态留在组件内部;服务端数据则应交给专门的请求缓存方案,而不是手工塞进 Store。
目录组织方式的选择
方式一:按类型组织(适合小项目)
src/ ├── components/ # 所有组件 ├── views/ # 所有页面 ├── stores/ # 所有状态 └── services/ # 所有服务方式二:按功能组织(适合中大型项目)
src/ ├── features/ │ ├── auth/ # 认证相关所有代码 │ ├── user/ # 用户相关所有代码 │ └── product/ # 商品相关所有代码 ├── shared/ # 共享资源 └── App.vue选择标准:
- 项目页面数 < 10 → 按类型组织
- 项目页面数 > 20 → 按功能组织
- 团队规模 > 5 人 → 按功能组织,便于并行开发
按功能组织的本质是把"一个业务域"的组件、页面、状态、服务收拢在同一目录,降低跨目录跳转成本;当多人并行开发不同业务域时,冲突面也最小。
3.5 仓库实证:Vite 工程化项目的真实形态
easy-vibe 的 examples/trae-3d-block-game 是进阶级架构的完整样例:一个基于 Three.js 的 3D 方块游戏,同时支持 Web 与 Electron 桌面端,其工程化配置与 3.2/3.3 节的目录思想完全对应。
从 vite.config.js 可以看到关键工程化配置:
export default defineConfig({ root: 'src', // 以 src/ 为项目根目录 base: './', // 相对路径打包,便于静态托管 build: { outDir: '../dist', // 产物输出到 dist/ emptyOutDir: true, rollupOptions: { input: { main: resolve(__dirname, 'src/index.html') } } }, server: { port: 5173, // 开发服务器端口 open: true // 启动自动打开浏览器 } })而 package.json 则体现了进阶级项目"脚本化管理"的特征:
"scripts": { "dev:web": "vite", "build:web": "vite build", "dev:electron": "vite build && electron .", "build": "vite build && electron-builder", "build:mac": "vite build && electron-builder --mac", "build:win": "vite build && electron-builder --win", "build:linux": "vite build && electron-builder --linux" }源码组织上(examples/trae-3d-block-game/src),index.html(页面骨架)、styles.css(全局样式)、main.js(Three.js 主逻辑)按类型分目录存放——这是"按类型组织"在小规模工程中的合理形态。依赖上,three作为运行时依赖、vite/electron/electron-builder作为开发依赖分离(package.json),构建产物与多平台打包目标(mac 的 dmg/zip、win 的 nsis/zip、linux 的 AppImage/zip)也都在配置中明确声明,体现了进阶级项目对构建链路的完整管理。
4. 企业级:大型应用架构
4.1 适用场景
- 大型互联网平台(电商、社交、内容平台)
- 复杂企业应用
- 需要支撑多团队协作的项目
- 对性能与可维护性要求高的项目
4.2 微前端架构(Micro-Frontend)
当项目体量达到"单一代码仓库难以维护"的程度,可以考虑微前端架构:由一个基座应用(框架主应用)承载公共壳层,多个子应用独立开发、独立部署。
大型电商平台/ ├── 基座应用(主框架) │ ├── 顶部导航栏 │ ├── 侧边菜单 │ ├── 用户中心入口 │ └── 子应用容器 ├── 商品子应用(独立部署) │ ├── 商品列表 │ ├── 商品详情 │ └── 商品管理 ├── 订单子应用(独立部署) │ ├── 购物车 │ ├── 订单列表 │ └── 结算流程 ├── 用户子应用(独立部署) │ ├── 个人中心 │ ├── 收货地址 │ └── 优惠券 └── 营销子应用(独立部署) ├── 活动页面 ├── 优惠券发放 └── 积分商城微前端优势:
- 团队自治:每个子应用由独立团队开发、部署,互不阻塞
- 技术栈独立:不同团队可以选用不同的框架
- 渐进式升级:老旧系统可以逐个模块渐进重构
4.3 企业级目录:Monorepo
微前端通常与 Monorepo 配合,将多个子应用与共享包纳入一个仓库统一管理:
enterprise-project/ ├── apps/ # 微前端子应用 │ ├── main/ # 基座应用 │ ├── product/ │ ├── order/ │ └── user/ ├── packages/ # 共享包(Monorepo) │ ├── ui-components/ # 通用组件库 │ ├── utils/ # 工具函数 │ ├── constants/ # 常量定义 │ └── types/ # TypeScript 类型 ├── shared/ # 共享配置 │ ├── eslint-config/ │ ├── ts-config/ │ └── vite-config/ ├── docs/ # 项目文档 ├── scripts/ # 构建脚本 └── package.jsonapps/与packages/的分隔是 Monorepo 的核心:apps/是可独立部署的应用,packages/是被多个应用共享的库。组件库、工具函数、常量、类型定义被抽为共享包后,跨应用复用不再依赖复制粘贴。
4.4 性能优化架构
大型应用必须在"构建时"和"运行时"两个阶段持续优化:
性能优化策略/ ├── 构建时优化 │ ├── 代码分割(Code Splitting) │ ├── 路由懒加载 │ ├── Tree Shaking │ └── 资源压缩 ├── 运行时优化 │ ├── 虚拟滚动(长列表) │ ├── 图片懒加载 │ ├── 组件按需渲染 │ └── 缓存策略 └── 网络优化 ├── CDN 加速 ├── HTTP 缓存 ├── 资源预加载 └── Service Worker其中"路由懒加载"与"代码分割"在 Vite/Rollup 体系中由构建工具原生支持(如 3.5 节 vite.config.js 中的rollupOptions.input多入口配置即为入口级代码分割);"图片懒加载"则对应入门级章节中 2.4 节的进阶形态。
4.5 SSR/SSG 架构
对于需要 SEO 或首屏渲染速度的场景,引入服务端渲染方案:
| 方案 | 适用场景 | 代表框架 |
|---|---|---|
| SSR | 需要 SEO、首屏渲染快 | Next.js、Nuxt.js |
| SSG | 静态内容、更新不频繁 | Astro、VitePress |
| 混合 | 部分静态、部分动态 | Next.js(ISR) |
4.6 仓库实证:easy-vibe 文档站本身的企业级组织
easy-vibe 仓库本身就是企业级前端架构思想的产物:
- 多应用/多包视角:站点基于 VitePress(package.json 中的
vitepress、vue、element-plus、mermaid、reveal.js等依赖),采用多语言多站点结构——docs/下同时维护zh-cn、en、ar-sa、de-de、es-es、fr-fr、ja-jp、ko-kr、vi-vn、zh-tw十余个语言目录,每个语言目录拥有独立的 appendix 体系与 stage-0/1/2/3 课程结构; - 共享主题组件:docs/.vitepress/theme/components 下集中维护
AppendixFlowMap.vue、ArticleCard.vue、Tabs.vue、ReadingProgress.vue等全局共享组件,对应 4.3 节packages/ui-components的思路; - 架构可视化组件:ArchitectureComparisonDemo.vue 是本文主题的直接配套交互组件——它以分层卡片渲染前端(
frontendLayers)与后端(backendLayers)的架构层次,并支持点击切换活动层(ArchitectureComparisonDemo.vue),说明本课程的"前端架构"教学不仅有文字理论,还有仓库内可交互的源码级演示; - 侧边栏数据驱动:站点导航通过 docs/.vitepress/sidebars/index.mjs 与
data.mjs以数据文件形式统一管理,正文与目录解耦——这正是大型站点"文档即数据"的组织实践。
此外,easy-vibe 的构建脚本体系(package.json 中的build、sitemap、book:pdf、book:epub等)也展示了"scripts/ 构建脚本"在企业级仓库中的角色:静态站点、PDF 书籍、EPUB 电子书共用同一套 Markdown 源,通过脚本层输出多种交付物。
5. 按用户规模选择架构
架构不仅取决于技术复杂度,还取决于活跃用户规模。easy-vibe 给出了三档参考:
5.1 个人/小团队(日活 < 1000)
- 特点:快速迭代、资源有限、需求变化快
- 推荐架构:
- 技术栈:Vue 3 + Vite 或 React + Vite
- 状态管理:Pinia 或 Zustand(轻量)
- UI 库:Element Plus / Ant Design
- 部署:Vercel / Netlify / 云服务器
- 目录结构:简单的按类型组织即可
5.2 中型企业(日活 1k-100k)
- 特点:业务复杂、团队协作、需要稳定
- 推荐架构:
- 技术栈:Vue 3 + TypeScript 或 React + TypeScript
- 状态管理:Pinia + 组合式函数 或 Redux Toolkit
- UI 库:自建组件库 + 业务组件库
- 测试:单元测试 + E2E 测试
- 部署:CI/CD 流水线 + Docker
- 目录结构:按功能组织,建立规范
5.3 大型平台(日活 > 100k)
- 特点:高并发、多团队协作、长期维护
- 推荐架构:
- 技术栈:React/Vue + TypeScript(严格模式)
- 架构:微前端 + Monorepo
- 状态管理:精细化状态管理 + 服务端状态缓存
- 性能:SSR/SSG + CDN + 边缘计算
- 监控:前端监控 + 错误追踪 + 性能分析
- 目录结构:Monorepo + 微前端
需要说明的是,这里的日活分档是教程给出的经验性参考值,实际选型还应结合团队规模、业务复杂度与迭代节奏综合判断,避免"唯用户量论"。
6. 架构演进路线图
6.1 演进示例:从博客到平台
阶段 1:个人博客(HTML/CSS/JS) ↓ 需求:后台管理 阶段 2:增加管理后台(Vue/React + 简单结构) ↓ 需求:用户体系、评论功能 阶段 3:功能模块化(按功能组织) ↓ 需求:多团队协作、独立部署 阶段 4:微前端架构(Monorepo)每一步演进都应当由真实需求驱动,而不是"别人都在用"。例如 easy-vibe 的 examples/trae-block-game(单文件 HTML)演进到 examples/trae-3d-block-game(Vite + Three.js + Electron 工程化项目),中间的驱动力是明确且可观察的:3D 渲染需要引入three依赖、桌面端需要 Electron 打包、多平台构建需要electron-builder——这些需求一旦出现,工程化升级就顺理成章。
6.2 需要升级架构的信号
| 信号 | 描述 | 建议 |
|---|---|---|
| 构建时间 > 5 分钟 | 项目过于庞大 | 代码分割、微前端 |
| 多人频繁冲突 | 协作困难 | 按功能组织、模块拆分 |
| 改一处坏多处 | 耦合度过高(Coupling) | 重构、加强测试 |
| 首屏加载 > 3 秒 | 性能问题 | 懒加载、SSR、优化 |
| 新成员上手慢 | 结构混乱 | 文档、规范、重构 |
这五个信号覆盖了工程化的五个维度:构建效率、协作效率、代码质量、用户体验、团队可维护性。任何一项亮起红灯,都意味着架构需要"向前走一步"。
7. 总结
架构没有银弹,合适的才是最好的。
- 小项目不要过度设计,HTML/CSS/JS 足够
- 中项目建立规范、组件化、模块化
- 大项目考虑微前端、性能优化、团队协作
贯穿始终的四条原则:
- 渐进式演进:从简单开始,随需求增长逐步演进
- 规范统一:保持命名、结构、代码风格一致
- 文档先行:记录架构决策,便于传承
- 定期重构:及时偿还技术债
最终目标:让代码像一间整理有序的空间,无论大小,都能高效运转。
在 easy-vibe 仓库中,这条演进路线是可以亲手触摸的:从 examples/trae-block-game/index.html 的单文件 HTML,到 examples/trae-3d-block-game 的 Vite 工程化项目,再到 docs/.vitepress 下多语言文档站的企业级组织,三级架构的每个层次都有真实代码可对照。建议读者按照"先跑通入门级示例 → 改造为工程化项目 → 用升级信号评估是否进入企业级"的顺序,在实际项目中逐步验证这套架构方法论。
- 教程
- 文档
【免费下载链接】easy-vibe
从 0 到 1 学会 vibe coding,项目制学习
相关推荐
前端项目架构实战指南:从 HTML/CSS/JS 到企业级微前端的演进路线(easy-vibe 课程详解)
前端项目架构实战指南:从 HTML/CSS/JS 到企业级微前端的演进路线(easy vibe 课程详解) 导读 :本篇技术指南系统讲解前端项目架构如何随项目规
教程文档人工智能Vibe CodingEasy-Vibe 前端项目架构指南:从 HTML 单页到企业级微前端的渐进式选型
Easy Vibe 前端项目架构指南:从 HTML 单页到企业级微前端的渐进式选型 导读 前端项目该用多复杂的架构?从个人博客的单 HTML 页面,到承载数十万
教程文档easy-vibe 前端项目架构实战指南:从 HTML/CSS/JS 到微前端与 SSR 的分级演进方案
easy vibe 前端项目架构实战指南:从 HTML/CSS/JS 到微前端与 SSR 的分级演进方案 本文是 easy vibe 前端技术体系(浏览器与前端
教程文档人工智能Vibe Coding
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考