---
url: /courses/web-frontend-framework/course-start/index.md
---
# 第1章：从静态页面到 Vue 工程

以前写静态页面时，双击 `index.html` 就能看到结果。进入 Vue 后，页面为什么要从终端启动？`npm`、Vite、`main.js` 和 `App.vue` 又分别做什么？

这一章沿着一条完整工程主线学习：先看懂静态页面和 Vue 工程的区别，再检查环境、创建项目、认识启动链、编写组件，最后完成运行、构建和排错。

::: tip 本章项目目标
完成一个中性的 `vue-course-lab` 学习工程。浏览器能够显示课程首页和状态卡片，保存组件后页面自动更新，执行构建命令后能生成发布文件。校园微商城只在第8章做页面功能分析，本章不提前创建商城。
:::

::: tip 学习说明
建议从 1.1 开始顺序学习，并依次完成每节的课堂演示和当堂练习；学完整章后，再完成章末综合任务。
:::

::: tip 🎯 学习梯度指引（分层通关）

* **核心必学（保底通关）**：1.1 ~ 1.6 节。重点是跑通 Node/npm 环境、学会用 `npm run dev` 启动开发服务、掌握单文件组件（SFC）的三块结构，以及把一个子组件引入到 `App.vue` 中。
* **进阶选学（拔高拓展）**：1.7 节的生产打包（`build`）与 1.8 节的工程排错锦囊。初学阶段先保证页面能跑通、文字能改动；学有余力或遇到工程报错时，再深入探索。
* **练习分层**：每节练习设【必做任务】与【选做挑战🌟】。必做任务面向全员通关；选做挑战完全由学生个人根据兴趣自主拓展，不包含也不挂钩任何分数或加分。
  :::

## 本章工程主线

```mermaid
flowchart LR
  A[静态页面] --> B[检查工具]
  B --> C[创建 Vue 工程]
  C --> D[看懂启动链]
  D --> E[编写 SFC]
  E --> F[组合组件]
  F --> G[开发与构建]
  G --> H[复现与排错]
```

本章示例统一使用 `resources/ch01/classroom-demo/`。可以直接运行这个工程，也可以把每个知识点的 `App.vue` 示例粘贴进去观察结果。

## 1.1 静态页面和 Vue 工程有什么不同

### 1.1.1 学习目标

掌握静态页面与 Vue 工程的基本区别，能够判断一个项目应该直接打开还是通过 npm 脚本启动。

### 1.1.2 语法/概念

静态页面像一张已经印好的纸：浏览器直接读取 HTML、CSS 和 JavaScript。Vue 工程更像一条小型生产线：`.vue` 文件要先交给开发工具处理，再由浏览器显示。

| 对比项 | 静态页面 | Vue + Vite 工程 |
| --- | --- | --- |
| 怎么启动 | 直接打开 HTML，或用静态服务器 | 在项目根目录执行 npm 脚本 |
| 页面放哪里 | 主要写在 HTML 文件里 | 主要写在 `.vue` 组件里 |
| 依赖怎么来 | CDN 或手工下载 | 根据 `package.json` 安装 |
| 修改后怎么看 | 手动刷新 | 开发服务器自动更新 |
| 发布什么 | 原来的静态文件 | 构建后的 `dist/` 文件 |

最小 Vue 单文件组件模板如下：

```vue
<template>
  <main>
    <!-- 最小 Vue 组件模板：包含页面的主体结构与标题 -->
    <h1>Web 前端框架开发</h1>
  </main>
</template>
```

::: warning Vue 不能替代基础知识
Vue 仍然使用 HTML 组织结构、CSS 控制样式、JavaScript 处理数据和动作。标签不会闭合、选择器写错、变量拼错，换成 Vue 后仍然会出错。
:::

### 1.1.3 课堂演示

下面的演示只做一件事：运行课堂工程，并把页面改成最小的 Vue 首页。

:::: steps

1. 进入课堂工程目录。

   ```bash
   cd docs/courses/web-frontend-framework/resources/ch01/classroom-demo
   npm install
   npm run dev
   ```

   运行后，终端应该出现以 `Local` 开头的访问地址。

2. 用下面的代码替换 `src/App.vue`。

   ```vue
   <template>
     <main class="page">
       <!-- 小标题/阶段标签 -->
       <p class="eyebrow">VUE COURSE LAB</p>
       <!-- 页面主标题 -->
       <h1>Web 前端框架开发</h1>
       <p>我已经从静态页面进入 Vue 工程。</p>
     </main>
   </template>

   <style scoped>
   /* scoped 保证样式仅在当前组件生效，不会污染全局 */
   .page {
     max-width: 680px;
     margin: 80px auto;
     padding: 32px;
     border: 1px solid #dce4f2;
     border-radius: 20px;
   }

   .eyebrow {
     color: #3157d5;
     font-weight: 800;
   }
   </style>
   ```

   粘贴完成后，编辑器里应该只剩这一个完整组件，并且没有红色语法提示。

3. 保存文件并打开终端给出的地址。

   页面应该显示课程名称和“我已经从静态页面进入 Vue 工程”，而不是脚手架原来的欢迎页。
   ::::

### 1.1.4 当堂练习

**【必做任务（基础通关）】**
在刚才的页面上完成两个小改动，确认热更新机制：

1. 打开 `src/App.vue`，把标题改成“我的 Vue 学习工程”；
2. 在标题下面增加一行段落：“第1章：从静态页面到 Vue 工程”；
3. 按保存键，确认浏览器无需手动刷新即刻显示新文字。

**【选做挑战（🌟 自主拓展）】**
给新加的段落增加一个自定义类名（如 `class="intro"`），并在 `<style scoped>` 中为它设置蓝色文字（如 `color: #3157d5;`），体验 SFC 内部样式控制。

> 只修改 `src/App.vue`，必做任务预计 10 分钟完成。

## 1.2 Node.js、npm 和 Vite 分别做什么

### 1.2.1 学习目标

掌握 Node.js、npm 和 Vite 的分工，能够用版本命令判断当前终端是否具备运行 Vue 工程的基础条件。

### 1.2.2 语法/概念

可以把三者理解成开工前的三样工具：

| 工具 | 简单说明 | 能看到的证据 |
| --- | --- | --- |
| Node.js | 让终端可以运行 JavaScript 开发工具 | `node --version` 返回版本号 |
| npm | 负责下载依赖、执行项目脚本 | `npm --version` 返回版本号，`npm run dev` 能执行 |
| Vite | 把 `.vue` 文件处理成浏览器能加载的内容 | 终端出现 Local 地址，保存后页面自动更新 |

版本检查语法：

```bash
node --version
npm --version
```

版本号不是越新越好。项目真正要求什么版本，应查看 `package.json` 中的 `engines` 或课程统一环境说明。

参考：[Vue 官方教程：简介](https://cn.vuejs.org/guide/introduction.html)、[Vite 官方入门](https://vite.dev/guide/)。

::: details 教材截图和当前界面不一样怎么办
先保持学习目标不变，再以项目中的 `package.json`、lock 文件和官方文档为准。不要为了让界面和旧截图完全一样，随意降级整个开发环境。
:::

### 1.2.3 课堂演示

:::: steps

1. 在 VS Code 终端执行版本命令。

   ```bash
   node --version
   npm --version
   ```

   两条命令都应返回版本号。如果提示“找不到命令”，先安装课程要求的 Node.js，再重新打开终端。

2. 把实际看到的版本号写进 `src/App.vue`。下面的 `v0.0.0` 要换成自己的结果。

   ```vue
   <template>
     <!-- 环境检测卡片：展示本地开发工具链就绪状态 -->
     <main class="environment-card">
       <h1>开发环境检查</h1>
       <!-- 实际操作时，将 v0.0.0 替换为终端查看到的真实版本号 -->
       <p>Node.js：v0.0.0 · 已识别</p>
       <p>npm：v0.0.0 · 已识别</p>
       <strong>基础工具可以使用</strong>
     </main>
   </template>

   <style scoped>
   /* 浅绿色系背景，直观传达环境健康正常的状态 */
   .environment-card {
     max-width: 620px;
     margin: 80px auto;
     padding: 28px;
     border: 1px solid #b9dfc8;
     border-radius: 18px;
     background: #f1fbf5;
   }

   strong {
     color: #168242;
   }
   </style>
   ```

   替换完成后，编辑器中应该能看到自己的 Node.js 和 npm 版本号，不再保留 `v0.0.0`。

3. 保存文件。

   页面应该出现两条版本记录和“基础工具可以使用”的文字状态。状态不能只画一个绿色圆点，因为文字更容易判断。
   ::::

### 1.2.4 当堂练习

**【必做任务（基础通关）】**
在当前环境检查卡中填入你电脑的实际版本号：

1. 打开 VS Code 终端，执行 `node -v` 和 `npm -v`；
2. 将返回的真实版本号写进 `src/App.vue`（替换掉示例中的 `v0.0.0`）；
3. 确认浏览器正常显示你的工具版本。

**【选做挑战（🌟 自主拓展）】**
在卡片中再增加两行工具环境状态：

* 编辑器：VS Code · 已安装
* 浏览器：Chrome / Edge · 已就绪

> 每一行保持“工具名称 + 当前状态”的格式，预计 10 分钟完成。

## 1.3 使用 create-vue 创建第一个工程

### 1.3.1 学习目标

掌握 create-vue 的基本创建流程，能够独立生成、安装并启动一个名称规范的 Vue 学习工程。

### 1.3.2 语法/概念

create-vue 是 Vue 官方项目脚手架。脚手架不是“帮你写完整网站”，而是先把项目需要的基础文件准备好。

命令模板：

```bash
npm create vue@latest <project-name>
cd <project-name>
npm install
npm run dev
```

`<project-name>` 是占位符，执行时要换成真实英文目录名，不要把尖括号一起输入。

::: tip 💡 初学脚手架选择指引（极简模式，专注跑通）
运行 `npm create vue@latest` 时，终端会依次询问多个配置选项。**第一章为了排除干扰，除 JavaScript 外一律选择 No**：

* Add TypeScript? -> **No**
* Add JSX Support? -> **No**
* Add Vue Router? -> **No**（第4章再学）
* Add Pinia? -> **No**（第7章再学）
* Add Vitest / End-to-End Testing? -> **No**
* Add ESLint / Prettier? -> **No**（若经常因格式化报错打断，建议初学全选 No，先把注意力放在代码跑通上）

> **原则**：刚开始做减法，把心智负担降到最低；等学到对应模块时，再按需引入工具。
> :::

### 1.3.3 课堂演示

:::: steps

1. 在专门存放个人练习的父目录执行：

   ```bash
   npm create vue@latest vue-course-lab
   ```

   按提示选择 JavaScript；其余功能全部选择 No。创建完成后，个人练习目录中应该出现 `vue-course-lab/` 文件夹，终端不应出现红色 error。

2. 进入项目并安装依赖。

   ```bash
   cd vue-course-lab
   npm install
   npm run dev
   ```

   终端应该给出 Local 地址，浏览器可以打开脚手架初始页面。

3. 用下面的最小组件替换新项目的 `src/App.vue`。

   ```vue
   <template>
     <!-- 欢迎卡片：验证由 create-vue 创建的项目能够正常运行与展示 -->
     <main class="created-page">
       <h1>Vue 学习工程已创建</h1>
       <p>项目目录：vue-course-lab</p>
       <p>启动方式：npm run dev</p>
     </main>
   </template>

   <style scoped>
   /* 浅蓝基调容器，居中布局并带圆角 */
   .created-page {
     max-width: 680px;
     margin: 80px auto;
     padding: 32px;
     border-radius: 20px;
     background: #eef3ff;
   }
   </style>
   ```

   保存后，浏览器应该从脚手架欢迎页变成“Vue 学习工程已创建”。
   ::::

### 1.3.4 当堂练习

**【必做任务（基础通关）】**
在刚创建的 `vue-course-lab` 工程中完成以下改动：

1. 把页面标题改成自己的班级和姓名，例如“软件 2401 · 张三”；
2. 保持项目通过 `npm run dev` 正常启动，在浏览器中查看新页面；
3. 检查控制台（F12 -> Console），确认没有红色报错。

**【选做挑战（🌟 自主拓展）】**

1. 在页面中再增加一行：“下一步：认识 Vue 项目启动链”；
2. 体验在终端按快捷键 Ctrl + C 正常退出服务，再输入 `npm run dev` 重新启动。

> 保持目录名、文件名和代码标识符为英文，必做任务预计 15 分钟完成。

## 1.4 看懂 Vue 工程启动链

### 1.4.1 学习目标

掌握 Vue 工程从命令到页面的启动链，能够说明 `package.json`、`main.js` 和 `App.vue` 各自负责什么。

### 1.4.2 语法/概念

输入 `npm run dev` 后，并不是 npm 自己把页面画出来。它先读取 `package.json` 的脚本，再把工作交给 Vite；浏览器加载入口后，`main.js` 创建 Vue 应用，最后显示 `App.vue`。

```json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}
```

```js
// 1. 从 vue 核心库中导入应用工厂函数 createApp
import { createApp } from 'vue'
// 2. 导入我们的根组件 App.vue
import App from './App.vue'

// 3. 创建 Vue 应用实例，并挂载到 index.html 中 id 为 app 的容器上
createApp(App).mount('#app')
```

简单理解：

* `package.json` 是项目的“命令菜单”；
* Vite 是开发服务器和加工工具；
* `main.js` 是应用入口；
* `App.vue` 是页面最外层的根组件；
* `#app` 是 `index.html` 中预留的挂载位置。

播放动画后，按顺序说出“npm 读脚本 → Vite 启动 → main.js 创建应用 → App.vue 显示页面”。

### 1.4.3 课堂演示

:::: steps

1. 在课堂工程中依次打开 `package.json`、`src/main.js` 和 `src/App.vue`。

   ::: file-tree title="本节只看四个节点" icon="colored"

   * classroom-demo/
     * **package.json** # npm 从这里找到 dev 与 build
     * index.html # 提供 #app 挂载位置
     * src/
       * **main.js** # 创建并挂载 Vue 应用
       * **App.vue** # 根组件与可见页面
         :::

   打开后，编辑器标签栏应该同时看到这三个文件；浏览器页面暂时不会变化。

2. 把 `src/App.vue` 改成下面的启动链说明页。

   ```vue
   <template>
     <!-- 启动链说明卡片：展示从命令到界面的关键流转节点 -->
     <main class="flow-card">
       <h1>Vue 项目启动链</h1>
       <!-- 有序列表对应启动流程的先后顺序 -->
       <ol>
         <li>package.json：找到 dev 脚本</li>
         <li>Vite：启动开发服务器</li>
         <li>main.js：创建 Vue 应用</li>
         <li>App.vue：显示根组件</li>
       </ol>
     </main>
   </template>

   <style scoped>
   .flow-card {
     max-width: 680px;
     margin: 80px auto;
     padding: 30px;
     border: 1px solid #dce4f2;
     border-radius: 18px;
   }

   li {
     margin: 12px 0;
   }
   </style>
   ```

   粘贴完成后，编辑器中应该能看到四个 `<li>`；还没有保存时，浏览器可以保持原样。

3. 保存并观察页面。

   页面应该显示四步启动链。现在指着每一行，在项目中找到对应文件或终端证据。
   ::::

### 1.4.4 当堂练习

**【必做任务（基础通关）】**

1. 观察项目结构，思考并回答一个排错小问题：如果在终端执行 `npm run dev` 时提示 `Missing script: "dev"`，你应该先去检查哪个文件？（提示：回顾开发启动命令是在哪里定义的）；
2. 把你的答案作为一行段落文字写在 `App.vue` 底部，保存并确认浏览器显示出来。

**【选做挑战（🌟 自主拓展）】**
在启动链的有序列表 `<ol>` 中增加第 5 项：

> `<li>浏览器：解析并呈现根组件页面</li>`

> 必做任务预计 10 分钟完成。

## 1.5 认识 Vue 单文件组件 SFC

### 1.5.1 学习目标

掌握单文件组件的三块结构，能够在 `App.vue` 中分别编写简单数据、页面结构和组件样式。

### 1.5.2 语法/概念

`.vue` 文件叫单文件组件，英文是 Single-File Component，常用缩写是 SFC。它通常由三块组成：

| 区域 | 简单说明 | 主要放什么 |
| --- | --- | --- |
| `<script setup>` | 组件的“大脑” | 变量、函数、导入 |
| `<template>` | 组件的“骨架” | 标题、段落、按钮等页面结构 |
| `<style scoped>` | 组件的“外观” | 当前组件使用的 CSS |

语法模板：

```vue
<script setup>
// 1. 逻辑区：定义组件需要的数据或函数（当前为普通字符串常量）
const message = '这里准备数据'
</script>

<template>
  <!-- 2. 模板区：使用双大括号 {{ }} 插值语法把数据渲染到界面上 -->
  <p>{{ message }}</p>
</template>

<style scoped>
/* 3. 样式区：scoped 确保样式只在当前组件内部生效，防止样式污染 */
p {
  color: #3157d5;
}
</style>
```

`{{ message }}` 的意思很简单：把脚本里的 `message` 文字放到这里。响应式数据会在第2章系统学习，本节只使用普通常量。

### 1.5.3 课堂演示

课堂示例的解锁答案是单文件组件的英文缩写 **SFC**。

:::: steps

1. 用解锁后的代码替换 `src/App.vue`。

   粘贴完成后，编辑器应该依次看到 `<script setup>`、`<template>` 和 `<style scoped>` 三块。

2. 保存文件，浏览器应该显示阶段标签、课程标题和下一步说明。

3. 把 `courseTitle` 改成“我的前端框架课程”。保存后标题应该立即变化。
   ::::

### 1.5.4 当堂练习

**【必做任务（基础通关）】**
体验 SFC 脚本数据与模板渲染绑定：

1. 在 `<script setup>` 中新声明一个字符串常量：
   ```js
   const myTeacher = '负责教师：王老师' // 换成你的任课教师姓名
   ```
2. 在 `<template>` 中使用双花括号插值 `{{ myTeacher }}` 显示出来；
3. 保存后，确认浏览器正文出现该行文字。

**【选做挑战（🌟 自主拓展）】**
在当前 `App.vue` 中增加常量：

```js
const nextTask = '创建第一个自定义组件'
```

在模板中显示它，并在 `<style scoped>` 中为它加上浅蓝色背景（如 `background: #eef3ff; padding: 12px; border-radius: 8px;`）。

> 必做任务预计 10 分钟完成。

## 1.6 把页面拆成根组件和子组件

### 1.6.1 学习目标

掌握最基础的组件创建与组合，能够新建一个 `.vue` 文件并在 `App.vue` 中导入、使用它。

### 1.6.2 语法/概念

组件就是页面里可以单独管理的一块内容。`App.vue` 负责摆放页面的大结构，`CourseStatus.vue` 负责显示课程状态卡片。

导入和使用组件的语法模板：

```vue
<script setup>
// 1. 局部导入子组件：从相对路径引入 CourseStatus.vue
import CourseStatus from './components/CourseStatus.vue'
</script>

<template>
  <!-- 2. 模板中直接使用子组件：大驼峰单闭合标签 -->
  <CourseStatus />
</template>
```

本章先让子组件显示自己的固定内容，不讲 Props。父组件传值会在第3章正式学习。

### 1.6.3 课堂演示

:::: steps

1. 在 `src/components/` 中新建 `CourseStatus.vue`。

   新建后，文件树中应该出现 `src/components/CourseStatus.vue`；此时页面还不会多出卡片。

2. 用下面两个完整文件组成课程首页。

   ::: code-tree title="课程首页与状态卡片" entry="src/App.vue" height="560px"

   ```vue title="src/App.vue" :active
   <script setup>
   // 1. 导入自定义子组件 CourseStatus
   import CourseStatus from './components/CourseStatus.vue'

   // 2. 声明课程首页主标题数据
   const courseTitle = 'Web 前端框架开发'
   </script>

   <template>
     <main class="page">
       <p class="eyebrow">VUE COURSE LAB</p>
       <!-- 渲染课程主标题 -->
       <h1>{{ courseTitle }}</h1>
       <!-- 引用子组件，展示课程状态卡片 -->
       <CourseStatus />
     </main>
   </template>

   <style>
   /* 全局基底样式 */
   :root {
     color: #1d2942;
     background: #f4f7fb;
     font-family: system-ui, sans-serif;
   }

   body {
     margin: 0;
   }

   .page {
     width: min(680px, calc(100% - 32px));
     margin: 80px auto;
   }

   .eyebrow {
     color: #5b6ee1;
     font-size: 12px;
     font-weight: 800;
     letter-spacing: 0.16em;
   }
   </style>
   ```

   ```vue title="src/components/CourseStatus.vue"
   <template>
     <!-- 状态卡片组件：负责独立展示当前学习阶段信息 -->
     <section class="card">
       <span class="badge">正在学习</span>
       <h2>第1章：Vue 工程入门</h2>
       <p>下一步：完成运行、构建和排错练习。</p>
     </section>
   </template>

   <style scoped>
   /* 卡片主体：白色卡片底色与轻微阴影 */
   .card {
     padding: 28px;
     border: 1px solid #dce3f0;
     border-radius: 24px;
     background: white;
     box-shadow: 0 18px 45px rgb(45 63 105 / 12%);
   }

   /* 状态徽标样式 */
   .badge {
     display: inline-block;
     padding: 6px 10px;
     color: #3150c5;
     border-radius: 999px;
     background: #e7edff;
     font-weight: 700;
   }

   h2 {
     margin: 18px 0 8px;
   }

   p {
     margin: 0;
     color: #667085;
   }
   </style>
   ```

   :::

   粘贴完成后，`App.vue` 中应该有导入语句和 `<CourseStatus />`，子组件中应该有自己的模板与样式。

3. 保存两个文件。

   浏览器应该先显示课程标题，再显示一张“正在学习”的状态卡片。删除 `<CourseStatus />` 后卡片会消失，恢复后卡片重新出现。
   ::::

### 1.6.4 当堂练习

**【必做任务（基础通关）】**
独立创建并导入一个子组件：

1. 在 `src/components/` 目录下新建一个文件 `NextStepCard.vue`；
2. 在该组件内编写简单的 `<template>`，显示一行段落文字：“下一步任务：学习响应式数据”；
3. 在 `src/App.vue` 的 `<script setup>` 中导入它，并在模板中以 `<NextStepCard />` 使用它；
4. 保存后，在浏览器中确认出现了这一行子组件内容。

**【选做挑战（🌟 自主拓展）】**
为 `NextStepCard.vue` 增加结构与美化：

* 增加二级标题 `<h2>下一步任务</h2>`；
* 在卡片样式中加上白色背景、圆角和内边距，并在两张卡片之间设置清晰的外边距（如 `margin-top: 20px;`）。

> 本节不涉及 Props 传值或事件通信，必做任务预计 15 分钟完成。

## 1.7 开发、热更新、构建和预览

### 1.7.1 学习目标

掌握 `dev`、`build` 和 `preview` 三个脚本的用途，能够判断“开发时能打开”和“可以构建发布”是两种不同证据。

### 1.7.2 语法/概念

| 命令 | 简单说明 | 通过证据 |
| --- | --- | --- |
| `npm run dev` | 开发时边改边看 | 终端有 Local 地址，保存后页面自动更新 |
| `npm run build` | 把项目加工成发布文件 | 命令无 error，并生成 `dist/` |
| `npm run preview` | 在本地预览刚构建的结果 | 预览地址能正常打开 |

命令模板：

```bash
npm run dev
npm run build
npm run preview
```

::: tip 🌟 进阶选学：从本地开发（dev）到生产构建（build）

* **日常实训核心（必学）**：我们在课堂上 95% 的时间都使用 `npm run dev`。它启动快、支持修改代码后浏览器立即热更新，是日常写代码的最佳工具。
* **阶段验收与上线（选学拓展）**：`npm run build` 会把所有的 `.vue` 组件和现代语法压缩、打包成纯原生的 HTML/CSS/JS 文件并存入 `dist/` 目录。本节课主要建立感性认知，知道有这道打包工序即可，后续综合实战阶段会深入使用。
  :::

### 1.7.3 课堂演示

:::: steps

1. 在项目根目录执行 `npm run dev`，打开 Local 地址。

   终端应该显示 Local 地址，浏览器应该先看到 1.6 节完成的课程首页。

2. 把 `CourseStatus.vue` 临时改成下面的最小内容。

   ```vue
   <template>
     <!-- 热更新（HMR）测试组件：修改文字并保存，观察浏览器无需整页刷新即可实时响应 -->
     <p class="status">热更新测试：第一次保存</p>
   </template>

   <style scoped>
   .status {
     padding: 18px;
     color: #2449bd;
     border-radius: 12px;
     background: #e8efff;
   }
   </style>
   ```

   保存后，页面应立即显示“第一次保存”，不需要重新执行启动命令。

3. 把文字改成“热更新测试：第二次保存”。

   页面应再次自动变化，证明当前编辑的文件属于正在运行的项目。

4. 【进阶选做演示】在终端按 `Ctrl + C` 停止开发服务器，再执行：

   ```bash
   npm run build
   npm run preview
   ```

   构建应无 error，项目根目录生成 `dist/`，预览地址能打开页面。
   ::::

### 1.7.4 当堂练习

**【必做任务（基础通关）】**
体验热更新与服务启停操作：

1. 恢复 1.6 节的完整课程首页；
2. 修改 `CourseStatus.vue` 中的文字，在浏览器中确认页面自动更新（无需手动刷新浏览器）；
3. 练习在终端中按快捷键 Ctrl + C 成功停止开发服务器。

**【选做挑战（🌟 自主拓展）】**

1. 在终端执行 `npm run build`，查看项目根目录是否成功生成了 `dist/` 文件夹；
2. 用一句话简要说明：为什么开发时用 `dev`，发布给别人用 `build`？

> 必做任务预计 10 分钟完成。

## 1.8 复现已有项目并按证据排错

### 1.8.1 学习目标

掌握已有 Vue 项目的复现与基础排错顺序，能够根据目录、运行时、依赖和端口证据定位常见启动问题。

### 1.8.2 语法/概念

复现已有项目不是重新创建项目，而是读取已有文件，安装相同依赖，再按项目脚本启动。

```bash
npm install
npm run dev
npm run build
```

排错顺序固定从最容易检查的地方开始：

| 层次 | 先问什么 | 证据 |
| --- | --- | --- |
| 目录 | 当前是不是项目根目录 | 同时看到 `package.json` 和 `src/` |
| 运行时 | Node.js、npm 能不能执行 | 两条版本命令 |
| 依赖 | 项目依赖有没有安装成功 | lock 文件、安装日志、`node_modules` |
| 端口与浏览器 | 打开的地址是不是终端给出的地址 | Vite Local 地址、Console 第一条错误 |

::: danger 不要把“全部删除重来”当成第一步
不要在不知道原因时删除 lock 文件、全局重装 Node.js 或清空整个用户缓存。先保存错误原文，再做范围明确、可以恢复的修改。
:::

::: tip 🌟 进阶选学：工程排错锦囊
本节是工程开发中的“安全气囊”。初学阶段如果你的代码运行顺畅，可先通读理解排错的四层顺序；一旦在后续实训中遇到项目跑不起来、终端报错飘红时，再随时翻阅本节对照排查。
:::

### 1.8.3 课堂演示

:::: steps

1. 复制 `resources/ch01/classroom-demo/`，把副本重命名为 `ch01-environment-practice`，再用 VS Code 打开副本。

   打开后，VS Code 文件树顶层应该同时看到 `package.json` 和 `src/`，说明当前打开的是项目根目录。

2. 在副本根目录执行：

   ```bash
   npm install
   npm run dev
   ```

   页面应显示课程标题和课程状态卡片。

3. 故意把 `src/App.vue` 的导入路径写错大小写：

   ```vue
   <script setup>
   // 模拟常见排错场景：故意将文件名首字母大写的 CourseStatus 写成小写 courseStatus
   // 提示：Linux/macOS 等区分大小写的文件系统或打包工具将直接报“模块未找到”
   import CourseStatus from './components/courseStatus.vue'
   </script>

   <template>
     <main>
       <h1>Vue 工程排错练习</h1>
       <!-- 此时由于上方导入路径错误，该子组件将无法正常加载渲染 -->
       <CourseStatus />
     </main>
   </template>
   ```

   保存后，终端或浏览器应该出现“找不到模块”一类错误。记录第一条错误、涉及的文件和导入路径。

4. 把路径恢复为 `./components/CourseStatus.vue`。

   页面应该重新出现。最后执行 `npm run build`，构建应成功。
   ::::

{{guided-demo:vue-environment-diagnosis}}

### 1.8.4 当堂练习

**【必做任务（基础通关）】**
独立完成一次已有工程的复现与启动：

1. 复制 `resources/ch01/classroom-demo/` 到个人练习目录；
2. 在终端进入该目录，依次执行 `npm install` 与 `npm run dev`；
3. 打开本地地址，确认页面正常运行显示。

**【选做挑战（🌟 自主拓展）】**
体验一次实战排错或备忘整理：

* 方式 A（排错实操）：故意将 `src/App.vue` 中的导入路径写错一个字母，保存后观察终端弹出的首行错误提示，记录错误原因后将其修正；
* 方式 B（备忘卡片）：在项目中新建 `src/components/EnvironmentNote.vue`，展示项目根目录判断、`dev` 命令与 `build` 命令，并在 `App.vue` 中导入展示。

> 必做任务预计 10 分钟完成。

{{reflection-checkpoint:vue-course-start-checkpoint}}

## 1.9 课后任务：Vue 项目运行说明页

### 任务目标

使用本章学过的环境检查、项目结构、单文件组件与组件组合知识，完成一张能帮助别人快速运行项目的说明页。本任务包含“基础通关要求（全员必做）”与“进阶拓展任务（自主选做）”。

### 基础通关要求（全员必做）

1. 复制 `resources/ch01/after-class-starter/` 到个人练习目录，不修改课程资源原文件；
2. 页面正确显示项目名称、环境状态（如“环境已就绪”）和开发命令 `npm run dev`；
3. 新建 `src/components/ProjectGuide.vue`，组件内部显示开发命令与下一步任务；
4. 在 `src/App.vue` 中导入并使用 `ProjectGuide.vue`；
5. 执行 `npm install` 与 `npm run dev` 能够成功启动并在浏览器中看到说明页，修改文字支持热更新；
6. 目录名、文件名和代码标识符使用英文，页面文案使用中文。

### 进阶拓展任务（自主选做）

以下两项任务完全由个人根据学习兴趣自主选择探索，不与任何分数或加分绑定：

1. **挑战一【生产构建验证】**：在终端成功执行 `npm run build`，根目录下生成 `dist/` 打包目录，并在提交截图中展示构建成功日志；
2. **挑战二【模拟实战排错】**：故意制造一次组件导入路径错误（如将大小写改错），记录控制台/终端报错信息后将其修复，并在说明页底部写下一条排错体会。

### 必须使用的知识

| 本章知识 | 在任务中的用途 |
| --- | --- |
| Node.js 与 npm | 检查环境、安装依赖、执行脚本 |
| `package.json` | 找到 `dev` 脚本与依赖定义 |
| SFC 三块结构 | 编写页面结构、简单数据和样式 |
| 组件创建与导入 | 创建并使用 `ProjectGuide.vue` |
| Vite 开发服务器 | 启动页面并观察热更新 |
| 生产构建与排错（选做） | 生成 `dist/`，根据错误证据完成排查 |

### 完成效果

浏览器显示一张整洁的“Vue 项目运行说明页”：上方是项目名称和“环境已就绪”文字状态，下方是由独立子组件渲染的运行指南卡片，清楚写出开发命令和下一步任务。修改组件文字后页面能够自动热更新，刷新后仍可正常打开。

### 验收步骤

1. 在项目根目录执行 `npm install`，确认安装无 error；
2. 执行 `npm run dev`，用终端给出的 Local 地址打开页面；
3. 修改 `ProjectGuide.vue` 中的一行文字，确认页面自动更新；
4. 检查页面是否完整显示项目名称、环境状态与运行指南组件；
5. 检查 `App.vue` 是否真正导入并使用 `ProjectGuide.vue`；
6. （选做）执行 `npm run build`，确认终端无 error 并生成 `dist/` 目录；
7. （选做）检查排错记录是否清晰表述了“报错现象与修复方法”。

### 提交内容

* **基础提交（全员必交）**：
  * 项目源码（不包含 `node_modules/` 和 `dist/`）；
  * 一张浏览器正常运行页面截图。
* **拓展提交（自选提交）**：
  * 若尝试了进阶挑战，可附带一张 `npm run build` 构建成功截图或一条排错心得记录。

## 1.10 本章小测

下面的题目检查能否根据现象定位问题，不只检查工具名称。

{{assessment:vue-course-start-check}}

## 1.11 本章知识自检

| 能力 | 达标标准 |
| --- | --- |
| 工程判断 | 能区分静态页面与 Vue 工程的启动方式 |
| 环境检查 | 能说明 Node.js、npm 和 Vite 的分工 |
| 项目创建 | 能创建并启动 `vue-course-lab` |
| 启动链 | 能说明 `package.json → main.js → App.vue` 的关系 |
| SFC | 能说明并编写 `script`、`template`、`style` 三块 |
| 组件组合 | 能创建、导入并使用一个无 Props 的子组件 |
| 开发与构建 | 能区分 `dev`、`build` 和 `preview` |
| 基础排错 | 能按目录、运行时、依赖、端口顺序收集证据 |

## 本章小结

* Vue 工程比静态页面多了包管理、构建工具和模块入口。
* Node.js 提供运行环境，npm 安装依赖并执行脚本，Vite 负责开发服务和构建。
* `package.json` 提供脚本，`main.js` 创建应用，`App.vue` 是根组件。
* SFC 把逻辑、结构和样式放在一个 `.vue` 文件中。
* 根组件可以导入并摆放子组件；Props 会在第3章学习。
* 开发能打开、热更新正常、生产构建成功，是三种不同证据。
* 出错时先看目录和第一条错误，不要直接删除项目重来。