[!info] related notes

• 所属：Vite 基础 MOC
• 路线：Vite 学习路线 MOC
• 后续：配置与别名 · 环境变量

安装 Vite 并运行第一个应用

目标

在本机创建并运行一个官方模板项目，完成 dev → 修改可见 → build/preview 闭环。

这个场景为什么出现

新同学常卡在：Node 版本不对、包管理器不一致、模板选错、只跑 dev 从不验证 build。本 howto 固定最小验收。

前置条件

• Node.js 满足模板与 Vite 的 engines；2026-10-07 核对 Vite 8.3.3 / create-vite 9.2.1 要求 ^20.19.0 || >=22.12.0，新项目优先仍受维护的 LTS（见 Vite 指南）
• 可用的包管理器：pnpm / npm / yarn 之一

步骤

1. 创建项目

pnpm create vite inventory-admin --template react-ts
cd inventory-admin
pnpm install

说明：模板可换成 vue-ts / vanilla-ts 等；名称用业务域（库存后台）而不是 demo1。

2. 启动开发服务器

pnpm dev

浏览器打开终端提示的本地 URL（通常 http://localhost:5173）。

3. 做一次可见修改

编辑 src/App.tsx（或 Vue 的 App.vue），改标题文案为「库存后台」，保存后确认 HMR 更新。

4. 生产构建与预览

pnpm build
pnpm preview

preview 服务上一步生成的 dist/，不会随源码修改重新构建，也不是生产服务器。部署还要验证真实站点的 base、路由回退与 API 配置。模板版本会变化，已有项目应按锁文件与 package.json 中的脚本运行。

验收标准

• dev 能打开页面且无控制台致命错误
• 修改源码后页面更新（HMR 或可接受刷新）
• build 成功并生成 dist/
• preview 能访问构建产物

常见故障

现象	可能原因	处理
create 失败	网络/权限/Node 过旧	根据错误检查网络、目录权限与 Node engines
依赖装不上	锁文件/包管理器混用	统一 pnpm 或 npm
端口占用	5173 被占	先看实际监听 URL；需要固定端口时配置 server.port 与 strictPort

自测题

1. 为什么验收必须包含 build？
2. 模板里的 index.html 在项目根目录意味着什么？

参考答案

1. dev 与 build 是不同管线，只验收 dev 无法保证可部署产物。
2. HTML 是应用入口，由 Vite 在 dev/build 中作为根文档处理（与某些把 html 藏进 src 的工具不同）。

延伸阅读

资料	类型	支撑内容
Getting Started	官方	脚手架与脚本