前端工程化 / 系统课时

创建最小 Vite 项目

创建最小 Vite 项目

本课从空目录创建一个可运行的原生 JavaScript Vite 项目,并通过浏览器和终端完成验证。完成后,你将能定位 HTML 入口、JavaScript 入口与默认 npm 脚本,为后续修改配置和排查启动问题建立可靠基线。

学习目标

  • 使用官方 create-vite 脚手架创建并启动最小项目
  • 识别 index.html、src/main.js 与 package.json 的职责
  • 根据终端输出验证开发服务器是否正常工作

前置检查

Vite 8 要求 Node.js 20.19+ 或 22.12+。先在终端确认 Node.js 与 npm 已可用;若版本不满足要求,应先升级 Node.js,再创建项目。

bash
node -v
npm -v

预期输出

text
v<NODE_VERSION>
<NPM_VERSION>

<NODE_VERSION> 与 <NPM_VERSION> 会随本机环境变化。Node.js 版本应满足前述范围,否则脚手架或开发服务器可能直接拒绝启动。

创建并启动项目

下面使用原生 JavaScript 模板创建 vite-minimal。--no-interactive 关闭交互提问,适合复制执行;目标目录必须不存在或为空。

bash
npm create vite@latest vite-minimal -- --template vanilla --no-interactive
cd vite-minimal
npm install
npm run dev -- --host 127.0.0.1

预期输出

text
Scaffolding project in <PATH>/vite-minimal...
Done. Now run:
  cd vite-minimal
  npm install
  npm run dev

VITE v<VITE_VERSION> ready in <TIME> ms
Local: http://127.0.0.1:<PORT>/

脚手架版本、耗时、路径和端口可能不同。终端出现本地访问地址后,在浏览器打开该地址;看到模板页面即表示依赖安装、入口解析和开发服务器都已正常工作。验证结束后按 Ctrl+C 停止服务。

识别入口与默认脚本

原生模板可能附带示例图片或演示模块,但核心结构可以缩减为以下几项:

text
vite-minimal/
├── index.html
├── package.json
├── public/
└── src/
    ├── main.js
    └── style.css

index.html 位于项目根目录,它不是简单复制到服务器的静态文件,而是 Vite 在开发和构建阶段处理的 HTML 入口。页面中的模块脚本继续指向 JavaScript 入口。

html
<div id="app"></div>
<script type="module" src="/src/main.js"></script>

这是入口关系的片段示例。src/main.js 负责导入样式、组件或其他模块,并把页面内容挂载到 #app。public/ 中的文件按原文件名提供,适合不需要经过模块处理的资源。

package.json 中的默认脚本把 npm 命令映射到 Vite CLI:

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

这是配置片段,不需要单独执行。运行 npm run dev 时,npm 实际调用本项目依赖中的 vite,因此不必全局安装 Vite。

修改并验证热更新

保持开发服务器运行,编辑 src/main.js 中页面可见的文字并保存。浏览器应自动更新,通常不需要手动刷新;终端也不应出现编译错误。若页面没有变化,依次确认文件已保存、浏览器地址来自当前终端、编辑的是当前项目目录。

遇到启动失败时,优先检查以下问题:

  • 出现 Node.js 版本错误:升级到受支持版本后删除 node_modules,再执行 npm install
  • 出现找不到 package.json:确认终端当前目录是 vite-minimal
  • 默认端口被占用:读取终端实际打印的新端口,不要固定猜测为 5173
  • 页面空白但服务已启动:查看浏览器控制台,并检查 index.html 中的模块入口路径
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建最小 Vite 项目

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通