摘要本文面向 Vue 2 新手和需要重构老项目的开发者手把手演示如何用 Vue CLI 从零搭建一个规范的 Vue 2 项目并进一步把 Webpack 构建迁移到 Vite体验秒级启动与热更新带来的开发效率提升。全流程已实测通过每一段代码、每一条命令都在真实项目中跑过并验证了浏览器渲染结果。前言虽然 Vue 3 已经发布多时但在实际开发和维护中Vue 2 依然占据着巨大的市场份额。对于新手或需要重构老项目的开发者来说如何从零搭建一个规范的 Vue 2 项目是必备技能。本文将带你从零开始使用官方脚手架 Vue CLI 搭建标准 Vue 2 项目并在最后教你如何将 Webpack 替换为 Vite体验极速启动的快乐。⚠️ 关于 Vue 2 的生命周期Vue 2.7.16 是 Vue 2 的最后一个版本已于 2023-12-31 停止维护不再有安全更新。存量项目维护没问题但如果这是全新项目且需要长期演进建议直接上 Vue 3。本文针对的是「必须用 Vue 2」的场景。第一阶段环境准备与基础搭建第一步环境准备安装 Node.js建议 18 LTS 及以上下载地址安装 Git下载地址Node 自带 npm无需单独下载。验证安装node -v npm -v能正常显示版本号说明环境准备就绪。第二步全局安装 Vue CLInpm install -g vue/cli第三步创建 Vue 2 项目在目标文件夹下执行vue create my-vue2-project进入交互式界面后关键选择如下选项选择原因预设Manually select features默认是 Vue 3要手动选功能功能勾选 Babel、Router、Vuex、ESLint核心插件Vue 版本2.x⚠️ 最关键的一步务必选 2.x路由模式YHistory 模式单页应用推荐URL 无#CSS 预处理器按需Less / Sass / Stylus后续 Vite 也需要对应编译包Linter 配置ESLint Standard config本文后续会升级为 ESLint 9校验时机Lint on save保存时检查配置文件位置In dedicated config files独立配置文件结构更清晰等待依赖安装完成项目创建好了。第四步启动项目cd my-vue2-project npm run serve终端会显示访问地址通常是http://localhost:8080。初始项目结构速览public/index.html页面模板Vue CLI 特有src/main.js入口初始化 Vue 实例vue.config.jsWebpack 配置迁移时要删babel.config.jsBabel 配置迁移时要删第二阶段迁移到 Vite 核心实战Vue CLI 基于 Webpack项目变大后启动和热更新会明显变慢。Vite 用原生 ESM启动是秒级的。⚠️ 迁移前必读两个“看不见的坑”在动手前先说清楚两个照着错误教程做会掉进去的坑 坑 ADev 白屏但 Prod 正常原项目src/router/index.js里有这么一行base: process.env.BASE_URL, // ← 这是 Webpack 的写法Vite 里没有process.env这个对象。后果是Dev 模式直接抛ReferenceError: process is not defined页面完全空白。Prod 模式Vite 构建时把process.env替换成{}于是base静默变成undefined——不报错但 base 配置丢了部署到子路径时 404。最坑的地方在于 Prod 能跑测试很容易漏过去。必须手动改。 坑 B搜process.env.VUE_APP_搜不到它网上很多教程说「全局搜索process.env.VUE_APP_全部替换」。但上面那行是process.env.BASE_URL不带VUE_APP_前缀按这个模式搜索会被整个漏掉。正确的搜索关键词是process.env.不带前缀。第一步改写 package.json删除所有 Vue CLI 相关依赖vue/cli-plugin-*、vue-template-compiler以及这些在 Vite 下完全用不到的包babel/core、babel/eslint-parser—— Vite 用 esbuild 转译。less-loader——Webpack 的 loaderVite 直接用less留着纯属多余。vue/eslint-config-standard——vue-cli 专属依赖 Webpack 体系。同时必须把 Vue 版本升到^2.7.16vitejs/plugin-vue22.3.x的 peer 要求是vue: ^2.7.0-0而 vue create 生成的是^2.6.14——一旦命中 2.6.x 就会构建失败。最终package.json参考{ name: my-vue2-project, type: module, engines: { node: 18.0.0 }, scripts: { dev: vite, build: vite build, preview: vite preview, lint: eslint ., lint:fix: eslint . --fix }, dependencies: { vue: ^2.7.16, vue-router: ^3.6.5, vuex: ^3.6.2 }, devDependencies: { vitejs/plugin-vue2: ^2.3.4, eslint: ^9.39.5, eslint-plugin-vue: ^10.11.1, less: ^4.9.1, neostandard: ^0.14.1, vite: ^5.4.21, vue-eslint-parser: ^10.4.1 } }neostandard是eslint-config-standard的现代继任者完美支持 ESLint 9/10。第二步删除 Vue CLI 残留文件rm babel.config.js vue.config.js .eslintrc.js⚠️vue.config.js一定要删。它留着不影响 Vite但会误导后来的人以为还在用 Webpack。第三步移动 index.html 并清理 EJS 语法Vue CLI 用public/index.htmlVite 要求index.html在项目根目录。mv public/index.html index.html原文件里有两处 EJS 语法必须改% BASE_URL %favicon.ico改为/favicon.ico标题可以直接写死也可以用 Vite 的环境变量占位符。Vite 的 HTML 环境变量语法是%变量名%不含空格、不带!DOCTYPE html html langzh-CN head meta charsetUTF-8 / link relicon href/favicon.ico / title%VITE_APP_TITLE%/title /head body div idapp/div script typemodule src/src/main.js/script /body /html 很多人会写成% VITE_APP_TITLE %EJS 风格这样不会生效——Vite 的匹配规则是/%(\S?)%/g中间不允许有空格。写错时不报错只是占位符原样留在页面上。第四步创建 vite.config.js在项目根目录新建vite.config.js保持与 Vue CLI 一致的别名和端口习惯同时把代理和环境变量读取一并配好import { fileURLToPath, URL } from node:url import { defineConfig, loadEnv } from vite import vue from vitejs/plugin-vue2 export default defineConfig(({ mode }) { // loadEnv 的第三个参数传 表示读取全部变量含仅构建期使用的 const env loadEnv(mode, process.cwd(), ) return { plugins: [vue()], resolve: { alias: { // ESM 里没有 __dirname要用 import.meta.url 换算 : fileURLToPath(new URL(./src, import.meta.url)) } }, server: { port: Number(env.DEV_PORT) || 8080, proxy: { /api: { target: env.API_PROXY_TARGET || http://localhost:3000, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } }, build: { target: es2015, rollupOptions: { output: { manualChunks: { vue: [vue, vue-router, vuex] } } } } } })⚠️关于__dirname的坑网上常见的写法是path.resolve(__dirname, src)。加上type: module并改用import.meta.url才能彻底消除 CJS 警告。第五步调整源码与环境变量src/main.js保持原有的 Vue 2 实例化写法即可new Vue(...)。环境变量替换process.env.VUE_APP_XXX改为import.meta.env.VITE_XXX并把.env文件里的变量前缀改为VITE_。路由 baseprocess.env.BASE_URL改为import.meta.env.BASE_URLVite 内置提供无需自己定义。第六步清理并重新安装删除原来的node_modules和package-lock.json或yarn.lock然后重新安装并启动npm install npm run dev第三阶段实战避坑指南常见报错解决在迁移过程中由于网络环境或依赖版本变动很容易遇到以下报错以下是解决方案 坑 1npm install 报错 ERESOLVE unable to resolve dependency tree原因ESLint 配置包与插件版本不兼容如vue/eslint-config-standard要求eslint-plugin-vue^7.0.0而项目里装成了 8.x。解决不要盲目用--legacy-peer-deps掩盖问题。正确做法是移除vue/eslint-config-standard这类 vue-cli 专属包升级到 ESLint 9 Flat Config neostandard从根源上消除冲突。 坑 2npm install 报错 network read ECONNRESET原因国内网络环境连接 npm 官方源不稳定连接被重置。解决切换为淘宝阿里镜像源。npm config set registry https://registry.npmmirror.com配置后重新执行npm install即可。 坑 3页面白屏或控制台报错 process is not defined原因Vite 里没有process.env这个 Node.js 环境变量对象。解决全局搜索process.env.按变量类型分别替换为import.meta.env.VITE_XXX或import.meta.env.BASE_URL。 坑 4启动时报错找不到 less 或 sass原因Vite 内置了预处理器支持但不会自动安装对应的编译包同时less-loader是 Webpack 专属Vite 下不需要。解决只装编译包本身以 less 为例。npm install less -D 坑 5jsconfig.json 满屏红色波浪线原因VS Code 的类型检查无法解析 Vite 的特殊别名或import.meta环境变量。解决不要直接关闭检查而是补全jsconfig.json的types和paths{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] }, types: [vite/client] }, exclude: [node_modules, dist] }总结通过以上步骤我们成功从 0 到 1 搭建了标准的 Vue 2 项目并顺利迁移到了 Vite 构建。遇到报错不要慌仔细看终端的报错提示往往就是版本冲突或语法不兼容导致的。如果在迁移过程中遇到其他具体报错欢迎在评论区留言交流
