1. 为什么 config 目录值得单独拎出来讲很多人做 Vue 项目src目录翻得滚瓜烂熟组件、路由、状态管理写得飞起但一提到根目录下的config文件夹就有点含糊——不就是放配置的地方吗 真到要改构建行为、配代理、调环境变量的时候才发现这里面的门道比想象中多。config目录是 Vue 项目尤其是基于 Vue CLI 脚手架生成的项目里专门用来存放构建配置和环境配置的地方它决定了项目怎么编译、怎么打包、开发服务器怎么跑、不同环境加载哪些参数。说白了src管的是页面长什么样config管的是项目怎么跑起来、怎么发出去。这篇文章面向的是已经能跑通一个 Vue 项目、但对构建层配置还停留在照着改不敢动阶段的开发者。我会把config目录里每个文件的职责、关键字段的含义、常见改法背后的逻辑以及我自己踩过的坑一条条拆开讲。读完你至少能做到三件事知道每个配置文件该改哪里、明白为什么这么改、遇到构建报错时知道往哪个方向排查。文章里涉及的具体参数值我会给出基于常见实践的推荐配置你可以直接抄但更重要的是理解它为什么这么设。需要先说明一点Vue 项目的构建配置体系经历过几轮变化。早期 Vue CLI 2.x 时代配置分散在config/和build/两个目录里到了 Vue CLI 3.x 之后官方把 webpack 配置全部收敛进vue.config.jsconfig目录的形态发生了变化。所以下面我会分情况讲避免你拿着老教程在新项目里对不上号。2. config 目录的整体设计与思路拆解2.1 配置分离的核心思想环境与构建解耦要理解config目录为什么这么设计得先抓住一个核心思想把会随环境变化的东西和不会随环境变化的东西分开。一个 Vue 项目从开发到上线至少要经历本地开发、测试、预发、生产这几套环境每套环境的接口地址、资源路径、是否压缩、是否生成 source map 都不一样。如果把这些全写死在代码里每次切换环境都要手动改代码出错概率极高。config目录的设计就是来解决这个问题的。它把环境相关的参数抽出来通过一套命名约定和加载机制让构建工具在打包时自动读取对应环境的配置。这样开发者只需要维护几份配置文件切换环境时改一个变量或者跑一条命令就行。这个思路和很多后端框架的application-dev.yml、application-prod.yml是一脉相承的只不过前端这边是通过构建工具在编译期注入。我见过不少团队图省事把所有配置塞进一个文件用if (process.env.NODE_ENV production)到处判断。项目小的时候还行一旦环境多了、配置项多了这个文件会变成谁都不敢碰的祖传代码。所以配置分离不是过度设计而是给未来的自己留条活路。2.2 不同 Vue 版本下 config 目录的形态差异这里必须把版本差异讲清楚否则你搜到的资料很可能对不上你的项目。在Vue CLI 2.x时代脚手架生成的项目根目录下确实有一个独立的config文件夹里面通常包含三个文件index.js、dev.env.js、prod.env.js。index.js是主配置按dev和prod两个 key 组织分别描述开发和生产环境的构建参数dev.env.js和prod.env.js则负责定义注入到代码里的环境变量。这套结构清晰直观改起来也方便。到了Vue CLI 3.x 及以后官方做了大幅简化config和build目录被合并大部分配置项有了默认值需要自定义的部分统一写进根目录的vue.config.js。这时候严格意义上的config目录可能不再存在但配置这件事本身没消失只是换了个地方。很多团队为了保持结构清晰仍然会自己建一个config目录用来存放环境变量文件、代理配置、多环境参数等再在vue.config.js里引用。所以当你看到config 目录这个词先确认自己项目用的是哪套脚手架。下面我讲具体文件时会同时覆盖这两种情况你按自己的版本对号入座。2.3 配置文件的加载顺序与优先级配置这东西最怕的就是到底哪个生效了。Vue 项目的配置加载有一套明确的优先级规则理解它能帮你快速定位我改了怎么没反应的问题。以 Vue CLI 3 为例配置来源大致有这么几层优先级从低到高脚手架内置默认值 →vue.config.js中的配置 → 命令行参数 → 环境变量文件.env系列。也就是说命令行里传的参数会覆盖配置文件里的值而.env文件里的变量又会通过process.env注入到代码和配置中。在 Vue CLI 2.x 的config/index.js里则是通过process.env.NODE_ENV来判断当前是开发还是生产然后选择对应的配置块。这个判断发生在构建启动的那一刻所以你在运行时改NODE_ENV是没用的必须在启动命令里指定。提示排查配置不生效的问题时第一件事是确认当前构建到底加载了哪份配置。可以在vue.config.js里打印process.env.NODE_ENV和关键变量一眼就能看出问题。3. 核心文件逐个拆解与实操要点3.1 config/index.js构建行为的总控台在 Vue CLI 2.x 项目里config/index.js是整个构建配置的中枢。它导出一个对象通常包含dev和build两个大块分别对应开发和生产构建。我挑几个最常改、也最容易改错的字段来讲。dev块里最关键的是devServer相关配置。host决定开发服务器监听哪个地址默认localhost如果你想让同一局域网内的手机或其他设备访问需要改成0.0.0.0。port是端口号默认 8080被占用时构建工具会自动换端口但如果你有固定的联调需求最好手动指定一个不冲突的端口。proxyTable是代理配置用来解决开发时的跨域问题这个后面单独讲。build块里最重要的是assetsPublicPath。它决定打包后静态资源的引用路径。默认是/适合部署在域名根目录如果你的项目要部署在子路径下比如https://example.com/myapp/就必须改成/myapp/否则所有 JS、CSS 都会 404。这个坑我踩过不止一次页面白屏、控制台一堆资源加载失败八成就是它没配对。productionSourceMap也值得说一句。它控制生产构建是否生成 source map。开启后方便线上调试但会显著增大打包体积而且会把源码暴露出去。我的建议是内部系统可以开对外产品关掉需要排查线上问题时临时开一次重新构建。// config/index.js 片段示例Vue CLI 2.x 风格 module.exports { dev: { host: 0.0.0.0, port: 8080, assetsPublicPath: /, proxyTable: {} }, build: { index: path.resolve(__dirname, ../dist/index.html), assetsRoot: path.resolve(__dirname, ../dist), assetsPublicPath: /, productionSourceMap: false } }3.2 dev.env.js 与 prod.env.js环境变量的注入源头这两个文件的作用是定义注入到代码里的环境变量。它们的写法通常是这样的// config/prod.env.js module.exports { NODE_ENV: production, API_BASE_URL: https://api.example.com }注意这里的值为什么要用两层引号。因为最终这些值会被 webpack 的 DefinePlugin 以字符串替换的方式注入到代码里production替换后代码里就是production这个字符串字面量。如果你只写production替换后代码里就变成了production这个变量名直接报未定义错误。这个细节新手极容易搞错我第一次配的时候就被它坑了半天。环境变量的命名有个约定俗成的规矩只放构建期就需要确定的值比如接口基础地址、埋点开关、版本号。不要把运行期才该决定的东西塞进来因为一旦注入它在打包那一刻就固定了运行时改不了。3.3 .env 系列文件Vue CLI 3 的新玩法Vue CLI 3 引入了.env文件体系比老版本的 env.js 更灵活。常见的文件有.env、.env.development、.env.production、.env.local等。加载规则是.env所有环境都加载.env.[mode]只在对应模式下加载.env.local会被 git 忽略、用于本地个人配置。这里有个关键点只有以VUE_APP_开头的变量才会被注入到客户端代码里。这是官方为了防止误把敏感变量比如某些密钥打进前端包而设的保护机制。所以你在.env.production里写API_URLxxx是拿不到的必须写成VUE_APP_API_URLxxx。# .env.production VUE_APP_API_BASE_URLhttps://api.example.com VUE_APP_BUILD_VERSION1.2.0在代码里通过process.env.VUE_APP_API_BASE_URL访问。构建时这些值会被静态替换所以不能用在需要动态计算的场景。注意.env.local一定要加进.gitignore。我见过有人把本地调试用的接口地址提交上去结果整个团队的构建都指向了错误的地址排查了半天才发现是这文件惹的祸。3.4 代理配置开发环境跨域的正解开发时前端跑在localhost:8080后端接口在另一个域名或端口浏览器同源策略会拦下请求。这时候代理配置就派上用场了。它的原理是开发服务器收到匹配规则的请求后代替浏览器去请求真实接口再把结果返回给前端。因为服务器之间通信不受同源策略限制跨域问题就绕过去了。在 Vue CLI 2.x 里代理写在config/index.js的dev.proxyTable在 Vue CLI 3 里写在vue.config.js的devServer.proxy。写法基本一致// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://backend.example.com, changeOrigin: true, pathRewrite: { ^/api: } } } } }target是真实接口地址changeOrigin: true让请求头里的 host 变成目标地址某些后端会校验这个pathRewrite用来去掉路径前缀。比如前端请求/api/user实际会转发到http://backend.example.com/user。这里有个容易忽略的点代理只在开发环境生效生产环境是打包后的静态文件直接请求真实接口所以生产环境的跨域要靠后端配置 CORS 或者用同域部署来解决。别指望代理能带到线上去。4. 实操过程与核心环节实现4.1 从零配置一套多环境方案假设你接手一个项目需要支持开发、测试、生产三套环境接口地址各不相同。我按 Vue CLI 3 的思路走一遍完整流程。第一步在项目根目录建config目录虽然官方不强制但集中管理更清晰里面放三个文件.env.development、.env.test、.env.production。内容分别写好各自的VUE_APP_API_BASE_URL。第二步在package.json的 scripts 里配置不同模式的启动命令{ scripts: { serve: vue-cli-service serve, build:test: vue-cli-service build --mode test, build:prod: vue-cli-service build --mode production } }--mode test会让构建工具去加载.env.test文件。注意 mode 的名字要和文件名后缀对应上写错了就加载不到。第三步在代码里统一封装一个读取环境变量的模块避免到处写process.env.xxx// src/config/env.js const config { development: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL }, test: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL }, production: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL } } export default config[process.env.NODE_ENV] || config.development这样业务代码只依赖这个模块切换环境时不用改任何业务逻辑。4.2 参数计算assetsPublicPath 到底该怎么填assetsPublicPath这个参数很多人是试出来的其实它有明确的计算逻辑。它本质上是告诉浏览器打包后的 JS、CSS、图片这些资源应该从哪个基础路径去加载。假设你的项目部署在https://example.com/apps/shop/这个路径下那么assetsPublicPath就应该填/apps/shop/。构建后index.html里引用资源会变成script src/apps/shop/js/app.xxx.js浏览器就能正确找到。如果填错了会怎样填成/浏览器会去https://example.com/js/app.xxx.js找而实际文件在/apps/shop/js/下结果就是 404页面白屏。填成相对路径./在某些场景下也能用但一旦页面路由是多层嵌套的相对路径的基准就变了容易出问题。所以我的经验是能用绝对路径就用绝对路径把部署路径算清楚再填。还有一种情况是用 CDN 加速静态资源。这时候assetsPublicPath要填 CDN 的域名比如https://cdn.example.com/apps/shop/。但要注意index.html本身通常还是放在自己的服务器上只有 JS、CSS、图片走 CDN这个区分要在构建配置里处理好。4.3 构建产物分析与体积优化配置改完之后怎么知道效果好不好答案是看构建产物。Vue CLI 内置了--report参数跑vue-cli-service build --report会生成一个report.html用浏览器打开就能看到每个模块的体积占比。我一般会重点关注三类东西一是体积特别大的第三方库比如某些图表库、编辑器库看看能不能按需引入或者换更轻量的方案二是重复打包的依赖同一个库被多个 chunk 引入可以通过splitChunks配置抽出来三是自己写的业务代码里有没有误引入整个库的情况比如import _ from lodash就会把整个 lodash 打进去改成import debounce from lodash/debounce能省不少体积。在vue.config.js里可以通过configureWebpack或chainWebpack来调整 webpack 配置。比如配置externals把某些大库排除出打包改用 CDN 引入// vue.config.js module.exports { configureWebpack: { externals: { vue: Vue, element-ui: ELEMENT } } }这样打包时就不会把 vue 和 element-ui 打进去而是在index.html里通过 script 标签引入。代价是增加了对外部 CDN 的依赖需要权衡。5. 常见问题与排查技巧实录5.1 配置改了不生效的排查思路这是最高频的问题。我的排查顺序是这样的先确认改的文件是不是当前构建真正加载的那个。比如你改了.env.production但跑的是npm run serve开发模式那当然不生效。可以在配置文件里加一行console.log看构建时有没有打印出来。其次确认变量名有没有写对。.env文件里的变量必须以VUE_APP_开头config/index.js里的字段名要和代码里引用的完全一致大小写都不能错。我遇到过把assetsPublicPath写成assetPublicPath的构建不报错但资源路径就是不对查了半天。最后确认有没有缓存干扰。构建工具的缓存有时候会记住旧配置删掉node_modules/.cache目录再重新构建往往能解决一些莫名其妙的问题。5.2 环境变量注入失败的典型原因环境变量拿不到通常逃不出这几种情况。一是变量名没加VUE_APP_前缀这个前面说过。二是.env文件放错了位置必须在项目根目录和package.json同级。三是 mode 名字和文件名对不上--mode staging就得有.env.staging。四是值里带了特殊字符没转义比如地址里有#或空格需要用引号包起来。还有一种隐蔽的情况变量在构建时被静态替换如果你在代码里用动态拼接的方式访问比如process.env[VUE_APP_ key]是拿不到值的因为构建工具只做字面量替换不做运行时求值。这个坑比较深遇到时容易懵。5.3 常见问题速查表问题现象可能原因排查方向页面白屏控制台资源 404assetsPublicPath 配置错误检查部署路径与配置是否一致接口请求跨域代理未配置或生产环境未配 CORS开发查 proxy生产查后端 CORS环境变量为 undefined变量名缺 VUE_APP_ 前缀检查 .env 文件变量命名改了配置没反应加载了错误的配置文件打印 NODE_ENV 确认当前模式打包体积异常大全量引入第三方库用 --report 分析改按需引入构建报错找不到模块路径别名未配置检查 resolve.alias 配置5.4 几个我踩过的坑和独家经验第一个坑是关于pathRewrite的。有次配代理前端请求/api/user后端接口实际是/user我配了pathRewrite: { ^/api: }结果一直 404。后来发现是changeOrigin没开后端根据 host 做了拦截。这两个参数经常要一起调别只顾一个。第二个经验是关于配置文件的注释。config目录里的配置项尤其是那些看起来没用但删了会出问题的一定要写清楚为什么这么配。我接手过一个项目assetsPublicPath被设成了一个奇怪的路径没人知道为什么后来发现是为了兼容某个历史部署环境。如果当时有注释能省下我半天时间。第三个经验是环境变量的安全边界。前端打包后的代码是公开的任何注入到客户端的变量都能被看到。所以 API 密钥、加密盐值这类敏感信息绝对不能放进VUE_APP_变量里。需要保密的逻辑必须放在后端前端只拿必要的公开配置。第四个经验是关于配置的版本管理。.env.local这类个人配置要忽略但.env.development、.env.production这些团队共用的配置必须提交到仓库而且要保证团队成员拿到的是一致的。我见过因为某人本地改了.env.development没提交导致别人拉下来跑不起来的尴尬情况。6. 配置体系的演进与个人实践建议6.1 从 webpack 到 Vite配置思路的迁移现在越来越多的新项目转向 Vite配置体系又变了一轮。Vite 用vite.config.js替代了vue.config.js环境变量依然走.env文件体系但前缀从VUE_APP_变成了VITE_。代理配置从devServer.proxy变成了server.proxy写法大同小异。迁移时最需要注意的是Vite 基于原生 ES 模块开发时不做打包所以一些依赖 webpack 特性的配置比如某些 loader需要换成 Vite 插件。但配置分离、环境变量注入这些核心思想是不变的。理解了config目录背后的设计逻辑换工具时只是换个写法思路是通的。6.2 我个人的配置组织习惯做了这么多项目我现在的习惯是不管用哪套脚手架都在根目录保留一个config目录里面按职责分文件。环境变量放.env系列构建相关的自定义配置放build.config.js代理规则单独放proxy.config.js然后在主配置文件里引用。这样每个文件职责单一改起来不用在一大坨配置里翻找。另外我会在config目录里放一个README.md简单说明每个文件的作用和关键字段的含义。别小看这个习惯团队里新人接手时这份说明能省下大量沟通成本。配置这东西写的时候觉得一目了然过三个月自己都未必记得当初为什么那么配。配置管理说到底是个前人栽树后人乘凉的事。多花十分钟把配置写清楚、注释写明白未来能省下的排查时间可能是十倍百倍。这也是我把config目录单独拎出来讲的原因——它不显眼但它是项目能不能顺利跑起来、能不能稳定发出去的地基。 
长河君 · 2026/10/15 10:44:36 · 阅读 1.2k Vue项目config目录全解析：构建配置与环境变量实战指南
1. 为什么 config 目录值得单独拎出来讲很多人做 Vue 项目src目录翻得滚瓜烂熟组件、路由、状态管理写得飞起但一提到根目录下的config文件夹就有点含糊——不就是放配置的地方吗 真到要改构建行为、配代理、调环境变量的时候才发现这里面的门道比想象中多。config目录是 Vue 项目尤其是基于 Vue CLI 脚手架生成的项目里专门用来存放构建配置和环境配置的地方它决定了项目怎么编译、怎么打包、开发服务器怎么跑、不同环境加载哪些参数。说白了src管的是页面长什么样config管的是项目怎么跑起来、怎么发出去。这篇文章面向的是已经能跑通一个 Vue 项目、但对构建层配置还停留在照着改不敢动阶段的开发者。我会把config目录里每个文件的职责、关键字段的含义、常见改法背后的逻辑以及我自己踩过的坑一条条拆开讲。读完你至少能做到三件事知道每个配置文件该改哪里、明白为什么这么改、遇到构建报错时知道往哪个方向排查。文章里涉及的具体参数值我会给出基于常见实践的推荐配置你可以直接抄但更重要的是理解它为什么这么设。需要先说明一点Vue 项目的构建配置体系经历过几轮变化。早期 Vue CLI 2.x 时代配置分散在config/和build/两个目录里到了 Vue CLI 3.x 之后官方把 webpack 配置全部收敛进vue.config.jsconfig目录的形态发生了变化。所以下面我会分情况讲避免你拿着老教程在新项目里对不上号。2. config 目录的整体设计与思路拆解2.1 配置分离的核心思想环境与构建解耦要理解config目录为什么这么设计得先抓住一个核心思想把会随环境变化的东西和不会随环境变化的东西分开。一个 Vue 项目从开发到上线至少要经历本地开发、测试、预发、生产这几套环境每套环境的接口地址、资源路径、是否压缩、是否生成 source map 都不一样。如果把这些全写死在代码里每次切换环境都要手动改代码出错概率极高。config目录的设计就是来解决这个问题的。它把环境相关的参数抽出来通过一套命名约定和加载机制让构建工具在打包时自动读取对应环境的配置。这样开发者只需要维护几份配置文件切换环境时改一个变量或者跑一条命令就行。这个思路和很多后端框架的application-dev.yml、application-prod.yml是一脉相承的只不过前端这边是通过构建工具在编译期注入。我见过不少团队图省事把所有配置塞进一个文件用if (process.env.NODE_ENV production)到处判断。项目小的时候还行一旦环境多了、配置项多了这个文件会变成谁都不敢碰的祖传代码。所以配置分离不是过度设计而是给未来的自己留条活路。2.2 不同 Vue 版本下 config 目录的形态差异这里必须把版本差异讲清楚否则你搜到的资料很可能对不上你的项目。在Vue CLI 2.x时代脚手架生成的项目根目录下确实有一个独立的config文件夹里面通常包含三个文件index.js、dev.env.js、prod.env.js。index.js是主配置按dev和prod两个 key 组织分别描述开发和生产环境的构建参数dev.env.js和prod.env.js则负责定义注入到代码里的环境变量。这套结构清晰直观改起来也方便。到了Vue CLI 3.x 及以后官方做了大幅简化config和build目录被合并大部分配置项有了默认值需要自定义的部分统一写进根目录的vue.config.js。这时候严格意义上的config目录可能不再存在但配置这件事本身没消失只是换了个地方。很多团队为了保持结构清晰仍然会自己建一个config目录用来存放环境变量文件、代理配置、多环境参数等再在vue.config.js里引用。所以当你看到config 目录这个词先确认自己项目用的是哪套脚手架。下面我讲具体文件时会同时覆盖这两种情况你按自己的版本对号入座。2.3 配置文件的加载顺序与优先级配置这东西最怕的就是到底哪个生效了。Vue 项目的配置加载有一套明确的优先级规则理解它能帮你快速定位我改了怎么没反应的问题。以 Vue CLI 3 为例配置来源大致有这么几层优先级从低到高脚手架内置默认值 →vue.config.js中的配置 → 命令行参数 → 环境变量文件.env系列。也就是说命令行里传的参数会覆盖配置文件里的值而.env文件里的变量又会通过process.env注入到代码和配置中。在 Vue CLI 2.x 的config/index.js里则是通过process.env.NODE_ENV来判断当前是开发还是生产然后选择对应的配置块。这个判断发生在构建启动的那一刻所以你在运行时改NODE_ENV是没用的必须在启动命令里指定。提示排查配置不生效的问题时第一件事是确认当前构建到底加载了哪份配置。可以在vue.config.js里打印process.env.NODE_ENV和关键变量一眼就能看出问题。3. 核心文件逐个拆解与实操要点3.1 config/index.js构建行为的总控台在 Vue CLI 2.x 项目里config/index.js是整个构建配置的中枢。它导出一个对象通常包含dev和build两个大块分别对应开发和生产构建。我挑几个最常改、也最容易改错的字段来讲。dev块里最关键的是devServer相关配置。host决定开发服务器监听哪个地址默认localhost如果你想让同一局域网内的手机或其他设备访问需要改成0.0.0.0。port是端口号默认 8080被占用时构建工具会自动换端口但如果你有固定的联调需求最好手动指定一个不冲突的端口。proxyTable是代理配置用来解决开发时的跨域问题这个后面单独讲。build块里最重要的是assetsPublicPath。它决定打包后静态资源的引用路径。默认是/适合部署在域名根目录如果你的项目要部署在子路径下比如https://example.com/myapp/就必须改成/myapp/否则所有 JS、CSS 都会 404。这个坑我踩过不止一次页面白屏、控制台一堆资源加载失败八成就是它没配对。productionSourceMap也值得说一句。它控制生产构建是否生成 source map。开启后方便线上调试但会显著增大打包体积而且会把源码暴露出去。我的建议是内部系统可以开对外产品关掉需要排查线上问题时临时开一次重新构建。// config/index.js 片段示例Vue CLI 2.x 风格 module.exports { dev: { host: 0.0.0.0, port: 8080, assetsPublicPath: /, proxyTable: {} }, build: { index: path.resolve(__dirname, ../dist/index.html), assetsRoot: path.resolve(__dirname, ../dist), assetsPublicPath: /, productionSourceMap: false } }3.2 dev.env.js 与 prod.env.js环境变量的注入源头这两个文件的作用是定义注入到代码里的环境变量。它们的写法通常是这样的// config/prod.env.js module.exports { NODE_ENV: production, API_BASE_URL: https://api.example.com }注意这里的值为什么要用两层引号。因为最终这些值会被 webpack 的 DefinePlugin 以字符串替换的方式注入到代码里production替换后代码里就是production这个字符串字面量。如果你只写production替换后代码里就变成了production这个变量名直接报未定义错误。这个细节新手极容易搞错我第一次配的时候就被它坑了半天。环境变量的命名有个约定俗成的规矩只放构建期就需要确定的值比如接口基础地址、埋点开关、版本号。不要把运行期才该决定的东西塞进来因为一旦注入它在打包那一刻就固定了运行时改不了。3.3 .env 系列文件Vue CLI 3 的新玩法Vue CLI 3 引入了.env文件体系比老版本的 env.js 更灵活。常见的文件有.env、.env.development、.env.production、.env.local等。加载规则是.env所有环境都加载.env.[mode]只在对应模式下加载.env.local会被 git 忽略、用于本地个人配置。这里有个关键点只有以VUE_APP_开头的变量才会被注入到客户端代码里。这是官方为了防止误把敏感变量比如某些密钥打进前端包而设的保护机制。所以你在.env.production里写API_URLxxx是拿不到的必须写成VUE_APP_API_URLxxx。# .env.production VUE_APP_API_BASE_URLhttps://api.example.com VUE_APP_BUILD_VERSION1.2.0在代码里通过process.env.VUE_APP_API_BASE_URL访问。构建时这些值会被静态替换所以不能用在需要动态计算的场景。注意.env.local一定要加进.gitignore。我见过有人把本地调试用的接口地址提交上去结果整个团队的构建都指向了错误的地址排查了半天才发现是这文件惹的祸。3.4 代理配置开发环境跨域的正解开发时前端跑在localhost:8080后端接口在另一个域名或端口浏览器同源策略会拦下请求。这时候代理配置就派上用场了。它的原理是开发服务器收到匹配规则的请求后代替浏览器去请求真实接口再把结果返回给前端。因为服务器之间通信不受同源策略限制跨域问题就绕过去了。在 Vue CLI 2.x 里代理写在config/index.js的dev.proxyTable在 Vue CLI 3 里写在vue.config.js的devServer.proxy。写法基本一致// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://backend.example.com, changeOrigin: true, pathRewrite: { ^/api: } } } } }target是真实接口地址changeOrigin: true让请求头里的 host 变成目标地址某些后端会校验这个pathRewrite用来去掉路径前缀。比如前端请求/api/user实际会转发到http://backend.example.com/user。这里有个容易忽略的点代理只在开发环境生效生产环境是打包后的静态文件直接请求真实接口所以生产环境的跨域要靠后端配置 CORS 或者用同域部署来解决。别指望代理能带到线上去。4. 实操过程与核心环节实现4.1 从零配置一套多环境方案假设你接手一个项目需要支持开发、测试、生产三套环境接口地址各不相同。我按 Vue CLI 3 的思路走一遍完整流程。第一步在项目根目录建config目录虽然官方不强制但集中管理更清晰里面放三个文件.env.development、.env.test、.env.production。内容分别写好各自的VUE_APP_API_BASE_URL。第二步在package.json的 scripts 里配置不同模式的启动命令{ scripts: { serve: vue-cli-service serve, build:test: vue-cli-service build --mode test, build:prod: vue-cli-service build --mode production } }--mode test会让构建工具去加载.env.test文件。注意 mode 的名字要和文件名后缀对应上写错了就加载不到。第三步在代码里统一封装一个读取环境变量的模块避免到处写process.env.xxx// src/config/env.js const config { development: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL }, test: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL }, production: { apiBaseUrl: process.env.VUE_APP_API_BASE_URL } } export default config[process.env.NODE_ENV] || config.development这样业务代码只依赖这个模块切换环境时不用改任何业务逻辑。4.2 参数计算assetsPublicPath 到底该怎么填assetsPublicPath这个参数很多人是试出来的其实它有明确的计算逻辑。它本质上是告诉浏览器打包后的 JS、CSS、图片这些资源应该从哪个基础路径去加载。假设你的项目部署在https://example.com/apps/shop/这个路径下那么assetsPublicPath就应该填/apps/shop/。构建后index.html里引用资源会变成script src/apps/shop/js/app.xxx.js浏览器就能正确找到。如果填错了会怎样填成/浏览器会去https://example.com/js/app.xxx.js找而实际文件在/apps/shop/js/下结果就是 404页面白屏。填成相对路径./在某些场景下也能用但一旦页面路由是多层嵌套的相对路径的基准就变了容易出问题。所以我的经验是能用绝对路径就用绝对路径把部署路径算清楚再填。还有一种情况是用 CDN 加速静态资源。这时候assetsPublicPath要填 CDN 的域名比如https://cdn.example.com/apps/shop/。但要注意index.html本身通常还是放在自己的服务器上只有 JS、CSS、图片走 CDN这个区分要在构建配置里处理好。4.3 构建产物分析与体积优化配置改完之后怎么知道效果好不好答案是看构建产物。Vue CLI 内置了--report参数跑vue-cli-service build --report会生成一个report.html用浏览器打开就能看到每个模块的体积占比。我一般会重点关注三类东西一是体积特别大的第三方库比如某些图表库、编辑器库看看能不能按需引入或者换更轻量的方案二是重复打包的依赖同一个库被多个 chunk 引入可以通过splitChunks配置抽出来三是自己写的业务代码里有没有误引入整个库的情况比如import _ from lodash就会把整个 lodash 打进去改成import debounce from lodash/debounce能省不少体积。在vue.config.js里可以通过configureWebpack或chainWebpack来调整 webpack 配置。比如配置externals把某些大库排除出打包改用 CDN 引入// vue.config.js module.exports { configureWebpack: { externals: { vue: Vue, element-ui: ELEMENT } } }这样打包时就不会把 vue 和 element-ui 打进去而是在index.html里通过 script 标签引入。代价是增加了对外部 CDN 的依赖需要权衡。5. 常见问题与排查技巧实录5.1 配置改了不生效的排查思路这是最高频的问题。我的排查顺序是这样的先确认改的文件是不是当前构建真正加载的那个。比如你改了.env.production但跑的是npm run serve开发模式那当然不生效。可以在配置文件里加一行console.log看构建时有没有打印出来。其次确认变量名有没有写对。.env文件里的变量必须以VUE_APP_开头config/index.js里的字段名要和代码里引用的完全一致大小写都不能错。我遇到过把assetsPublicPath写成assetPublicPath的构建不报错但资源路径就是不对查了半天。最后确认有没有缓存干扰。构建工具的缓存有时候会记住旧配置删掉node_modules/.cache目录再重新构建往往能解决一些莫名其妙的问题。5.2 环境变量注入失败的典型原因环境变量拿不到通常逃不出这几种情况。一是变量名没加VUE_APP_前缀这个前面说过。二是.env文件放错了位置必须在项目根目录和package.json同级。三是 mode 名字和文件名对不上--mode staging就得有.env.staging。四是值里带了特殊字符没转义比如地址里有#或空格需要用引号包起来。还有一种隐蔽的情况变量在构建时被静态替换如果你在代码里用动态拼接的方式访问比如process.env[VUE_APP_ key]是拿不到值的因为构建工具只做字面量替换不做运行时求值。这个坑比较深遇到时容易懵。5.3 常见问题速查表问题现象可能原因排查方向页面白屏控制台资源 404assetsPublicPath 配置错误检查部署路径与配置是否一致接口请求跨域代理未配置或生产环境未配 CORS开发查 proxy生产查后端 CORS环境变量为 undefined变量名缺 VUE_APP_ 前缀检查 .env 文件变量命名改了配置没反应加载了错误的配置文件打印 NODE_ENV 确认当前模式打包体积异常大全量引入第三方库用 --report 分析改按需引入构建报错找不到模块路径别名未配置检查 resolve.alias 配置5.4 几个我踩过的坑和独家经验第一个坑是关于pathRewrite的。有次配代理前端请求/api/user后端接口实际是/user我配了pathRewrite: { ^/api: }结果一直 404。后来发现是changeOrigin没开后端根据 host 做了拦截。这两个参数经常要一起调别只顾一个。第二个经验是关于配置文件的注释。config目录里的配置项尤其是那些看起来没用但删了会出问题的一定要写清楚为什么这么配。我接手过一个项目assetsPublicPath被设成了一个奇怪的路径没人知道为什么后来发现是为了兼容某个历史部署环境。如果当时有注释能省下我半天时间。第三个经验是环境变量的安全边界。前端打包后的代码是公开的任何注入到客户端的变量都能被看到。所以 API 密钥、加密盐值这类敏感信息绝对不能放进VUE_APP_变量里。需要保密的逻辑必须放在后端前端只拿必要的公开配置。第四个经验是关于配置的版本管理。.env.local这类个人配置要忽略但.env.development、.env.production这些团队共用的配置必须提交到仓库而且要保证团队成员拿到的是一致的。我见过因为某人本地改了.env.development没提交导致别人拉下来跑不起来的尴尬情况。6. 配置体系的演进与个人实践建议6.1 从 webpack 到 Vite配置思路的迁移现在越来越多的新项目转向 Vite配置体系又变了一轮。Vite 用vite.config.js替代了vue.config.js环境变量依然走.env文件体系但前缀从VUE_APP_变成了VITE_。代理配置从devServer.proxy变成了server.proxy写法大同小异。迁移时最需要注意的是Vite 基于原生 ES 模块开发时不做打包所以一些依赖 webpack 特性的配置比如某些 loader需要换成 Vite 插件。但配置分离、环境变量注入这些核心思想是不变的。理解了config目录背后的设计逻辑换工具时只是换个写法思路是通的。6.2 我个人的配置组织习惯做了这么多项目我现在的习惯是不管用哪套脚手架都在根目录保留一个config目录里面按职责分文件。环境变量放.env系列构建相关的自定义配置放build.config.js代理规则单独放proxy.config.js然后在主配置文件里引用。这样每个文件职责单一改起来不用在一大坨配置里翻找。另外我会在config目录里放一个README.md简单说明每个文件的作用和关键字段的含义。别小看这个习惯团队里新人接手时这份说明能省下大量沟通成本。配置这东西写的时候觉得一目了然过三个月自己都未必记得当初为什么那么配。配置管理说到底是个前人栽树后人乘凉的事。多花十分钟把配置写清楚、注释写明白未来能省下的排查时间可能是十倍百倍。这也是我把config目录单独拎出来讲的原因——它不显眼但它是项目能不能顺利跑起来、能不能稳定发出去的地基。