课程库

外观

第1章：从静态页面到 Vue 工程

复制页面

约 7784 字大约 26 分钟

Vue 3ViteNode.js开发环境

2026-07-28

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

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

本章项目目标

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

学习说明

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

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

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

本章工程主线

本章示例统一使用 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 单文件组件模板如下：

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

Vue 不能替代基础知识

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

1.1.3 课堂演示

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

  1. 进入课堂工程目录。

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

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

  2. 用下面的代码替换 src/App.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 地址，保存后页面自动更新

版本检查语法：

node --version
npm --version

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

参考：Vue 官方教程：简介、Vite 官方入门。

教材截图和当前界面不一样怎么办

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

1.2.3 课堂演示

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

    node --version
npm --version

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

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

    <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 官方项目脚手架。脚手架不是“帮你写完整网站”，而是先把项目需要的基础文件准备好。

命令模板：

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

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

💡 初学脚手架选择指引（极简模式，专注跑通）

运行 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 课堂演示

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

    npm create vue@latest vue-course-lab

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

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

    cd vue-course-lab
npm install
npm run dev

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

  3. 用下面的最小组件替换新项目的 src/App.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。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}
// 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 中预留的挂载位置。

交互演示

Vite 项目从命令到页面的启动链

观察 npm、Vite、模块入口与浏览器之间的职责边界。

1 / 4
  1. 1读取脚本package.json
  2. 2启动服务Vite
  3. 3加载入口main.js
  4. 4渲染页面App.vue
当前发生

npm 找到 dev 脚本，并把执行权交给 Vite。

观察证据

终端输出实际运行的 vite 命令。

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

1.4.3 课堂演示

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

    本节只看四个节点

    classroom-demo

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

  2. 把 src/App.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

语法模板：

<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。

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

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

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

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

1.5.4 当堂练习

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

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

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

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 负责显示课程状态卡片。

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

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

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

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

1.6.3 课堂演示

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

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

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

    课程首页与状态卡片

    src

    App.vue

    components

    CourseStatus.vue

    src/App.vue
    <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>
    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在本地预览刚构建的结果预览地址能正常打开

命令模板：

npm run dev
npm run build
npm run preview

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

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

1.7.3 课堂演示

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

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

  2. 把 CourseStatus.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 停止开发服务器，再执行：

    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 语法/概念

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

npm install
npm run dev
npm run build

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

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

交互演示

启动失败时的证据链

先判断失败发生在哪一层，再选择对应处理动作。

1 / 4
  1. 1确认目录工作路径
  2. 2确认运行时Node / npm
  3. 3确认依赖node_modules
  4. 4确认端口浏览器
当前发生

检查当前目录是否真的包含 package.json。

观察证据

终端路径与项目根目录一致。

不要把“全部删除重来”当成第一步

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

🌟 进阶选学：工程排错锦囊

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

1.8.3 课堂演示

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

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

  2. 在副本根目录执行：

    npm install
npm run dev

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

  3. 故意把 src/App.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，构建应成功。

对话示范

示范：从启动错误回到证据

观察一名学生如何先定位失败层级，再执行范围明确的修复。

1 / 4
学生报告现象

我运行 npm run dev 后提示 Missing script: "dev"，是不是要重装 Node.js？

观察点
  • 先根据错误原文判断失败层级，没有直接执行大范围重装。
  • 当前目录和 package.json 是验证 npm 脚本问题的直接证据。
  • 修复动作范围小、可解释，并且能在重新运行后立即验证。

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 分钟完成。

学习自检

停一下：我能独立启动项目吗

在小测前确认自己能把启动链和排错证据说清楚。

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 本章小测

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

章节测评

第1章小测：从静态页面到 Vue 工程

检查是否能根据启动现象定位工程层级。

3 题
1. 运行 npm run dev 后出现 Missing script: "dev"，第一步最应该检查什么？
2. Vue 项目从 npm 脚本到根组件的正确关系是哪一项？
3. 教材截图与当前脚手架选项不一致时，哪种处理更可靠？

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章学习。
  • 开发能打开、热更新正常、生产构建成功，是三种不同证据。
  • 出错时先看目录和第一条错误，不要直接删除项目重来。