版本: 3.1.0 文档中心

工程化起点：Node.js、npm 与 Vite 如何让 Vue 项目跑起来

当你学习 HTML、CSS、JavaScript、Fetch / Ajax 时，通常是在浏览器里直接写代码。你可能会新建一个 index.html，再通过 <script> 标签写入逻辑，这种方式非常适合打基础。

但当你开始进入 Vue 3、React、TypeScript 等现代前端框架时，很多新名词会突然一起出现：

Node.js
npm
package.json
import / export
Vite
.vue

这时很多初学者会产生一个典型困惑：

我明明已经会写 JavaScript 了，为什么这些代码不能直接在浏览器里跑？为什么还要装一堆工具？

这篇文章就是用来解决这个断层的。

1. 为什么现代前端项目不再只是一个 HTML 文件

在最基础的网页开发中，一个页面通常长这样：

project/
  index.html
  style.css
  main.js

浏览器打开 index.html，就能直接看到页面效果。

但当项目逐渐变复杂时，会出现很多现实问题：

代码越来越多，难以维护
文件之间需要模块化拆分
需要安装第三方依赖
需要本地开发服务器
需要热更新
需要把源码打包成可部署版本

这时，前端项目就不再只是“几个静态文件”，而会进入 工程化开发 阶段。

你可以先这样理解：

静态网页开发解决的是“能不能做出页面”；工程化开发解决的是“怎么把一个真实项目组织、运行、构建、部署起来”。

2. Node.js 到底是什么

Node.js 不是前端框架，也不是浏览器插件。

它的本质是：

一个让 JavaScript 可以脱离浏览器运行的环境。

在浏览器里，JavaScript 主要用于：

操作 DOM
响应点击事件
发起网络请求

而在 Node.js 里，JavaScript 可以用于：

运行构建工具
安装和管理依赖
启动本地开发服务器
执行自动化脚本

这就是为什么学 Vue 时，明明最后页面还是跑在浏览器里，却还要先安装 Node.js。

2.1 浏览器环境和 Node 环境有什么区别

它们都能运行 JavaScript，但能力不完全一样。

例如：

浏览器里有 document、window
Node.js 里没有浏览器 DOM
Node.js 更擅长文件、命令行、工具脚本处理

所以你要建立一个清晰认知：

页面最终运行在浏览器
工程化工具通常运行在 Node.js 环境

3. npm 是什么

npm 是 Node.js 自带的包管理工具，全称是 Node Package Manager。

你可以把它理解为：

用来安装、更新和管理 JavaScript 项目依赖的软件工具。

例如，当你想在项目里使用 Vue 时，并不是把 Vue 代码一行行复制进来，而是通过包管理器安装：

npm install vue

这时 npm 会帮你：

下载依赖包
记录依赖信息
放入项目可用的位置

3.1 `package.json` 是什么

几乎每个现代前端项目里都会有一个 package.json 文件。

它通常用来记录：

项目名称
项目版本
依赖包
可执行脚本

一个简化示例如下：

{
  "name": "my-vue-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.0"
  }
}

你可以先重点看懂两个部分：

dependencies：这个项目依赖哪些库
scripts：这个项目有哪些常用命令

3.2 `npm install` 到底在做什么

当你执行：

npm install

npm 会根据 package.json 下载当前项目所需的依赖。

如果你刚从别人的仓库把代码拉下来，往往第一件事就是先执行这条命令，否则很多包都还没装，项目根本跑不起来。

4. 什么是模块化，为什么会出现 `import / export`

在早期网页开发里，我们经常这样引入多个脚本：

<script src="utils.js"></script>
<script src="api.js"></script>
<script src="main.js"></script>

这当然能工作，但随着项目变大，会带来很多问题：

文件依赖顺序容易出错
全局变量容易污染
代码复用不清晰
协作维护困难

于是现代前端更常使用 模块化。

例如：

// utils.js
export function formatPrice(price) {
  // 提取公共格式化逻辑，供其他模块复用
  return "￥" + price;
}

// main.js
import { formatPrice } from "./utils.js";

// 导入后即可直接使用
console.log(formatPrice(99));

这样做的好处是：

一个文件负责一块逻辑
依赖关系更清晰
复用更容易
更适合大型项目维护

4.1 为什么原生浏览器时代你几乎没怎么见过它

因为在最基础的学习阶段，很多教程都是直接用单个 HTML 文件演示。

而 import / export 这种模块化能力，在现代项目里通常会结合工程化工具一起使用，所以你会在 Vue、Vite、React 项目里更频繁地看到它。

5. Vite 是什么

Vite 是现代前端非常流行的构建工具和开发服务器。

你可以把它理解成一个“前端项目启动器 + 开发助手 + 构建工具”。

它主要解决这些问题：

帮你启动本地开发服务器
让项目支持热更新
处理模块化导入
处理 .vue、TypeScript、CSS 等源码
在发布前把项目构建成可部署产物

5.1 为什么 Vue 项目经常搭配 Vite

因为 Vue 项目常常需要：

识别 .vue 单文件组件
支持模块化导入
更快的本地启动速度
更顺滑的热更新体验

而 Vite 正好很适合这套需求。

所以你看到的很多 Vue 3 教程，默认都会说：

用 Vite + Vue 3 创建项目

6. 用 Vite 创建第一个 Vue 项目

如果你已经安装好 Node.js，就可以开始创建一个 Vue 3 项目。

6.1 创建命令

npm create vite@latest my-vue-app -- --template vue

这条命令的意思是：

使用最新的 Vite 创建项目
项目文件夹名叫 my-vue-app
使用 vue 模板

6.2 安装依赖

cd my-vue-app
npm install

6.3 启动项目

npm run dev

如果启动成功，终端通常会看到类似输出：

  VITE v5.x ready in 300 ms

  Local:   http://localhost:5173/

然后你在浏览器打开这个地址，就能看到页面。

7. 看懂一个 Vue 项目的基本目录结构

创建完成后，你通常会看到类似结构：

my-vue-app/
  index.html
  package.json
  node_modules/
  src/
    main.js
    App.vue
    components/
    assets/

下面是最重要的几个位置。

7.1 `index.html`

这是浏览器真正打开的入口页面。

里面通常会有一个挂载点：

<div id="app"></div>

Vue 应用会被挂载到这个容器上。

7.2 `src/main.js`

这是 JavaScript 入口文件，最常见的内容类似这样：

import { createApp } from "vue";
import App from "./App.vue";

// 创建应用并挂载到页面入口节点
createApp(App).mount("#app");

它做了三件事：

导入 Vue 的 createApp
导入根组件 App.vue
把整个应用挂载到 #app

7.3 `src/App.vue`

这是根组件，也是整个应用最外层的组件。

一个 .vue 文件往往会同时包含：

<template>：页面结构
<script>：逻辑代码
<style>：样式代码

例如：

<script setup>
// 在 script 中定义模板要使用的数据
const title = "Hello Vue";
</script>

<template>
  <h1>{{ title }}</h1>
</template>

<style>
h1 {
  color: #42b883;
}
</style>

7.4 `components/`

这里通常放可复用组件，例如：

Header.vue
TodoItem.vue
ArticleCard.vue

这就是 Vue 组件化开发的落点。

8. `.vue` 文件为什么能工作

这是很多初学者第一次接触 Vue 时最疑惑的问题之一。

浏览器本身并不认识 .vue 文件。

它能运行，并不是因为浏览器直接理解了它，而是因为：

Vite 和 Vue 的相关工具，会在开发和构建阶段把 .vue 文件转换成浏览器能执行的 JavaScript、HTML 和 CSS。

所以你要记住：

.vue 不是浏览器原生标准文件
.vue 需要工具链处理
Vite 正是在这里发挥了关键作用

这也是为什么 .vue 文件不能直接双击运行。

9. `npm run dev`、`build`、`preview` 分别是什么

在 package.json 里，你经常会看到这样的脚本：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

它们的含义通常是：

9.1 `npm run dev`

启动开发服务器，供你本地写代码、看效果、热更新。

9.2 `npm run build`

把源码打包成适合上线部署的静态文件，通常会输出到 dist/ 目录。

9.3 `npm run preview`

用本地服务器预览打包后的结果，方便确认生产构建是否正常。

你可以这样区分：

dev：开发时用
build：发布前打包
preview：本地验证打包结果

10. 初学者最常见的几个坑

10.1 没装 Node.js

如果连 Node.js 都没装，npm 命令通常就无法使用。

10.2 创建项目后没有先安装依赖

很多人执行完创建命令后，直接就想 npm run dev，结果报错。

因为依赖还没安装，应该先执行：

npm install

10.3 端口被占用

如果 5173 端口已经被别的程序占用，Vite 可能会自动换端口，或者直接提示冲突。

10.4 以为 `.vue` 文件可以直接双击打开

.vue 文件是工程化源码，不是浏览器可以直接运行的最终页面。

10.5 只会写语法，不理解项目入口

如果你不知道 index.html、main.js、App.vue 分别在做什么，后面学组件通信、路由、状态管理时会越来越乱。

11. 工程化进阶与补充

在掌握了基础的 Node.js 和 Vite 运行机制后，实际开发中你还会遇到以下几个高频的工程化概念和工具。

11.1 基础命令行认知

作为前端开发，虽然不需要成为 Linux 运维专家，但基本的终端命令是必须要掌握的：

cd <目录名>：进入某个文件夹（Change Directory）。
cd ..：返回上一级目录。
dir (Windows) / ls (Mac/Linux)：查看当前目录下的文件列表。
npm install：根据 package.json 安装依赖。
npm run <脚本名>：运行 package.json 中 scripts 定义的命令（如 dev、build）。
注意：所有的 npm 命令都必须在包含 package.json 的项目根目录下执行，否则会报错。

11.2 npx 与 pnpm 是什么

npx：npm 自带的命令，用来“临时执行”某个包，而不需要全局安装。比如有些命令你只用一次，用 npx 就会自动下载执行完后不留痕迹。
pnpm：目前最推荐的包管理工具，它是 npm 的替代品。相比 npm，它的下载速度更快，并且通过硬链接机制极大地节省了磁盘空间。现在很多团队都会要求用 pnpm install 代替 npm install。

11.3 Vue CLI 去哪了？

如果你搜索一些旧教程，可能会看到使用 vue create my-project 或者提到 Vue CLI。

Vue CLI：Vue 官方以前基于 Webpack 的老牌脚手架工具。
Vite：现在官方强烈推荐的新一代构建工具。它的启动速度比 Vue CLI 快几十倍。
结论：新项目无脑选 Vite，只有在维护老项目时，你才需要了解 Vue CLI。

11.4 推荐的 VS Code 插件

工欲善其事，必先利其器。开发 Vue 项目，这几个插件是标配：

Vue - Official（原 Volar）：Vue 官方插件，提供代码高亮、语法提示。
ESLint：代码规范检查工具，帮你找出代码里的潜在错误。
Prettier - Code formatter：代码格式化工具，按保存键自动排版代码。
Auto Rename Tag：修改 HTML 标签时，自动修改对应的闭合标签。
Path Intellisense：路径自动补全插件，引入文件时不用再盲猜路径。

11.5 环境变量与 `.env` 文件

真实项目中，开发环境（本地调试）和生产环境（上线后）调用的接口地址通常是不一样的。 Vite 提供了非常优雅的解决方案：

在项目根目录创建 .env.development 和 .env.production 文件。
在里面定义变量，注意必须以 VITE_ 开头，例如：VITE_BASE_URL=http://api.dev.com。
在代码中，可以通过 import.meta.env.VITE_BASE_URL 来读取。
这样，npm run dev 时会自动读取 development 里的变量，npm run build 时会自动读取 production 里的变量，不需要手动改代码。

11.6 团队协作的工程化习惯

进入团队后，代码就不是你一个人的了，几个基本习惯能让你避免成为“猪队友”：

永远不在主分支直接开发：基于主分支拉取新分支（如 feature/login），开发完再提合并请求。
提交前自己先跑一遍：确保 npm run dev 不报错，页面能打开，最好也试一下 npm run build 看能否成功打包。
清晰的 Commit 消息：不要只写“更新”或“修改 bug”，写清楚改了什么，例如 feat: 新增员工列表页面 或 fix: 修复登录按钮点击无效的问题。
不要提交不相关的文件：node_modules 绝对不能提交（通过 .gitignore 忽略），只提交项目源码。

12. 这篇知识和 Vue 学习怎么衔接

当你理解了 Node.js、npm、Vite 和项目结构后，再回头看 Vue 代码，很多原本抽象的东西会立刻清晰：

为什么能写 import
为什么 App.vue 能被导入
为什么项目要用 npm run dev 启动
为什么 createApp(App).mount("#app") 会出现在 main.js

这时你再进入 Vue 3 的模板语法、响应式数据、组件化开发，学习路径就会顺畅很多。

13. 小结

把这一篇的知识串起来，本质上就是：

Node.js 提供运行前端工具链的环境
npm 负责管理项目依赖和脚本
模块化让代码可以拆分和导入
Vite 负责开发服务器和构建流程
Vue 则建立在这套工程化基础上开发界面

理解这条链路后，你就完成了从“浏览器里写几个脚本”到“真正启动一个现代前端项目”的关键过渡。