4.1 Vite 搭建工程跑通首屏

4.1 Vite 搭建工程跑通首屏

本节摘要：用 Vite 初始化 Vue 工程并跑通首屏，认识单文件组件的三块结构。本节与 3.1 思路一致但语法不同，正好验证"同样的思想、不同的皮囊"。跑通之后，你就有了一块可反复实验 Vue 语法的试验田。

本节阅读目标
阅读完本节，你应当能够：

1. 用 Vite 初始化 Vue 工程并启动运行。
2. 辨认单文件组件里模板、脚本、样式三块各自的职责。
3. 通过 HMR 在浏览器里即时验证 Vue 改动。

一、脚手架：Vue 与 React 的同门用法

绕过复杂配置，Vite 一条命令即可。步骤：

npm create vite@latest siru-app -- --template vue
cd siru-app
npm install
npm run dev
​

几乎和 3.1 的 React 流程同构，差别只在模板参数。体会到这个"同构"很重要：脚手架把工程骨架封装好了，你只负责往里填组件。

二、单文件组件 SFC 的三块结构

Vue 的组件写在 .vue 单文件组件里，固定分三块：

<template>
  <p>你好，{{ name }}</p>
</template>

<script setup>
import { ref } from 'vue';
const name = ref('世界');
</script>

<style scoped>
p { color: blue; }
</style>
​

• template：声明式描述界面，里面可以直接用双花括号插值和指令。
• script setup：组件逻辑，ref 定义响应式数据。
• style scoped：样式，scoped 让它只作用于当前组件，天然防样式互串。

这套"结构 + 逻辑 + 样式"放在同一文件的组织，对应第 2.1 节说的关注点内聚，是 Vue 单文件组件的标志性优点。

三、图：从命令到首屏的落地链路

图：Vue 工程初始化与单文件组件结构

四、跑通之后干什么

首屏跑通后先别急着写复杂界面，做三件小事建立回路：改 template 里的文案看刷新、在 script 里加一个 ref 数据并在模板用插值、给样式加 scoped 看看它是否只影响当前组件。这套 2.4 节强调的"即改即验"练习，能最快把 Vue 语法焊进记忆。

四·一、单文件组件为什么值得单独讲一节

你可能觉得"不就是把三段代码放进一个文件"，但它背后的取舍很关键。把结构、逻辑、样式放在同一文件，换来的是同一组件的所有相关代码相邻可见——改动一个组件的样式不必跳到另一个文件翻。这在团队协作里尤其明显：一个任务往往只动某几个组件，每个组件自成一体，别人 review 也只需打开对应文件。这与"全局样式天上飘、组件逻辑散各处"的旧做法相比，是把"关注点内聚"落到了文件粒度（呼应 2.1 节）。

当然它不是没有代价：.vue 文件需要构建工具转译才能运行，Vite 正是那个在你写完后替你把 SFC 编译成普通脚本的帮手。所以你不必担心"浏览器会不会认 .vue"——脚手架早已把这层处理隐藏掉。理解这点，你读工程里出现的各种转译配置时就不会发怵。

五、常见坑速览

• 忘了进工程目录就 npm run，容器找不到脚本。
• script 里用了 ref 却在模板忘了写 .value 访问——Vue 在模板里对 ref 自动解包，脚本里需要 .value，别混。
• scoped 作用域记不清导致样式"怎么不生效"，确认样式写在当前组件的 style。

一句话治住"模板解包"的困惑

上面提到的"模板里 ref 自动解包、脚本里要 .value"是新人最常卡的一处，值得单独钉牢。解包只发生在 template 的顶层表达式里——<p>{{ count }}</p> 能直接拿数值。但当你把它放进对象再拿到模板用，或在一行里既读又算，就要自行 .value，比如 {{ config.count.value }} 这种嵌套路径里它不会替你想太多。手稳的做法是：脚本里一律显式 .value，模板里尽量用顶层 ref，这样两边的边界都清晰，不会出现"明明打印有值、模板却显示空"的错乱。拿这个规则回去核对你自己写的第一个组件，多数"怎么不显示"的疑惑当场就解开了。

认清工程里那几处"模板相关"的目录

跑通首屏后顺手看一遍工程结构，能帮你预判改动该落在哪。<script setup> 会要求你把组件 -> 目录组织得规整：主组件通常写在 src 下的 App.vue，新写的可复用组件放进一个 components 目录，页面级视图可以再分一层 views。样式上，全局样式放在入口附近引入，组件自己的样式则写进各自的 <style scoped>，不污染全局。当你的工程从"Hello 一个组件"长到几十个组件时，"一眼知道某个功能该去哪改"就全靠这套约定。

Vite 里还有个执行脚本的概念值得当一回事：npm run dev 起开发服务器，npm run build 产出可部署的静态文件，npm run preview 在本地预演构建结果。三条命令在工程师手里翻来覆去地用，你在 3.1 已见过一模一样的这套三角动作。把它们的用途钉牢，之后的构建与部署话题（如 6.2 路由的历史模式要配后端回退）才有一个可落脚的入口。

顺带记住这些命令都声明在 package.json 的 scripts 字段里——新建脚本、改启动参数、看某条命令到底执行了什么，都在这一处。它是工程运行的"总控面"，遇到"命令能跑但行为意外"时，多半该回这里看一眼是否配错。这条字段既是约定也是事实来源，改配置前先在这里确认它指向谁，能少很多踩坑。

本节要点回顾

• 脚手架同构：Vite 对 React/Vue 用法一致，语法不同。
• SFC 三块：template 界面、script 逻辑、style 样式，关注点内聚。
• 首个回路：改模板、加 ref、试 scoped，即时验证。
• 一个坑：脚本里 ref 要 .value，模板里自动解包。

工程跑起来了。下一节钻进 Vue 最常碰的模板语法与内置指令——插值、v-if、v-for、v-bind 这些怎么表达界面。