19｜Vue 项目创建与组件结构

原生 JavaScript 操作 DOM 在页面逻辑少时没问题，状态一多就乱了：手动维护列表数据、选中状态、加载标志这些变量，每次数据变了都要找到对应 DOM 更新，忘了一处页面就跟数据对不上。Vue 把这个过程自动化——数据变了页面自动更新，不需要手动操作 DOM。

一、创建 Vue 项目

Vue 官方推荐用 Vite 创建工程：

npm create vite@latest ops-console -- --template vue
cd ops-console
npm install
npm run dev

命令解释：

部分	作用
npm create vite@latest	调用 Vite 官方脚手架
ops-console	项目目录名
-- --template vue	使用 Vue 模板（注意 -- 分隔）
npm run dev	启动开发服务器，默认端口 5173

启动后浏览器打开 http://localhost:5173，修改代码页面自动刷新。

二、目录结构

ops-console/
├── index.html          # 入口 HTML，Vite 自动注入打包后的 JS
├── package.json        # 依赖和脚本
├── vite.config.js      # Vite 配置
└── src/
    ├── main.js         # 入口 JS，创建 Vue 应用并挂载
    ├── App.vue         # 根组件
    ├── components/     # 可复用组件（自建）
    ├── views/          # 页面级组件（自建）
    ├── assets/         # 图片、样式等静态资源（自建）
    └── router/         # 路由配置（自建，后续安装 vue-router）

关键文件：

文件	作用
index.html	页面骨架，只有一个 div id="app"，Vue 应用挂载到这里
src/main.js	引入根组件 App.vue，调用 createApp 创建应用
src/App.vue	根组件，所有其他组件都嵌套在它内部

三、单文件组件

Vue 的基本单位是组件，一个 .vue 文件包含三块：

<!-- ArticleCard.vue -->
<template>
  <div class="card">
    <h3>{{ title }}</h3>
    <p>{{ summary }}</p>
  </div>
</template>

<script setup>
const title = "Python 入门";
const summary = "从变量到面向对象的完整基础";
</script>

<style scoped>
.card {
  border: 1px solid #ddd;
  padding: 16px;
  border-radius: 8px;
}
</style>

块	作用
template	HTML 结构，只能有一个根元素（Vue 3 支持多根）
script setup	组件逻辑，setup 是 Vue 3 组合式 API 的语法糖
style scoped	CSS 样式，scoped 表示只作用于当前组件

四、组件引入与复用

在 App.vue 中使用自定义组件：

<template>
  <div class="app">
    <h1>运维平台</h1>
    <ArticleCard />
    <ArticleCard />
  </div>
</template>

<script setup>
import ArticleCard from "./components/ArticleCard.vue";
</script>

组件名推荐大驼峰（ArticleCard），在模板中可以用大驼峰（<ArticleCard />）或短横线（<article-card />）两种写法，效果相同。

五、组件命名规范

类型	命名方式	示例
基础组件	大驼峰	BaseButton.vue、BaseInput.vue
页面组件	大驼峰，语义化	ServerList.vue、TaskDetail.vue
布局组件	大驼峰，加 Layout 后缀	DefaultLayout.vue

组件文件名和组件内部 name（如果需要定义）保持一致，便于调试和 IDE 自动导入。

六、静态资源引用

在模板中引用

<template>
  <img src="/logo.png" alt="Logo">
</template>

public/ 目录（或项目根目录）下的文件可以直接通过根路径 / 引用，不经过构建处理。

在 JS 中引用

<script setup>
import logoUrl from "./assets/logo.png";
</script>

<template>
  <img :src="logoUrl" alt="Logo">
</template>

src/ 目录下的资源通过 import 引入，Vite 会处理路径、哈希化和优化。

七、常见错误

template 中有多个根元素（Vue 2）

<!-- Vue 2 中错误 -->
<template>
  <div>A</div>
  <div>B</div>
</template>

<!-- Vue 3 支持片段（Fragment），多根合法 -->
<!-- 但如果项目用 Vue 2，必须包在一个根元素内 -->
<template>
  <div>
    <div>A</div>
    <div>B</div>
  </div>
</template>

组件未注册就使用

<template>
  <MyComponent />    <!-- 错误：没有 import -->
</template>

<script setup>
// 缺少 import MyComponent from "./MyComponent.vue"
</script>

scoped 样式穿透问题

<style scoped>
/* 只影响当前组件内的 .title */
.title { color: red; }
</style>

如果子组件也有 .title，父组件的 scoped 样式不会作用到子组件上。需要影响子组件时，用 :deep()：

<style scoped>
:deep(.child-title) {
  color: blue;
}
</style>