Vue 完整项目实战：从 0 搭建一个组件化和路由的现代前端应用

作者：袖梨 2026-06-20

前言

前面我们学习了 Vue 的响应式数据、ref、Todos 任务清单，但这些都是在单文件里完成的。

Vue 完整项目实战：从 0 搭建一个组件化 + 路由的现代前端应用

今天我们来做一个真正的 Vue 项目——一个拥有多页面、路由导航、组件化架构的现代前端应用。

这个项目虽然小，但它麻雀虽小五脏俱全，涵盖了 Vue 3 项目开发的核心骨架：

  • Vite 构建工具：现代前端工程化的基石
  • Vue Router：前端路由，实现无刷新页面切换
  • 组件化架构：App.vue + views 目录结构
  • ESM 模块化：import/export 的现代 JS 规范

完整项目链接：gitee.com/hong-strong…

一、项目结构：一个 Vue 项目的"五脏六腑"

 复制代码all-vue/
├── public/
│   └── favicon.svg
├── src/
│   ├── router/
│   │   └── index.js        # 路由配置
│   ├── views/
│   │   ├── Home.vue         # 首页组件
│   │   └── About.vue        # 关于页组件
│   ├── App.vue              # 根组件
│   ├── main.js              # 入口文件
│   └── style.css            # 全局样式
├── index.html               # HTML 入口
├── package.json
└── vite.config.js           # Vite 配置
文件/目录职责类比
index.html整个应用的 HTML 入口房子的地基
main.jsJS 入口，创建 Vue 应用实例房子的总开关
App.vue根组件，包裹所有页面房子的框架
router/index.js路由配置，决定 URL 对应哪个页面房子的门牌号
views/*.vue具体的页面组件房子的各个房间
style.css全局样式房子的装修风格
vite.config.js构建工具配置施工图纸

二、HTML 入口：一切的起点

 复制代码<!-- index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>all-vue</title>
  </head>
  <body>
    <!-- 组件的挂载点 -->
    <div id="app"></div>
    <!-- vue 基于最新的 ESM，type="module" -->
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

逐行解析：

 复制代码<div id="app"></div>
  • 这是一个空的 div，它是 Vue 应用的挂载点
  • Vue 会把整个 App.vue 组件渲染到这个 div 里
  • 页面里其他的 HTML 内容都会被 Vue 接管
 复制代码<script type="module" src="/src/main.js"></script>
  • type="module" 表示使用 ESM（ES Modules） 规范
  • 这是 ES6 引入的模块化标准，支持 import/export
  • 为什么用 ESM？ 因为 Vite 基于原生 ESM 开发，浏览器直接解析模块，无需打包，所以开发时启动极快

三、入口文件 main.js：Vue 应用的"总开关"

 复制代码// main.js
import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
import router from './router';createApp(App)
  .use(router)  // 启用路由
  .mount('#app') // 挂载到 #app

逐行解析：

 复制代码import { createApp } from 'vue'
  • 从 vue 包中引入 createApp 函数
  • Vue 3 使用 createApp 创建应用实例（Vue 2 是 new Vue()）
  • 这是一个工厂函数，返回一个应用实例对象
 复制代码import './style.css'
  • 引入全局样式，Vite 会处理 CSS 的加载
  • 这个样式对整个应用的所有组件生效
 复制代码import App from './App.vue'
  • 引入根组件 App.vue
  • .vue 文件是 Vue 的单文件组件（SFC），包含 <template>、<script>、<style> 三部分
 复制代码import router from './router';
  • 引入我们定义的路由实例
  • 路由是一个独立的模块，负责 URL 和页面的映射
 复制代码createApp(App)
  .use(router)
  .mount('#app')
  • createApp(App)：以 App.vue 为根组件创建应用实例
  • .use(router)：安装路由插件，让应用具备路由能力
  • .mount('#app')：将整个 Vue 应用挂载到 id="app" 的 DOM 元素上
  • 链式调用：.use() 返回的仍然是应用实例，所以可以继续 .mount()

四、路由配置：URL 和页面的"门牌号"

 复制代码// router/index.js
import {
  createRouter,        // 创建路由实例
  createWebHashHistory // 路由模式
} from 'vue-router';
import Home from '../views/Home.vue';
import About from '../views/About.vue';const routes = [
  {
    path: '/',           // URL 路径
    name: 'Home',        // 路由名称（可选，用于命名导航）
    component: Home      // 对应的组件
  },
  {
    path: '/about',
    name: 'About',
    component: About
  }
];const router = createRouter({
  history: createWebHashHistory(), // Hash 模式
  routes                           // 路由配置
})export default router;

逐行解析：

 复制代码import { createRouter, createWebHashHistory } from 'vue-router';
  • createRouter：创建路由实例的工厂函数
  • createWebHashHistory：使用 Hash 路由模式，URL 形如 
 复制代码const routes = [...]
  • 路由配置数组，每一项定义了一个 URL → 组件 的映射
  • path：URL 路径，/ 表示根路径
  • name：路由名称，可用于 router.push({ name: 'Home' }) 编程式导航
  • component：路径匹配时渲染的组件
 复制代码history: createWebHashHistory()
  • Vue Router 支持两种模式：
模式APIURL 格式特点
Hash 模式createWebHashHistory()/#/about不需要服务器配置，兼容性好
History 模式createWebHistory()/aboutURL 更美观，需要服务器配置

五、根组件 App.vue：所有页面的"容器"

 复制代码<!-- App.vue -->
<script setup></script><template>
  <div>
    <header>
      <nav>
        <ul>
          <!-- router-link 是 vue-router 提供的全局组件 -->
          <li><router-link to="/">Home</router-link></li>
          <li><router-link to="/about">About</router-link></li>
        </ul> 
      </nav>
    </header>
    <main>
      <!-- 路由匹配到的组件会渲染在这里 -->
      <router-view></router-view>
    </main>
    <footer>
    </footer>
  </div>
</template><style scoped></style>

逐行解析：

 复制代码<router-link to="/">Home</router-link>
  • router-link 是 vue-router 注册的全局组件
  • 渲染后会变成 <a href="#/">Home</a>
  • to 属性指定目标路径，支持字符串和对象两种写法
  • 核心优势： 点击时不会刷新页面，而是通过 JS 切换路由，实现无刷新跳转
 复制代码<router-view></router-view>
  • 这是路由的出口，匹配到的页面组件会渲染在这里
  • 访问 /#/ 时，渲染 Home.vue
  • 访问 /#/about 时，渲染 About.vue
  • 它是动态的，随着 URL 的变化，渲染不同的组件

六、页面组件：views 目录下的各个"房间"

 复制代码<!-- views/Home.vue -->
<template>
  <div>Home</div>
</template>

 复制代码<!-- views/About.vue -->
<template>
  <div>About</div>
</template>

这两个是最简单的页面组件，只有 <template> 部分。

Vue 单文件组件（SFC）的三种写法：

写法示例适用场景
只有 template<template>...</template>纯展示型页面
template + script<template>...</template><script setup>...</script>有交互逻辑的页面
template + script + style完整三件套有独立样式的页面

七、全局样式：CSS 变量 + 暗黑模式

 复制代码/* style.css */
:root {
  --text: #6b6375;
  --bg: #fff;
  --accent: #aa3bff;
  /* ... */
  color-scheme: light dark;
}@media (prefers-color-scheme: dark) {
  :root {
    --text: #9ca3af;
    --bg: #16171d;
    --accent: #c084fc;
    /* ... */
  }
}

关键点解析：

 复制代码:root {
  --text: #6b6375;
}
  • :root 是 CSS 的根选择器，匹配 <html> 元素
  • --text 是 CSS 变量（自定义属性），可以在任何地方通过 var(--text) 使用
  • 好处：统一管理颜色，一处修改全局生效
 复制代码@media (prefers-color-scheme: dark) { ... }
  • 这是媒体查询，检测用户的系统主题偏好
  • 当用户开启暗黑模式时，自动切换 CSS 变量的值
  • 无需 JS，纯 CSS 实现暗黑模式

八、Vite 配置：构建工具

 复制代码// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'export default defineConfig({
  plugins: [vue()],
})
  • defineConfig：提供类型提示的配置函数
  • plugins: [vue()]：安装 Vue 插件，让 Vite 能处理 .vue 文件
  • Vite 底层使用 esbuild 做预构建，Rollup 做生产构建，速度极快
构建工具开发服务器生产构建特点
Webpack打包后启动打包生态成熟，配置复杂
Vite原生 ESMRollup启动快，配置简单
Turbopack原生 ESM-Next.js 专用，Rust 实现

九、数据流：从 URL 到页面渲染

 复制代码用户在浏览器访问 #/about
         ↓
浏览器加载 index.html，执行 main.js
         ↓
createApp(App).use(router).mount('#app')
         ↓
Vue Router 解析 URL 中的 hash：/#/about
         ↓
匹配到 routes 中 path: '/about' 的配置
         ↓
渲染 About.vue 组件到 <router-view> 的位置
         ↓
用户看到 "About" 页面

十、完整对比：传统开发 vs Vue 项目

环节传统 DOM 编程Vue 组件化开发
页面切换浏览器刷新，重新请求 HTMLrouter-link 无刷新跳转
组件复用复制粘贴 HTMLimport 引入，直接当标签用
样式隔离全局污染<style scoped> 组件级隔离
路由管理后端路由，每个 URL 一个 HTML前端路由，一个 HTML 动态切换
构建工具不需要Vite/Webpack 处理模块化

总结

这个项目虽然简单，但它搭建起了 Vue 开发的完整骨架：

  1. Vite 提供了极速的开发体验
  2. Vue Router 实现了无刷新的页面切换
  3. 组件化 让代码可复用、可维护
  4. ESM 模块化 让代码结构清晰

相关文章

精彩推荐