Vite .env 多环境自定义打包与加载机制避坑指南

Vite 项目里.env文件这件事说简单也简单——不就是加个VITE_前缀然后在代码里import.meta.env一下吗。但真正落到自定义打包这个场景上麻烦就来了同一套源码要出测试包、预发包、生产包接口地址、埋点开关、资源前缀、打点域名全都不一样打包机上环境变量一多.env文件的加载顺序就开始玄学好不容易配好了本地dev跑得好好的build出来的产物却把开发用的接口地址打了进去。我见过太多人卡在这一步最后干脆在代码里写一堆if (location.hostname.includes(test))硬判域名把构建配置的活儿硬生生挪到了运行时。这篇内容就围绕 Vite 中.env文件的加载机制、--mode自定义打包、loadEnv的正确用法、以及那些只有上线后才暴露出来的坑按从业者视角完整拆一遍。适合正在用 Vite 做多环境部署、或者被变量怎么没生效折磨过的同学从刚入门到已经能自己搭构建脚手架的人都能对上号。1. 从 process.env 到 import.meta.env先搞懂 Vite 换掉了什么在 webpack 时代待久了的人切到 Vite 第一反应就是找process.env.NODE_ENV然后在业务代码里写process.env.VUE_APP_API跑起来一看是undefined翻文档才发现根本不是这么回事。这一节把底层机制先讲透后面的所有配置都建立在这个机制上。1.1 为什么 Vite 不再把环境变量挂在 process 上webpack 的DefinePlugin是把process.env.XXX这种字符串在编译期直接替换成字面量Vite 其实也是静态替换的思路只是换了个命名空间——import.meta.env。这里有两个层面的原因理解了才能不踩坑。第一个层面是 ESM 规范。Vite 是原生 ESM 优先的构建工具开发态直接交给浏览器跑 ESM浏览器里根本没有 Node 的process全局对象除非你手动 polyfill但那是倒行逆施。import.meta是 ESM 标准里预留的元信息载体各家工具都能往上面挂自定义字段天然适合承载构建期注入的变量。用process.env在 dev 阶段会因为process is not defined直接崩掉。第二个层面是安全边界。webpack 那套配置里只要用了DefinePlugin注入process.env某个键那个键就进了产物很多人为了省事直接把整个process.env都注入进去结果打包产物里带出了 CI 机器的路径、token 之类的信息。Vite 用独立命名空间 VITE_前缀白名单的方式把哪些变量能进产物这件事显式化了。默认情况下只有以VITE_开头的变量才会被暴露到import.meta.env里其余变量哪怕在.env里写了也不会往下传。# .env.production VITE_API_BASEhttps://api.example-prod.internal DB_PASSWORDshould-never-ship上面这个文件里VITE_API_BASE会出现在客户端产物里DB_PASSWORD不会。如果你确实需要把某个非VITE_开头的变量用到浏览器端得在vite.config.ts里通过envPrefix显式改前缀// vite.config.ts export default defineConfig({ envPrefix: [VITE_, APP_] // 现在 APP_ 开头的也会注入 })提示envPrefix一旦放宽就等于把一批变量放进公开产物的白名单里。改之前先确认这批变量里没有密钥类信息否则后面出事很难查。1.2 静态替换意味着变量不是运行时读到的这是新人最容易误解的一点。很多人把.env当成运行时配置改完文件重新部署一下以为就生效了实际上 Vite 在build阶段就把import.meta.env.VITE_API_BASE这段代码字面替换成了字符串常量。// 源码里写的是 const base import.meta.env.VITE_API_BASE // 产物里实际变成简化示意 const base https://api.example-prod.internal这个替换行为带来几个连锁反应必须提前知道打包完成后产物是死的变量值已经写死在 JS 里改.env文件对已经生成的dist毫无影响必须重新build。变量值如果是true/false/ 数字产物里也是字符串false作为字符串是真值直接拿去做if判断会永远为真——这个坑我后面第 4 节单独展开。因为值是假的、能在编译期确定所以 Vite / Rollup 可以对if (import.meta.env.VITE_FEATURE_FLAG true)这种分支做 dead code elimination把没走到的分支整个从产物里删掉。这也是用环境变量做功能开关能比if (location.host)更省体积的原因。反过来说任何依赖运行时才能确定的环境比如容器启动时才知道的域名就不能只靠.envimport.meta.env解决得走运行时配置方案这部分放到第 6 节。development 和 production 是两个内置模式不要浪费。Vite 会自动根据vite dev/vite build设置MODE并且在build时把import.meta.env.PROD置为true、DEV置为false。业务里需要区分开发和生产逻辑时优先用这两个内置布尔量比自己再加一个VITE_ENV变量更省事也不会漏掉压缩场景。2. .env 文件的加载顺序与 mode 参数的真实作用这一节是自定义打包的地基。很多人.env的坑不是配错了内容而是配错了文件名导致你以为读了 A 文件实际读的是 B 文件。2.1 四个层级文件的优先级链Vite 加载.env文件不是只认一个而是一组按优先级从低到高覆盖。同一个变量在多个文件里出现高优先级的覆盖低的。这套顺序搞反了就会出现我在.env里改了没生效原来是被.env.production盖住了的情况。优先级文件名适用模式是否建议入库典型用途1最低.env所有模式是全环境公共变量如应用标题、通用配置2.env.local所有模式否本地开发者私有变量如本地 mock 地址3.env.[mode]指定模式是各环境差异化变量如测试/生产的接口地址4.env.[mode].local指定模式否特定模式的本地私有覆盖加载顺序的直觉模型是先来一个公共底座再叠上模式特殊配置最后用本地私有文件兜底覆盖。所以当调试变量为什么不生效时排查顺序应该是从上往下看有没有更高优先级的文件覆盖了它而不是先去怀疑代码写错。关于.local结尾的文件还有一个附加规则Vite 不会自动把它们加入 git 忽略官方只是建议你手动加进.gitignore。这意味着如果你忘了加本地开发者私有的、带个人 token 的.env.development.local有可能被误提交。项目初始化时第一件事就是打开.gitignore补上这几行# .gitignore .env.local .env.*.local2.2 --mode 参数到底决定了哪几件事--mode xxx不是简单地多加载一个.env.xxx文件就算完。它其实同时影响三件事很多人只知道第一件决定加载哪组.env.[mode]文件就是上一节表里的第 3、4 行。决定import.meta.env.MODE的值你在业务代码里可以通过它拿到当前模式字符串。影响NODE_ENV的默认值。vite build时--mode如果不是productionNODE_ENV默认是production注意这一点vite dev时--mode如果不是developmentNODE_ENV默认是development。这意味着一个常见的陷阱用vite build --mode staging打测试包NODE_ENV依然是production。如果你在某处依赖NODE_ENV development来开启某些调试逻辑比如打印详细日志在 staging 包里这些逻辑不会生效。想让它生效就得显式在.env.staging里加一行# .env.staging NODE_ENVdevelopment这种做法有利有弊把测试环境当成开发态配置 生产态构建的组合可以保留调试信息、sourcemap、详细日志。但要注意这种写法下部分库比如 React、Vue 的某些优化会根据NODE_ENV走不同分支确认一下你们的依赖树对这些行为无强依赖避免线上体验不一致。2.3 模式命名里那个容易被忽视的保留字官方文档里有一条容易扫过去的规定mode不能命名为local。原因很简单.env.local是所有模式的本地覆盖文件占位如果你用--mode localVite 会去加载.env.local和.env.local.local逻辑上完全乱套。我见过一个项目把本地联调模式命名成local跑vite build --mode local时候一脸懵最后追了两个小时才想起来是保留字。约定俗成的模式命名建议收敛在以下几种development本地开发默认、production正式环境默认、staging预发/测试、uat用户验收、gray灰度。模式名尽量用短横线或下划线连接别用大写和中文字符因为部分 shell / CI 平台传参时会有转义问题。3. 自定义打包链路从一条命令到最终产物的完整配置理论讲完进正题。所谓自定义打包本质上就是让同一份源码在不同mode下产出不同配置的产物然后部署到不同环境。这一节把从脚本到配置再到业务的链路拉通。3.1 package.json 脚本与 mode 的映射关系我倾向于把每个环境收敛成一条明确的 npm script命名直观不玩花活。别用build:test、build-uat、uat-build三种风格混着来团队里混着用迟早出错。{ scripts: { dev: vite, dev:test: vite --mode staging, build: vite build, build:staging: vite build --mode staging, build:uat: vite build --mode uat, build:gray: vite build --mode gray } }注意dev:test这条是很多人忽略的实用习惯本地开发时直接连测试环境的接口配合.env.staging里配置的假数据接口比在本地起一堆 mock 服务省事得多。但记得把.env.staging.local加进 gitignore用来覆盖本机特有的东西比如本地代理地址。CI 里调用打包脚本时永远只调用 script不要在 CI 里直接写npx vite build --mode xxx。原因很简单脚本是对外契约未来换构建工具比如切到别的 bundler或者加个前置步骤如版本号注入只需要改package.jsonCI 配置不用动。我现在的习惯是哪怕 script 里目前就是一条命令也保留这一层封装。3.2 vite.config.ts 里想读环境变量只能用 loadEnv打开配置文件你会发现vite.config.ts是最特殊的地方——它的执行时机在 Vite 加载.env之前或者更准确地说配置文件本身要先被加载才能进行后续的环境变量处理。所以在这个文件里写import.meta.env.VITE_API_BASE拿不到值process.env.VITE_API_BASE也可能拿不到得显式调用loadEnv。// vite.config.ts import { defineConfig, loadEnv } from vite export default defineConfig(({ mode }) { // 第三个参数传 表示加载所有变量不限于 VITE_ 前缀 const env loadEnv(mode, process.cwd(), ) console.log([build] mode:, mode) console.log([build] api base:, env.VITE_API_BASE) return { base: env.VITE_CDN_PREFIX || /, build: { sourcemap: env.VITE_ENABLE_SOURCEMAP true, }, define: { __APP_VERSION__: JSON.stringify(env.VITE_APP_VERSION || 0.0.0), } } })这里有几个实操细节值得展开loadEnv(mode, envDir, prefixes)的第三个参数如果是VITE_只会返回VITE_开头的变量如果传返回所有变量。传是双刃剑好处是可以在配置里读取像NODE_ENV这种非VITE_前缀变量坏处是如果你把loadEnv的结果直接塞进define就可能把敏感变量泄进产物。我自己的规范是读取全部变量做配置判断没问题但拼接到define/ 页面里的值必须显式挑出来。envDir传process.cwd()依赖脚本的执行目录。CI 里如果误在子目录里执行loadEnv会加载不到文件返回空对象而且不会报错——这个静默失败很坑所以我在启动日志里打印了一次env的关键键用于确认。更稳的写法是用path.resolve(__dirname, .)明确锚定项目根目录。import path from node:path const envDir path.resolve(__dirname) export default defineConfig(({ mode }) { const env loadEnv(mode, envDir, ) // ... })3.3 用变量驱动产物目录与资源前缀多环境打包最常见的需求就是测试包和生产包的静态资源目录/地址分开。做法不复杂全靠base和build.outDir两个配置项。export default defineConfig(({ mode }) { const env loadEnv(mode, process.cwd(), ) return { // 生产包走 CDN其他环境走相对路径方便直接丢到测试服务器任意目录 base: mode production ? env.VITE_CDN_PREFIX : /, build: { outDir: dist/${mode}, // 每个模式一个独立产物目录 sourcemap: mode ! production, rollupOptions: { output: { // 按模式加版本前缀方便回滚时定位 entryFileNames: assets/[name].${env.VITE_BUILD_TAG}.[hash].js, } } } } })把outDir按 mode 分目录后CI 归档、发布脚本选择产物都会清晰很多。我踩过的坑是早期所有环境统一打到dist/结果有次一个发布脚本忘了先rm -rf dist把上一次的生产产物和新的测试产物混在一起发上去了——排查了两小时才发现。分目录之后这类问题就没再出现过。base那一段的写法有个细节VITE_CDN_PREFIX通常是以/结尾的完整 URL如https://cdn.example.com/app/一旦末尾漏了斜杠拼出来的资源路径就成了https://cdn.example.com/appassets/...。校验方法很简单打包完打开dist/index.html搜一下script src第一眼就能看出路径对不对别指望部署后再发现。3.4 功能开关用变量控制分支并让编译器减掉死代码业务上总会有一些功能需要按环境灰度上线比如某个新控件只在生产打开、某个调试工具只在测试打开。用环境变量控制是最自然的方式而且配合静态替换可以真正把死分支从产物里删掉。// src/features/analytics.js if (import.meta.env.VITE_ENABLE_ANALYTICS true) { // 只有在 env 为 true 时这段代码才进产物 initAnalytics() }这段代码生效的前提是条件能编译期求值。import.meta.env.VITE_ENABLE_ANALYTICS在 build 阶段被替换成true或者false字符串与true比较后是常量表达式Rollup 就会删掉不成立的分支。这样打包后测试包和生产包对这段逻辑的体积占用也完全不同。但要注意一个反例如果你把变量先赋给一个变量再判断比如const flag import.meta.env.VITE_ENABLE_ANALYTICS if (flag true) { ... }虽然理论上编译器能追踪到但实际 Rollup 的分析能力有限也可能不会优化掉导致死代码仍进产物只是运行时不会执行。所以约定俗成的写法规矩是做功能开关时条件判断里直接写import.meta.env.XXX全路径不要中转赋值。这个约定要写进团队规范里否则新人习惯性抽变量就白优化了。4. 变量类型、前缀与构建缓存那些上线后才暴露的坑前面讲的是怎么配现在讲怎么翻车。下面每一条都是我自己或者身边同事真实踩过的不是网上抄的。4.1 一切都是字符串布尔与数字的隐形陷阱.env文件里写的东西无论看起来像什么类型读出来都是字符串。这是所有坑里发病率最高的一个而且它的表现往往很反常。# .env.production VITE_FEATURE_Atrue VITE_TIMEOUT3000 VITE_DEBUGfalse// 这段代码在 .env 里 VITE_DEBUG 是 false 的情况下会开启 debug if (import.meta.env.VITE_DEBUG) { enableDebugPanel() // 居然执行了 }原因前面提过false是非空字符串在 JS 里是 truthy。所以判断布尔值时正确写法只有两种// 写法一与字符串比较 if (import.meta.env.VITE_DEBUG true) { ... } // 写法二在 vite.config 里通过 define 提前转换推荐统一收集型变量 // vite.config.ts define: { __FEATURES__: JSON.stringify({ debug: env.VITE_DEBUG true, analytics: env.VITE_ENABLE_ANALYTICS true, }) }第二种写法好处是把所有布尔开关集中到一处转换业务代码里只需if (__FEATURES__.debug)不会有每个判断都写一次 true的啰嗦。数字同理Number(import.meta.env.VITE_TIMEOUT || 3000)是必须的别忘了后面跟个兜底值否则某个环境忘记配这个变量就会变成NaN接口超时时间设置成NaN会让 fetch 直接报错这种错误比变量没配还难排查。我现在的习惯是单独写一个小文件统一解析和导出// src/config/env.ts export const appConfig { apiBase: import.meta.env.VITE_API_BASE || /api, timeout: Number(import.meta.env.VITE_TIMEOUT) || 10000, enableDebug: import.meta.env.VITE_DEBUG true, appTitle: import.meta.env.VITE_APP_TITLE || 默认标题, }业务代码统一从appConfig里取其他地方禁止直接import.meta.env.XXX。这条纪律能有效防止某个页面写了if (import.meta.env.VITE_XXX)忘写 true这种破事也让未来做环境变量集中校验、切换运行时配置有统一入口。4.2 VITE_ 前缀是白名单不是装饰只要是被暴露出来的变量在打包产物里就是明文可读的这一点无论用什么前缀都无法改变。有人觉得我把变量名起得让人看不懂就能藏住——不存在的抓个包或者打开 sourcemap 都能看见。所以判断一个变量能不能加VITE_前缀的唯一标准是这个值能否公开给用户看。能公开的接口基础地址、埋点 appKey非密钥型、CDN 前缀、主题色、功能开关、应用版本、公告文案。 绝对不能公开的数据库密码、私有 API token、第三方服务 secret、签名盐值、内部域名中蕴含的组织结构信息。顺便说 internal 域名这个容易被忽略的点前端可能觉得反正内网访问不到但如果你打包产物放在公网可访问的静态资源里域名本身就是一种信息泄露。我的做法是所有能公网访问的产物中接口地址统一走同一域名下的/api路径由网关或反代来做环境路由从根上避免暴露多个内部子域。如果你确实需要客户端知道某个看起来像密钥的东西比如某些地图服务的 key天然就要暴露在前端那就只能接受它公开的事实转而用域名白名单 配额限制在服务端做防护别指望在构建工具这一层藏住。4.3 构建缓存不同步改了 .env 但构建结果还是旧的这个问题在 CI 有构建缓存时特别常见。表现是你明明在.env.staging里改了接口地址重新跑构建部署后一看还是旧地址。如果构建机上开了缓存很多平台默认缓存node_modules、.vite、dist目录很容易出现这种状态不一致。排查路径我在实践里沉淀成下面这条固定链路先确认构建机拿到的.env文件本身是新版在构建日志里打一行cat .env.staging | grep VITE_API_BASE直接看源文件。这一步排除掉代码没拉全、分支拉错的可能。再看构建产物中实际打进去的值grep -r api.example-staging dist/staging/assets/*.js如果没有说明变量压根没读进来。这一步能区分文件对了但没读到和读到了但产物没更新。排查.vite缓存目录Vite 的依赖预构建缓存放在node_modules/.vite一般不影响import.meta.env的替换那是在源码 transform 层做的但如果开了类似optimizeDeps.cacheDir的自定义目录并且跨环境复用就可能出现污染。清除方式就是删掉目录重跑。检查 CI 的缓存 key如果缓存 key 里没有包含.env文件的 hash缓存命中后构建工具可能直接复用旧结果。把缓存 key 改成包含hashFiles(.env*)之后问题消失。注意在 CI 里做环境变量校验时直接console.log(env)打印整个环境变量对象在部分平台会被脱敏工具截断或隐藏部分字段导致日志看起来一切正常。稳妥做法是只打印当前构建关心的那 3-5 个键名。4.4 静态部署后变量没生效的两种典型错法第一个典型错法是把.env当成运行时可编辑的配置文件。很多后端出身的同事默认会把.env留在部署目录里以为可以直接改文件重启一下就生效。静态服务器不重启、也没有重启这回事产物里的 JS 已经是死的。想做到部署后改配置必须走下一节说的运行时配置。第二个典型错法是直接复制.env里的内容到 HTML 的全局变量中比如手动在index.html里scriptwindow.__CONFIG__ {...}/script然后忘了让这部分内容进构建流程。结果是本地手动改的配置被提交线上也跟着变了。正确做法是下一节的占位符 部署时替换或独立的 config.json 运行时加载。5. TypeScript 类型提示让 env 变量不再裸奔用 TypeScript 的项目里如果import.meta.env.XXX一点提示都没有很容易写出拼错的变量名编译器又完全不管运行时才undefined。这一节把类型声明的标准写法讲清楚它不复杂但顺序和落位写错了就不生效。5.1 env.d.ts 的标准骨架在src/目录下建一个env.d.ts项目里已有的vite-env.d.ts可以合并进去用ImportMetaEnv接口声明所有自定义变量。/// reference typesvite/client / interface ImportMetaEnv { readonly VITE_API_BASE: string readonly VITE_APP_TITLE: string readonly VITE_TIMEOUT: string readonly VITE_DEBUG: true | false readonly VITE_CDN_PREFIX: string } interface ImportMeta { readonly env: ImportMetaEnv }几个容易写错的点一定要带/// reference typesvite/client /这一行否则 IDE 可能识别不做内置的MODE、DEV、PROD。变量类型声明为readonly防止业务代码里意外改写虽然运行时也不允许但声明层加上能提早发现问题。布尔类变量声明成true | false联合类型强迫业务代码里用 true比较可以借 IDE 提示规避 4.1 里那个经典坑。如果你在多个入口比如主应用 嵌入子应用共享类型可以把ImportMetaEnv抽到独立的types/env.d.ts然后再被各子项目include进来。5.2 变量缺失的提前暴露写一个加载校验即使有类型提示.env文件里漏配某个变量的情况也时有发生尤其 CI 环境切换时。类型系统管不住.env文件的正确性得在vite.config.ts里加一段校验。好处是在打包最早期就报错别等到用户打开页面白屏。const REQUIRED_ENV_KEYS [ VITE_API_BASE, VITE_APP_TITLE, VITE_CDN_PREFIX, ] as const export default defineConfig(({ mode }) { const env loadEnv(mode, process.cwd(), ) if (mode ! development) { const missing REQUIRED_ENV_KEYS.filter(k !env[k]) if (missing.length 0) { throw new Error( [env] 模式 ${mode} 缺少必需变量: ${missing.join(, )} ) } } return { /* ... */ } })对development模式放行是有意为之——本地开发经常只想快速起项目验证一个 UI 改动如果因为.env里缺个 CDN 前缀就起不来体验很差。非开发模式一律强校验不符合就打断构建。这条规则在团队里用得越久越能体现价值它把变量漏配这类问题从线上不可预料的白屏变成了 CI 一眼能看到的红色报错。6. 运行时配置什么时候必须跳出 import.meta.env不是所有场景都能靠构建期注入解决。用 Docker 打一次镜像、部署到 k8s 多环境、灰度环境动态切换这类情况要求同一个产物在不同环境里跑。这时候就必须做运行时配置不能把环境的差异固化进构建产物。6.1 什么信号说明你需要运行时配置识别信号有三个一套镜像要部署到多个集群镜像本身不能区分环境。部署后可能需要临时切换某个开关比如紧急关闭埋点不想为此重新走一次完整构建。接口地址中间带环境标识而这个标识只有在容器真正启动时才能确定由基础设施注入。只要命中其中任何一条import.meta.env就不够了。它解决的是构建期已知的差异而不是部署期/运行期的差异。6.2 用 config.json 启动时加载做运行时配置最直接的做法是把部署期才知道的配置作为public目录下的静态文件输出页面初始化时先加载它。public目录的内容会被原样复制到产物根目录部署时可以直接修改而不影响其他构建产物。// public/config.json { apiBase: /api, enableAnalytics: false, appTitle: }!-- index.html -- script // 阻塞一点没关系配置加载很快避免业务代码先跑到 __CONFIG__ 为 undefined (function () { var xhr new XMLHttpRequest() xhr.open(GET, /config.json, false) // 同步请求仅用于启动配置 xhr.send() try { window.__CONFIG__ JSON.parse(xhr.responseText) } catch (e) { window.__CONFIG__ {} } })() /script同步 XHR 已经不推荐用了如果对首屏性能敏感可以改成async加载 Promise 门控把业务初始化放在config加载完成的回调里。更优雅的方案是借助vite-plugin-html之类的插件在index.html里注入占位符然后在部署脚本里用sed替换比如 sh 脚本sed -i s|__API_BASE__|$API_BASE|g index.html效果等价但不需要发额外请求。但无论哪种方案注意两点import.meta.env和window.__CONFIG__两套机制不能混用后不明确优先级。建议是能在构建期确定的走import.meta.env只有真正需要部署期确定的才走__CONFIG__且统一在src/config/env.ts里做一次合并其他业务代码只认合并后的appConfig不要在业务层直接读window.__CONFIG__。部署脚本里的占位符替换一定要有兜底如果变量未设置sed会把__API_BASE__原样留在 HTML 里页面会静默使用错误路径。脚本里加一句if [ -z $API_BASE ]; then exit 1; fi拦住这种失误。我这边的实践是双轨并行构建期变量负责配置那些和产物本身强相关的CDN 前缀、版本号、编译优化开关运行时配置负责那些真正因部署环境而异的接口网关、灰度群组、紧急开关。这个分界线划清楚之后两套机制就不打架了。上面这些内容里我自己最深的体会是环境变量这件事的复杂度不在代码上而在于你以为它会在哪个时刻生效。把加载优先级、静态替换、类型转换这三条刻在脑子里之后剩下的都是配置项的排列组合。另外再分享一个排查小技巧当你怀疑某个变量没生效时先在产物里grep关键词找不到就是在构建阶段就丢了找得到但值不对就是覆盖顺序的问题这两步走完基本锁定方向别一上来就去怀疑框架 bug。