Vue 3 现代工程搭建：create-vue、Vite 8 与 TypeScript
Vue 3 现代工程搭建：create-vue、Vite 8 与 TypeScript
2026 年新建 Vue 单页应用时，推荐起点是官方脚手架 create-vue。它生成 Vue 3 + Vite 项目，并按选择加入 TypeScript、Vue Router、Pinia、Vitest、端到端测试、ESLint 和 Prettier。Vue CLI 已进入维护模式，不再适合作为新项目教程的主线。
本文以 2026-08-31 的稳定技术栈为基线：Vue 3.5、Vite 8、Vue Router 5、Pinia 4 和 TypeScript 7。版本会变化，所以项目里应提交 lockfile，并通过自动化依赖更新逐步升级。
一、先确认该不该直接使用 Vite
直接使用 Vue + Vite 很适合以下项目：
- 后台管理、桌面 Web、嵌入式页面等 SPA；
- 前后端分离，后端已经提供 API；
- 不依赖搜索引擎抓取首屏 HTML；
- 希望自己掌控路由、状态管理和部署方式。
如果项目明确需要 SSR、服务端路由、服务端数据获取、混合渲染或完整的全栈约定，可以优先评估 Nuxt。不要因为 Nuxt 功能更多就默认使用它；纯 SPA 用 Vite 的结构更轻。
二、准备 Node.js
当前 Vue 官方快速上手页面要求 create-vue 使用：
Node.js ^22.18.0 || >=24.12.0
先检查本机版本：
node --version
npm --version
Vite 8 自身的最低要求是 Node 20.19+ 或 22.12+，但 create-vue 的要求更高。新建项目时应以脚手架要求为准，否则可能出现“Vite 能运行，但脚手架不能启动”的情况。
推荐使用 fnm、nvm 或 Volta 管理 Node 版本，并在团队项目中提交 .nvmrc、.node-version 或 Volta 配置，避免开发机和 CI 使用不同主版本。
三、创建项目
在准备存放项目的目录运行：
npm create vue@latest
一个偏工程化、但不过度配置的选择可以是：
Project name: vue-app
Add TypeScript? Yes
Add JSX Support? No
Add Vue Router? Yes（多页面视图时选择）
Add Pinia? Yes（确实有跨页面共享状态时选择）
Add Vitest? Yes
Add an End-to-End Testing Solution? 按团队选择
Add ESLint? Yes
Add Prettier? 按团队选择
Add Vue DevTools extension? 按需选择
这里没有一套对所有项目都正确的答案：
- JSX 不是使用 Vue 的前提，普通项目使用 SFC 模板即可；
- 只有一个页面时可以先不装 Router；
- 只在父子组件间传值时不需要 Pinia；
- ESLint 负责发现问题，Prettier 负责统一格式，两者职责不同。
安装依赖并启动：
cd vue-app
npm install
npm run dev
生产构建和本地预览：
npm run build
npm run preview
preview 只用于本地检查构建产物，不是生产服务器。
四、认识生成的目录
典型目录如下：
vue-app/
├── public/ # 原样复制的静态资源
├── src/
│ ├── assets/ # 会进入构建管线的资源
│ ├── components/ # 可复用组件
│ ├── router/ # 选择 Router 后生成
│ ├── stores/ # 选择 Pinia 后生成
│ ├── App.vue # 根组件
│ └── main.ts # 应用入口
├── index.html # Vite 的 HTML 入口
├── vite.config.ts
└── package.json
入口文件通常非常短：
import { createApp } from 'vue'
import App from './App.vue'
import './assets/main.css'
createApp(App).mount('#app')
如果选择了 Router 和 Pinia，插件要在 mount() 前注册：
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'
const app = createApp(App)
app.use(createPinia())
app.use(router)
app.mount('#app')
五、用现代 SFC 写第一个组件
官方模板默认使用 Composition API 和 <script setup>。一个最小组件可以写成：
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
</script>
<template>
<main class="counter">
<h1>Vue 3 + TypeScript</h1>
<button type="button" @click="count++">
已点击 {{ count }} 次
</button>
</main>
</template>
<style scoped>
.counter {
max-width: 40rem;
margin: 4rem auto;
}
</style>
模板中会自动解包 ref，所以写 count；脚本中读取或修改时则写 count.value。事件表达式里的 count++ 属于模板，因此也不需要 .value。
六、编辑器和类型检查
VS Code 推荐安装官方扩展 Vue - Official（扩展 ID：Vue.volar）。旧项目如果仍安装 Vetur，应避免让两个 Vue 语言服务同时处理同一工作区。
Vite 只转译 TypeScript，不负责完整的类型检查。构建脚本通常会结合 vue-tsc：
{
"scripts": {
"dev": "vite",
"build": "run-p type-check \"build-only {@}\" --",
"build-only": "vite build",
"type-check": "vue-tsc --build"
}
}
具体脚本以 create-vue 生成结果为准，不必手工复制旧教程里的配置。
七、Vite 8 带来了什么
Vite 8 使用 Rolldown 作为统一的 Rust 打包器，取代过去“开发阶段由 esbuild、生产阶段由 Rollup”这一双打包器结构。大多数普通 Vue 项目不需要修改业务代码，但从旧 Vite 升级时仍应：
- 阅读对应版本的迁移指南；
- 检查自定义
rollupOptions、构建插件和 CommonJS 依赖； - 在 CI 中执行类型检查、单元测试和生产构建；
- 对大型项目比较构建产物、分包和运行时行为。
不要仅凭开发服务器能启动就认为升级完成。
八、旧 Vue CLI 项目怎么处理
旧项目可以继续维护，但新功能开发前应评估迁移到 Vite：
process.env.VUE_APP_*改为import.meta.env.VITE_*；require.context通常改为import.meta.glob；vue.config.js中的 webpack 配置需要映射到 Vite/Rolldown 配置；- 检查依赖是否依赖 Node polyfill 或 webpack 专有 loader；
- 先迁构建工具，再做 Composition API 等业务重构，降低一次性变更风险。
小结
新项目使用 create-vue，让脚手架选择相互兼容的 Vue、Vite 和 TypeScript 依赖；根据实际需求选择 Router、Pinia 和测试工具。Vite 8 是当前构建基线，Vue CLI 只应出现在旧项目维护章节中。
官方资料
