说实话vue2创建项目看起来是个特别入门的话题但我带过的小组里几乎每一个新人都在这件事上栽过跟头。不是vue create跑不起来而是跑起来之后发现各种版本冲突、依赖报错、目录混乱、联调环境配不明白——等到项目真正跑顺一天就过去了。这篇文章我想把这套流程从头到尾捋一遍结合我这些年实际创建Vue2项目的经验把我踩过的坑、验证过的方案、以及最终稳定可复用的配置方式都写出来。无论你是刚接触Vue2的新手还是准备给团队搭一个规范项目基座的开发者这篇内容应该能帮你少走很多弯路。1. 动手之前先想清楚脚手架选型很多教程上来就是一句运行npm install -g vue/cli然后vue create项目名但真正落到企业项目里选型这一步才是决定后面顺不顺利的关键。我先说结论Vue2项目长期维护、需要稳定生态的优先选Vue CLI 5追求极致启动速度的可以考虑Vite 兼容插件的方式纯手动搭建Webpack不是不行但我个人不推荐除非你有充分的定制需求。1.1 三种方式的取舍逻辑先看官方脚手架。Vue CLI从4.x升级到5.x之后底层Webpack升级到了5对现代Node版本的支持也好了很多。Vue2项目的标准姿势现在普遍是Vue CLI 5.0.8 Vue 2.7.x这是最被广泛验证过、遇到问题社区资料最多的组合。你用Vue CLI创建项目时默认会安装Vue 3.x模板但可以在交互选项里手动选择Vue 2版本也可以通过指定preset来快速生成后面我会详细说。Vite方案在Vue3时代是主流但在Vue2场景下需要靠官方插件vitejs/plugin-vue2来支持SFC编译。它的优点是开发服务器冷启动快、热更新快这在大型项目里的体感差异非常明显缺点则是生态成熟度不如Vue CLI部分Vue2生态里的老库尤其是那些需要特殊Webpack处理的可能没法直接用。我的态度是如果是全新的、知道自己在做什么的Vue2项目Vite可以尝试如果是维护老项目或者团队普遍熟悉Vue CLI那还是选Vue CLI省心。手动搭建Webpack Vue2的方案理论上可以做到完全定制但你要自己去配置vue-loader、vue-template-compiler、CSS处理、HMR等一系列东西。我自己只在做一个需要深度定制构建流程的组件库时用过这种方式普通业务项目完全没必要。1.2 版本兼容性检查表这里直接给出一份我实测过的版本搭配方案按推荐程度排序场景推荐Node版本脚手架/构建工具备注标准Vue2项目长期维护16.20.x 或 18.19.xVue CLI 5.0.8最稳资料最多Vue2老项目升级现有CLI14.x 或 16.xVue CLI 4.5.x老项目慎上Node 20追求开发体验的新项目18.xVite 4 vitejs/plugin-vue2冷启动快但要注意兼容性Node 20.x Vue220.xVue CLI 5.0.8可用但node-sass等老依赖会报错踩过的坑必须提一句千万别在Vue2项目里用node-sass除非你确认Node版本和它编译的二进制文件完全匹配。我自己后来全部换成了sass也就是Dart Sass配合Vue CLI 5完全没问题。你在创建项目选择CSS预处理器时也尽量选sass而不是node-sassVue CLI 5里选项名已经不怎么区分了但安装依赖时要注意看装的是哪个。1.3 为什么企业项目普遍锁死Vue2很多人会问新项目为什么不用Vue3这里不讨论技术优劣只说现实因素很多现存业务系统的依赖库、组件库、内部脚手架都是基于Vue2写的升级到Vue3意味着整套基础设施要重新适配成本极高。这种情况下创建Vue2项目并不是从零开始而是要在一堆老链路里插入一个新的子应用或者重构入口。所以你会看到即使社区都在推Vue3Vue2项目在企业里依然大量存在。2. vue create初始化过程中的选项决策确定用Vue CLI之后就进入实际创建流程了。先确保你已经安装了Vue CLI# 全局安装或升级到指定版本 npm install -g vue/cli5.0.8 # 查看版本验证安装成功 vue --version如果之前装过Vue CLI 3或4最好先卸载再安装5避免命令版本混乱。卸载命令是npm uninstall -g vue/cli。另外如果你的日常Node版本是20比如你要同时维护Vue3项目我建议用nvm或fnm这类Node版本管理工具在Vue2项目目录下切到Node 16。后面所有命令都在Node 16环境下跑。2.1 交互模式还是预设模式直接运行vue create my-vue2-project会进入交互式选择。这里逐个说一下我推荐的选项第一步选择预设建议选Manually select features不要用默认的Default ([Vue 3] babel, eslint)因为默认预设是Vue3。手动勾选时我一般这样选Babel必选编译ES6语法TypeScript如果项目需要就选不需要就别选Vue2 TS需要额外的vue-class-component配置复杂度会上去Router和Vuex根据实际需要选。这里有个版本陷阱Vue2项目必须用vue-router3和vuex3Vue CLI会自动装对应版本但你如果手动作业很容易装成vue-router4或vuex4这在Vue2里直接跑不起来CSS Pre-processors我选Dart SassLinter / Formatter推荐选ESLint Prettier这是当前最普及的组合Unit Testing / E2E Testing根据需求选不需要就不勾避免初始化时装一堆用不上的东西。选完特性之后还会问你要不要把这些选择存成preset方便下次复用。团队协作场景我强烈建议存一下并且把preset文件提交到代码仓库后续新成员创建项目时直接选相同的preset能保证所有子应用的基础配置完全一致。2.2 使用preset命令行创建如果你已经存了preset或者想通过命令直接指定Vue版本可以用这种方式vue create my-vue2-project -p my-preset-name如果不想提前存preset也可以这样先创建一个带预设的配置文件比如vue.config.js实际上preset可以放在项目根目录的preset.json里然后通过--preset参数指定vue create my-vue2-project --preset ./preset.jsonpreset.json的内容大致长这样{ useConfigFiles: true, cssPreprocessor: dart-sass, plugins: { vue/cli-plugin-babel: {}, vue/cli-plugin-eslint: { config: prettier, lintOn: [save, commit] }, vue/cli-plugin-router: { historyMode: true }, vue/cli-plugin-vuex: {} }, vueVersion: 2 }这样创建的my-vue2-project直接就是Vue2版本不用再进去改。这里注意useConfigFiles设为true代表把Babel、ESLint配置都放在独立配置文件中而不是塞进package.json我个人更喜欢独立文件方式团队里review配置改动时更清晰。2.3 初始化完成后的第一轮目录检查项目创建成功后最好先别急着写代码先敲一遍这些命令cd my-vue2-project npm install npm run serve浏览器打开localhost:8080看到Vue2欢迎页说明基础链路通了。如果这一步出错大多是Node版本问题或npm源问题。npm源我建议先检查一下npm config get registry # 如果输出不是官方源或企业内网源建议设置一下 npm config set registry https://registry.npmmirror.com国内网络环境用镜像源能快非常多。但有一点要提醒镜像源和官方源切换可能会导致锁文件变化团队协作时最好统一配置源并把package-lock.json提交到仓库避免每个人本地装出来的依赖树不一样。3. npm install阶段最常见的两座大山初始化完成并不代表万事大吉。你在npm install时碰到的报错90%以上可以归成两类ERESOLVE依赖树冲突以及peerDependencies没有被正确安装导致运行时报找不到模块。3.1 ERESOLVE野生错误与它背后的依赖树逻辑npm 7之后对依赖冲突的检测严格了很多老项目经常出现这种报错npm ERR! ERESOLVE unable to resolve dependency tree npm ERR! While resolving: project-name0.1.0什么意思呢简单说就是两个包之间对某个第三方库的版本要求不一致。比如A包要求webpack^5.0B包要求webpack^4.0npm按照最严格规则无法自动调和就会整体拒绝安装。这在Vue2老项目里尤其常见因为很多老依赖的peerDependencies范围写得比较窄。解决办法有两个层级第一层看能不能升级或降级其中一个依赖让它们的版本范围交叠。这是最健康的解法但需要时间排查。第二层如果你确认冲突的包之间实际兼容可以使用--legacy-peer-deps或--force来绕过npm install --legacy-peer-deps这个参数被问得最多我对它的态度是能用但要用得明白。它本质上是让npm退回到npm 6的依赖解析逻辑忽略部分peer依赖冲突。但这不代表冲突不存在后续如果依赖间真的不兼容运行时才会暴露。所以我只在排查后确认冲突无关紧要时才会这么做并且会在项目的README里记录这个命令以及为什么需要它。其实更省心的做法是在项目的.npmrc里加上legacy-peer-depstrue这样团队成员执行npm install时就不用手动加参数了行为完全一致。3.2 cnpm引发的半残node_modules我有个同事在某公司用cnpm装依赖装完后npm run serve能跑起来但一执行ESLint就直接报Cannot find module eslint-config-standard查了一圈发现node_modules里根本没这个包。这就是cnpm早期版本的经典问题它对peerDependencies的处理逻辑跟npm并不完全一致经常导致部分peer依赖缺失。我个人的经验是Vue2项目经过多年沉淀依赖树本来就非常复杂peerDependencies、optionalDependencies、各种deprecated的包混在一起用非npm官方工具安装风险真的不小。如果你不是对cnpm的依赖处理机制有十足把握建议一律用npm网络慢就换镜像源不要图方便直接上cnpm。实在要用也得用最新版cnpm并且装完后跑一遍npm ls --depth0检查顶层依赖有没有缺失。3.3 锁文件与CI环境安装架构稳定的Vue2项目本地和CI用的安装命令最好统一本地npm install它会在已有package.json和package-lock.json基础上增量安装速度快CI环境npm ci它严格按照锁文件全新安装不会做任何增量解析能保证构建环境可复现。如果本地和CI之间存在依赖树不一致优先检查是否有一方用了--force或者--legacy-peer-deps。这个细节影响非常深远——很多本地能跑、CI挂了的诡异问题最后都查到了依赖树不一致上。4. 统一IDE与项目目录结构规划Vue CLI只负责生成骨架真正让项目变得像企业级的是IDE配置、目录结构和命名约定。很多项目创建完就开写业务结果代码量上来之后光找文件就很费劲。4.1 Vue2项目的IDE插件选择VS Code是事实标准但Vue2和Vue3的插件选择有个大坑Vue3项目主流是VolarVue Language FeaturesVue2项目老牌插件是Vetur。在Vue2项目里装上Volar而不做任何配置有概率出现模板类型检查不一致的问题。团队协作时更要统一要么全都用Vetur要么统一用Volar并开启其针对Vue2的支持模式。我建议Vue2项目直接用Vetur最省心。另外ESLint、Prettier、EditorConfig for VS Code这三个插件也是必须统一装的。配合项目根目录的.editorconfig文件能保证不同操作系统、不同编辑器下代码格式一致root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true.editorconfig的优先级其实高于编辑器自身设置只要团队成员都装了对应的IDE插件格式基本不会乱。再加上ESLint和Prettier配置等于做了双保险。4.2 src目录怎么划分才不容易乱这是我个人一直在用的Vue2项目目录结构不算权威但经过多个项目验证后足够清晰src/ ├── api/ # 接口请求 │ ├── modules/ # 按业务模块拆分 │ └── request.js # axios实例封装 ├── assets/ # 静态资源图片、全局样式 ├── components/ # 公共组件 │ ├── base/ # 纯展示型基础组件 │ └── business/ # 业务型复合组件 ├── directives/ # 自定义指令 ├── filters/ # 全局过滤器Vue3里已移除的概念Vue2仍常用 ├── mixins/ # 混入逻辑 ├── router/ # 路由配置 ├── store/ # Vuex状态管理 │ ├── modules/ # 按业务模块拆分 │ └── index.js ├── styles/ # 全局样式变量与公共样式 ├── utils/ # 纯工具函数 ├── views/ # 页面级组件 ├── App.vue └── main.js这个结构最重要的原则是把容易变化的模块拆分出去。比如接口请求单独放api/页面就不会直接依赖具体的url状态管理拆模块就不会在store/index.js里堆几千行。组件分base和business是为了让基础组件可以无脑复用而业务组件知道从哪个store取数据、调哪个接口。4.3 别名配置让import路径不再地狱组件层级深了之后相对路径../../../components/...非常容易写错。Vue CLI项目可以在根目录jsconfig.json里配置路径别名让编辑器和构建器都认{ compilerOptions: { baseUrl: ., paths: { /*: [src/*], api/*: [src/api/*], components/*: [src/components/*] } }, exclude: [node_modules, dist] }Vue CLI内部已经默认支持指向src但如果团队习惯用更多语义化别名就在这个文件里定义。注意配置完需要重启VS Code才能生效。这个文件不是webpack配置它只是给编辑器做智能提示用的真正让Webpack认识这些别名需要确认vue.config.js或者内部默认配置里有对应的resolve配置。好消息是Vue CLI 5内置了别名其余自定义别名需要在vue.config.js中配置chainWebpack才能让Webpack也识别。两者一定要保持一致。5. 环境变量与代理配置开发联调顺畅的关键Vue2项目创建好之后马上会面临一个问题前端怎么对接后端接口开发环境调测试环境构建之后走生产环境域名这个过程没配置好不但联调效率低还会出线上事故。5.1 环境变量文件怎么写Vue CLI约定根目录下的.env文件用来存环境变量文件名后缀代表不同环境.env.development对应开发环境.env.production对应生产构建。变量名必须以VUE_APP_开头才会被注入到客户端代码中# .env.development VUE_APP_BASE_API/api VUE_APP_ENVdevelopment # .env.production VUE_APP_BASE_API/prod-api VUE_APP_ENVproduction代码里可以通过process.env.VUE_APP_BASE_API拿到对应值。这个机制的底层逻辑是Vue CLI会把VUE_APP_开头的变量在编译阶段直接替换进代码里而不是运行时读取所以不要在代码里动态拼接process.env变量名。5.2 devServer代理跨域问题的正解前后端联调最常见的跨域问题实际上不需要后端开CORS也不需要前端装代理插件直接利用Vue CLI的devServer代理就能解决// vue.config.js module.exports { devServer: { port: 8080, proxy: { /api: { target: http://192.168.1.100:3000, changeOrigin: true, pathRewrite: { ^/api: } } } } }这样你在前端代码里请求/api/user/list的时候devServer会把请求转发到http://192.168.1.100:3000/user/list。changeOrigin: true很关键它会把请求头里的Host字段改成目标域名很多后端服务会校验这个字段不改容易收到403。pathRewrite要不要写取决于后端接口路径里是否带/api前缀。如果后端接口本身就是/api/user/list那就不需要重写如果后端接口是/user/list才需要把前缀剥离。这个对应关系一定要跟后端确认清楚我见过因为前缀没对齐而排查了一整天的情况。5.3 记住两个环境三份文件的思维实际项目里我习惯至少维护三份环境文件.env全局基础配置所有环境都生效.env.development开发环境专属.env.production生产构建专属。如果有测试环境、预发布环境可以再加.env.staging、.env.test并用--mode参数来指定构建模式npm run build -- --mode staging这个mode可以直接通过process.env.NODE_ENV或自定义变量来区分。环境变量文件的命名和运行模式是一一对应的如果文件名带点比如.env.local要注意它是否会被git跟踪.env.local这种通常应该写进.gitignore因为它往往包含本地敏感配置。6. 代码规范与提交规范创建项目时就要架好防线只把项目跑通不算完成一个能长期维护的Vue2项目必须在初始化阶段就搭好代码规范和提交规范。这一步做不做直接决定项目3个月之后是整洁还是灾难。6.1 ESLint Prettier的联动配置Vue CLI在初始化时如果勾选了Linter会自动生成eslintrc相关配置。我推荐选择ESLint Prettier预设。这两个工具的分工要搞清楚ESLint管代码质量未使用变量、未定义变量、禁止console提交等Prettier管代码格式缩进、引号、分号、换行。它们在个别规则上有重叠所以需要用eslint-config-prettier把两者可能冲突的规则关掉再用eslint-plugin-prettier把Prettier作为ESLint的一条规则运行。Vue CLI5预设里已经处理好了这些联动你只需要注意团队里别有人单独改.prettierrc导致格式失配。lintOnSave建议保持默认的true这样npm run serve时ESLint会在保存时给出提示。再配合.prettierrc里统一的双引号、分号、每行最大宽度等配置全团队的代码风格就能收敛。6.2 Husky与lint-staged实现提交前自动检查光有ESLint还不够因为新人完全不看编辑器警告直接提交的情况时有发生。拦截线下移放在git commit这个动作上才是可靠的防线。现在的husky10.x及以上用法跟老版本不同初始化命令是npm install -D husky lint-staged # 在package.json中定义prepare脚本 # prepare: husky install执行npm install时prepare脚本会自动运行并在项目内生成.husky目录。然后添加pre-commit钩子npx husky add .husky/pre-commit npx lint-stagedlint-staged的配置写在package.json中{ lint-staged: { *.{js,vue}: [eslint --fix, prettier --write], *.{css,scss}: [prettier --write] } }这样每次提交只会对暂存区里变化的文件做检查修复不会把整个项目的代码全部检查一遍速度很快。eslint --fix能自动修复的问题比如分号、引号会直接改掉不能自动修复的会抛出错误终止提交逼开发者手动处理。6.3 commitlint统一提交信息规范提交信息一乱后续回滚、生成变更日志都会很难受。建议再装commitlint/cli和commitlint/config-conventional并用husky的commit-msg钩子校验信息格式npx husky add .husky/commit-msg npx commitlint --edit $1在根目录添加commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional] };支持的信息格式是type(scope?): subject比如feat(login): 增加扫码登录功能。常用的type包括feat、fix、docs、style、refactor、perf、test、chore。这样提交历史就从散文变成了有结构的日志后续出CHANGELOG.md或者按功能回溯提交都很方便。6.4 把核心配置沉淀成团队脚手架到这里你会发现一个稳定的Vue2项目骨架真正花心思的其实不是vue create那一步而是后续这一整套配套配置。如果团队经常要开新项目建议把这些配置抽到一个基础仓库或者内部脚手架工具里。我的做法是维护一个vue2-base-template私有仓库里面已经包含了所有依赖、配置、目录结构、ESLint规则、Husky钩子、环境变量样本。新项目直接基于它复制然后改改项目名和描述一天的初始化工作压缩到10分钟之内。这个模板仓库需要注意一点不要频繁改动。每次改动都要走一次完整的创建-构建-提交流程验证然后打tag发版本。团队成员既可以直接用最新模板也可以基于特定tag生成项目保证可控。7. 最后分享几个真实的兜底经验写到这里基础的Vue2项目创建流程算是走完了但我还想再补几个实战中容易踩到、且一般教程不会写的点。第一个是关于Vue2.7的。如果你在创建项目时选了Vue2.7.x它已经内置了composition-api的部分能力但又没完全移植跟Vue3的写法有些差异。团队写代码时最好明确到底是走Options API还是Composition API。在Vue2.7里混用两种风格虽然技术上允许但review和后期维护会很痛苦。我的标准是老项目继续用Options API新页面如果追求代码组织可以用script setup但要靠lint规则统一约束不要随手写。第二个是关于package.json里的engines字段。建议显式声明团队认可的Node版本范围{ engines: { node: 16 19 } }这样在错误版本的Node下跑install时npm会有明确提示而不是等到编译时才报一堆看不懂的错误。配合volta或nvm的.nvmrc文件成员切换目录时能自动切到合适版本我强烈建议团队这么做。第三个是关于首次提交。项目创建好、依赖装好、几个基础页面能跑通之后第一件事就是做一次干净的git提交。不用提交大而全但package-lock.json、.editorconfig、.husky这些基础设施一定要在第一次提交里就进去。很多东西拖到后面文件名、目录结构一变动对比工作量会成倍增加。最后一个经验有些反直觉Vue2项目创建完毕之后不要着急把依赖全部升级到最新。Vue2生态已经稳定很多包的最新版本反而不一定兼容老配置。我之前遇到过把某个工具库从^1.2.0升到^1.5.0后ESLint规则、构建流程直接崩掉的情况最后回滚版本才恢复。Vue2项目的原则是能不动就不动升级之前一定要先看changelog和peerDependencies变化同时在分支上先验证一遍npm run build再合入主分支。这在多人协作的长期项目里是避免半夜接到线上挂了电话的最好保障。 说实话vue2创建项目看起来是个特别入门的话题但我带过的小组里几乎每一个新人都在这件事上栽过跟头。不是vue create跑不起来而是跑起来之后发现各种版本冲突、依赖报错、目录混乱、联调环境配不明白——等到项目真正跑顺一天就过去了。这篇文章我想把这套流程从头到尾捋一遍结合我这些年实际创建Vue2项目的经验把我踩过的坑、验证过的方案、以及最终稳定可复用的配置方式都写出来。无论你是刚接触Vue2的新手还是准备给团队搭一个规范项目基座的开发者这篇内容应该能帮你少走很多弯路。1. 动手之前先想清楚脚手架选型很多教程上来就是一句运行npm install -g vue/cli然后vue create项目名但真正落到企业项目里选型这一步才是决定后面顺不顺利的关键。我先说结论Vue2项目长期维护、需要稳定生态的优先选Vue CLI 5追求极致启动速度的可以考虑Vite 兼容插件的方式纯手动搭建Webpack不是不行但我个人不推荐除非你有充分的定制需求。1.1 三种方式的取舍逻辑先看官方脚手架。Vue CLI从4.x升级到5.x之后底层Webpack升级到了5对现代Node版本的支持也好了很多。Vue2项目的标准姿势现在普遍是Vue CLI 5.0.8 Vue 2.7.x这是最被广泛验证过、遇到问题社区资料最多的组合。你用Vue CLI创建项目时默认会安装Vue 3.x模板但可以在交互选项里手动选择Vue 2版本也可以通过指定preset来快速生成后面我会详细说。Vite方案在Vue3时代是主流但在Vue2场景下需要靠官方插件vitejs/plugin-vue2来支持SFC编译。它的优点是开发服务器冷启动快、热更新快这在大型项目里的体感差异非常明显缺点则是生态成熟度不如Vue CLI部分Vue2生态里的老库尤其是那些需要特殊Webpack处理的可能没法直接用。我的态度是如果是全新的、知道自己在做什么的Vue2项目Vite可以尝试如果是维护老项目或者团队普遍熟悉Vue CLI那还是选Vue CLI省心。手动搭建Webpack Vue2的方案理论上可以做到完全定制但你要自己去配置vue-loader、vue-template-compiler、CSS处理、HMR等一系列东西。我自己只在做一个需要深度定制构建流程的组件库时用过这种方式普通业务项目完全没必要。1.2 版本兼容性检查表这里直接给出一份我实测过的版本搭配方案按推荐程度排序场景推荐Node版本脚手架/构建工具备注标准Vue2项目长期维护16.20.x 或 18.19.xVue CLI 5.0.8最稳资料最多Vue2老项目升级现有CLI14.x 或 16.xVue CLI 4.5.x老项目慎上Node 20追求开发体验的新项目18.xVite 4 vitejs/plugin-vue2冷启动快但要注意兼容性Node 20.x Vue220.xVue CLI 5.0.8可用但node-sass等老依赖会报错踩过的坑必须提一句千万别在Vue2项目里用node-sass除非你确认Node版本和它编译的二进制文件完全匹配。我自己后来全部换成了sass也就是Dart Sass配合Vue CLI 5完全没问题。你在创建项目选择CSS预处理器时也尽量选sass而不是node-sassVue CLI 5里选项名已经不怎么区分了但安装依赖时要注意看装的是哪个。1.3 为什么企业项目普遍锁死Vue2很多人会问新项目为什么不用Vue3这里不讨论技术优劣只说现实因素很多现存业务系统的依赖库、组件库、内部脚手架都是基于Vue2写的升级到Vue3意味着整套基础设施要重新适配成本极高。这种情况下创建Vue2项目并不是从零开始而是要在一堆老链路里插入一个新的子应用或者重构入口。所以你会看到即使社区都在推Vue3Vue2项目在企业里依然大量存在。2. vue create初始化过程中的选项决策确定用Vue CLI之后就进入实际创建流程了。先确保你已经安装了Vue CLI# 全局安装或升级到指定版本 npm install -g vue/cli5.0.8 # 查看版本验证安装成功 vue --version如果之前装过Vue CLI 3或4最好先卸载再安装5避免命令版本混乱。卸载命令是npm uninstall -g vue/cli。另外如果你的日常Node版本是20比如你要同时维护Vue3项目我建议用nvm或fnm这类Node版本管理工具在Vue2项目目录下切到Node 16。后面所有命令都在Node 16环境下跑。2.1 交互模式还是预设模式直接运行vue create my-vue2-project会进入交互式选择。这里逐个说一下我推荐的选项第一步选择预设建议选Manually select features不要用默认的Default ([Vue 3] babel, eslint)因为默认预设是Vue3。手动勾选时我一般这样选Babel必选编译ES6语法TypeScript如果项目需要就选不需要就别选Vue2 TS需要额外的vue-class-component配置复杂度会上去Router和Vuex根据实际需要选。这里有个版本陷阱Vue2项目必须用vue-router3和vuex3Vue CLI会自动装对应版本但你如果手动作业很容易装成vue-router4或vuex4这在Vue2里直接跑不起来CSS Pre-processors我选Dart SassLinter / Formatter推荐选ESLint Prettier这是当前最普及的组合Unit Testing / E2E Testing根据需求选不需要就不勾避免初始化时装一堆用不上的东西。选完特性之后还会问你要不要把这些选择存成preset方便下次复用。团队协作场景我强烈建议存一下并且把preset文件提交到代码仓库后续新成员创建项目时直接选相同的preset能保证所有子应用的基础配置完全一致。2.2 使用preset命令行创建如果你已经存了preset或者想通过命令直接指定Vue版本可以用这种方式vue create my-vue2-project -p my-preset-name如果不想提前存preset也可以这样先创建一个带预设的配置文件比如vue.config.js实际上preset可以放在项目根目录的preset.json里然后通过--preset参数指定vue create my-vue2-project --preset ./preset.jsonpreset.json的内容大致长这样{ useConfigFiles: true, cssPreprocessor: dart-sass, plugins: { vue/cli-plugin-babel: {}, vue/cli-plugin-eslint: { config: prettier, lintOn: [save, commit] }, vue/cli-plugin-router: { historyMode: true }, vue/cli-plugin-vuex: {} }, vueVersion: 2 }这样创建的my-vue2-project直接就是Vue2版本不用再进去改。这里注意useConfigFiles设为true代表把Babel、ESLint配置都放在独立配置文件中而不是塞进package.json我个人更喜欢独立文件方式团队里review配置改动时更清晰。2.3 初始化完成后的第一轮目录检查项目创建成功后最好先别急着写代码先敲一遍这些命令cd my-vue2-project npm install npm run serve浏览器打开localhost:8080看到Vue2欢迎页说明基础链路通了。如果这一步出错大多是Node版本问题或npm源问题。npm源我建议先检查一下npm config get registry # 如果输出不是官方源或企业内网源建议设置一下 npm config set registry https://registry.npmmirror.com国内网络环境用镜像源能快非常多。但有一点要提醒镜像源和官方源切换可能会导致锁文件变化团队协作时最好统一配置源并把package-lock.json提交到仓库避免每个人本地装出来的依赖树不一样。3. npm install阶段最常见的两座大山初始化完成并不代表万事大吉。你在npm install时碰到的报错90%以上可以归成两类ERESOLVE依赖树冲突以及peerDependencies没有被正确安装导致运行时报找不到模块。3.1 ERESOLVE野生错误与它背后的依赖树逻辑npm 7之后对依赖冲突的检测严格了很多老项目经常出现这种报错npm ERR! ERESOLVE unable to resolve dependency tree npm ERR! While resolving: project-name0.1.0什么意思呢简单说就是两个包之间对某个第三方库的版本要求不一致。比如A包要求webpack^5.0B包要求webpack^4.0npm按照最严格规则无法自动调和就会整体拒绝安装。这在Vue2老项目里尤其常见因为很多老依赖的peerDependencies范围写得比较窄。解决办法有两个层级第一层看能不能升级或降级其中一个依赖让它们的版本范围交叠。这是最健康的解法但需要时间排查。第二层如果你确认冲突的包之间实际兼容可以使用--legacy-peer-deps或--force来绕过npm install --legacy-peer-deps这个参数被问得最多我对它的态度是能用但要用得明白。它本质上是让npm退回到npm 6的依赖解析逻辑忽略部分peer依赖冲突。但这不代表冲突不存在后续如果依赖间真的不兼容运行时才会暴露。所以我只在排查后确认冲突无关紧要时才会这么做并且会在项目的README里记录这个命令以及为什么需要它。其实更省心的做法是在项目的.npmrc里加上legacy-peer-depstrue这样团队成员执行npm install时就不用手动加参数了行为完全一致。3.2 cnpm引发的半残node_modules我有个同事在某公司用cnpm装依赖装完后npm run serve能跑起来但一执行ESLint就直接报Cannot find module eslint-config-standard查了一圈发现node_modules里根本没这个包。这就是cnpm早期版本的经典问题它对peerDependencies的处理逻辑跟npm并不完全一致经常导致部分peer依赖缺失。我个人的经验是Vue2项目经过多年沉淀依赖树本来就非常复杂peerDependencies、optionalDependencies、各种deprecated的包混在一起用非npm官方工具安装风险真的不小。如果你不是对cnpm的依赖处理机制有十足把握建议一律用npm网络慢就换镜像源不要图方便直接上cnpm。实在要用也得用最新版cnpm并且装完后跑一遍npm ls --depth0检查顶层依赖有没有缺失。3.3 锁文件与CI环境安装架构稳定的Vue2项目本地和CI用的安装命令最好统一本地npm install它会在已有package.json和package-lock.json基础上增量安装速度快CI环境npm ci它严格按照锁文件全新安装不会做任何增量解析能保证构建环境可复现。如果本地和CI之间存在依赖树不一致优先检查是否有一方用了--force或者--legacy-peer-deps。这个细节影响非常深远——很多本地能跑、CI挂了的诡异问题最后都查到了依赖树不一致上。4. 统一IDE与项目目录结构规划Vue CLI只负责生成骨架真正让项目变得像企业级的是IDE配置、目录结构和命名约定。很多项目创建完就开写业务结果代码量上来之后光找文件就很费劲。4.1 Vue2项目的IDE插件选择VS Code是事实标准但Vue2和Vue3的插件选择有个大坑Vue3项目主流是VolarVue Language FeaturesVue2项目老牌插件是Vetur。在Vue2项目里装上Volar而不做任何配置有概率出现模板类型检查不一致的问题。团队协作时更要统一要么全都用Vetur要么统一用Volar并开启其针对Vue2的支持模式。我建议Vue2项目直接用Vetur最省心。另外ESLint、Prettier、EditorConfig for VS Code这三个插件也是必须统一装的。配合项目根目录的.editorconfig文件能保证不同操作系统、不同编辑器下代码格式一致root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true.editorconfig的优先级其实高于编辑器自身设置只要团队成员都装了对应的IDE插件格式基本不会乱。再加上ESLint和Prettier配置等于做了双保险。4.2 src目录怎么划分才不容易乱这是我个人一直在用的Vue2项目目录结构不算权威但经过多个项目验证后足够清晰src/ ├── api/ # 接口请求 │ ├── modules/ # 按业务模块拆分 │ └── request.js # axios实例封装 ├── assets/ # 静态资源图片、全局样式 ├── components/ # 公共组件 │ ├── base/ # 纯展示型基础组件 │ └── business/ # 业务型复合组件 ├── directives/ # 自定义指令 ├── filters/ # 全局过滤器Vue3里已移除的概念Vue2仍常用 ├── mixins/ # 混入逻辑 ├── router/ # 路由配置 ├── store/ # Vuex状态管理 │ ├── modules/ # 按业务模块拆分 │ └── index.js ├── styles/ # 全局样式变量与公共样式 ├── utils/ # 纯工具函数 ├── views/ # 页面级组件 ├── App.vue └── main.js这个结构最重要的原则是把容易变化的模块拆分出去。比如接口请求单独放api/页面就不会直接依赖具体的url状态管理拆模块就不会在store/index.js里堆几千行。组件分base和business是为了让基础组件可以无脑复用而业务组件知道从哪个store取数据、调哪个接口。4.3 别名配置让import路径不再地狱组件层级深了之后相对路径../../../components/...非常容易写错。Vue CLI项目可以在根目录jsconfig.json里配置路径别名让编辑器和构建器都认{ compilerOptions: { baseUrl: ., paths: { /*: [src/*], api/*: [src/api/*], components/*: [src/components/*] } }, exclude: [node_modules, dist] }Vue CLI内部已经默认支持指向src但如果团队习惯用更多语义化别名就在这个文件里定义。注意配置完需要重启VS Code才能生效。这个文件不是webpack配置它只是给编辑器做智能提示用的真正让Webpack认识这些别名需要确认vue.config.js或者内部默认配置里有对应的resolve配置。好消息是Vue CLI 5内置了别名其余自定义别名需要在vue.config.js中配置chainWebpack才能让Webpack也识别。两者一定要保持一致。5. 环境变量与代理配置开发联调顺畅的关键Vue2项目创建好之后马上会面临一个问题前端怎么对接后端接口开发环境调测试环境构建之后走生产环境域名这个过程没配置好不但联调效率低还会出线上事故。5.1 环境变量文件怎么写Vue CLI约定根目录下的.env文件用来存环境变量文件名后缀代表不同环境.env.development对应开发环境.env.production对应生产构建。变量名必须以VUE_APP_开头才会被注入到客户端代码中# .env.development VUE_APP_BASE_API/api VUE_APP_ENVdevelopment # .env.production VUE_APP_BASE_API/prod-api VUE_APP_ENVproduction代码里可以通过process.env.VUE_APP_BASE_API拿到对应值。这个机制的底层逻辑是Vue CLI会把VUE_APP_开头的变量在编译阶段直接替换进代码里而不是运行时读取所以不要在代码里动态拼接process.env变量名。5.2 devServer代理跨域问题的正解前后端联调最常见的跨域问题实际上不需要后端开CORS也不需要前端装代理插件直接利用Vue CLI的devServer代理就能解决// vue.config.js module.exports { devServer: { port: 8080, proxy: { /api: { target: http://192.168.1.100:3000, changeOrigin: true, pathRewrite: { ^/api: } } } } }这样你在前端代码里请求/api/user/list的时候devServer会把请求转发到http://192.168.1.100:3000/user/list。changeOrigin: true很关键它会把请求头里的Host字段改成目标域名很多后端服务会校验这个字段不改容易收到403。pathRewrite要不要写取决于后端接口路径里是否带/api前缀。如果后端接口本身就是/api/user/list那就不需要重写如果后端接口是/user/list才需要把前缀剥离。这个对应关系一定要跟后端确认清楚我见过因为前缀没对齐而排查了一整天的情况。5.3 记住两个环境三份文件的思维实际项目里我习惯至少维护三份环境文件.env全局基础配置所有环境都生效.env.development开发环境专属.env.production生产构建专属。如果有测试环境、预发布环境可以再加.env.staging、.env.test并用--mode参数来指定构建模式npm run build -- --mode staging这个mode可以直接通过process.env.NODE_ENV或自定义变量来区分。环境变量文件的命名和运行模式是一一对应的如果文件名带点比如.env.local要注意它是否会被git跟踪.env.local这种通常应该写进.gitignore因为它往往包含本地敏感配置。6. 代码规范与提交规范创建项目时就要架好防线只把项目跑通不算完成一个能长期维护的Vue2项目必须在初始化阶段就搭好代码规范和提交规范。这一步做不做直接决定项目3个月之后是整洁还是灾难。6.1 ESLint Prettier的联动配置Vue CLI在初始化时如果勾选了Linter会自动生成eslintrc相关配置。我推荐选择ESLint Prettier预设。这两个工具的分工要搞清楚ESLint管代码质量未使用变量、未定义变量、禁止console提交等Prettier管代码格式缩进、引号、分号、换行。它们在个别规则上有重叠所以需要用eslint-config-prettier把两者可能冲突的规则关掉再用eslint-plugin-prettier把Prettier作为ESLint的一条规则运行。Vue CLI5预设里已经处理好了这些联动你只需要注意团队里别有人单独改.prettierrc导致格式失配。lintOnSave建议保持默认的true这样npm run serve时ESLint会在保存时给出提示。再配合.prettierrc里统一的双引号、分号、每行最大宽度等配置全团队的代码风格就能收敛。6.2 Husky与lint-staged实现提交前自动检查光有ESLint还不够因为新人完全不看编辑器警告直接提交的情况时有发生。拦截线下移放在git commit这个动作上才是可靠的防线。现在的husky10.x及以上用法跟老版本不同初始化命令是npm install -D husky lint-staged # 在package.json中定义prepare脚本 # prepare: husky install执行npm install时prepare脚本会自动运行并在项目内生成.husky目录。然后添加pre-commit钩子npx husky add .husky/pre-commit npx lint-stagedlint-staged的配置写在package.json中{ lint-staged: { *.{js,vue}: [eslint --fix, prettier --write], *.{css,scss}: [prettier --write] } }这样每次提交只会对暂存区里变化的文件做检查修复不会把整个项目的代码全部检查一遍速度很快。eslint --fix能自动修复的问题比如分号、引号会直接改掉不能自动修复的会抛出错误终止提交逼开发者手动处理。6.3 commitlint统一提交信息规范提交信息一乱后续回滚、生成变更日志都会很难受。建议再装commitlint/cli和commitlint/config-conventional并用husky的commit-msg钩子校验信息格式npx husky add .husky/commit-msg npx commitlint --edit $1在根目录添加commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional] };支持的信息格式是type(scope?): subject比如feat(login): 增加扫码登录功能。常用的type包括feat、fix、docs、style、refactor、perf、test、chore。这样提交历史就从散文变成了有结构的日志后续出CHANGELOG.md或者按功能回溯提交都很方便。6.4 把核心配置沉淀成团队脚手架到这里你会发现一个稳定的Vue2项目骨架真正花心思的其实不是vue create那一步而是后续这一整套配套配置。如果团队经常要开新项目建议把这些配置抽到一个基础仓库或者内部脚手架工具里。我的做法是维护一个vue2-base-template私有仓库里面已经包含了所有依赖、配置、目录结构、ESLint规则、Husky钩子、环境变量样本。新项目直接基于它复制然后改改项目名和描述一天的初始化工作压缩到10分钟之内。这个模板仓库需要注意一点不要频繁改动。每次改动都要走一次完整的创建-构建-提交流程验证然后打tag发版本。团队成员既可以直接用最新模板也可以基于特定tag生成项目保证可控。7. 最后分享几个真实的兜底经验写到这里基础的Vue2项目创建流程算是走完了但我还想再补几个实战中容易踩到、且一般教程不会写的点。第一个是关于Vue2.7的。如果你在创建项目时选了Vue2.7.x它已经内置了composition-api的部分能力但又没完全移植跟Vue3的写法有些差异。团队写代码时最好明确到底是走Options API还是Composition API。在Vue2.7里混用两种风格虽然技术上允许但review和后期维护会很痛苦。我的标准是老项目继续用Options API新页面如果追求代码组织可以用script setup但要靠lint规则统一约束不要随手写。第二个是关于package.json里的engines字段。建议显式声明团队认可的Node版本范围{ engines: { node: 16 19 } }这样在错误版本的Node下跑install时npm会有明确提示而不是等到编译时才报一堆看不懂的错误。配合volta或nvm的.nvmrc文件成员切换目录时能自动切到合适版本我强烈建议团队这么做。第三个是关于首次提交。项目创建好、依赖装好、几个基础页面能跑通之后第一件事就是做一次干净的git提交。不用提交大而全但package-lock.json、.editorconfig、.husky这些基础设施一定要在第一次提交里就进去。很多东西拖到后面文件名、目录结构一变动对比工作量会成倍增加。最后一个经验有些反直觉Vue2项目创建完毕之后不要着急把依赖全部升级到最新。Vue2生态已经稳定很多包的最新版本反而不一定兼容老配置。我之前遇到过把某个工具库从^1.2.0升到^1.5.0后ESLint规则、构建流程直接崩掉的情况最后回滚版本才恢复。Vue2项目的原则是能不动就不动升级之前一定要先看changelog和peerDependencies变化同时在分支上先验证一遍npm run build再合入主分支。这在多人协作的长期项目里是避免半夜接到线上挂了电话的最好保障。