1. 项目概述为什么环境变量是跨端开发的“命门”最近在带几个新人做UniApp项目发现一个挺普遍的问题大家本地开发跑得好好的一到测试或生产环境接口地址、AppID、密钥这些就全乱套了要么就是打包后配置没生效要么就是不同环境配置混在一起。追根溯源问题往往出在环境变量配置这个基础环节上。很多人觉得这不过是几个配置文件照着教程配一下就行但真到了多环境、跨平台H5、小程序、App的UniApp Vue3 Vite项目里这里面的门道可不少。环境变量本质上是一套“运行时注入”的配置管理方案。它允许我们将与环境相关的配置如API基地址、调试开关、第三方密钥从代码中剥离出来实现“一份代码多处部署”。对于UniApp这种一次开发、多端发布的框架来说这一点尤为重要。想象一下你的应用需要对接的后端API在开发时可能是http://localhost:3000测试环境是https://test-api.example.com而上线后则是https://api.example.com。如果这些地址硬编码在代码里每次切换环境都得改代码、重新打包不仅效率低下而且极易出错。Vue3 Vite的组合为现代前端开发带来了极致的开发体验其基于ES模块的原生支持使得模块热更新HMR速度飞快。Vite在处理环境变量时也有一套自己的约定和构建时替换机制。但UniApp作为一个上层框架它对构建流程有自己的一套封装和扩展特别是在处理多平台如微信小程序、App时其构建目标和过程与纯Web项目有所不同。这就导致了一个常见的困境直接套用Vite或Vue CLI那套环境变量配置方法在UniApp里可能行不通或者只在H5端生效到了小程序和App端就“失灵”了。因此理清在UniApp Vue3 Vite技术栈下环境变量如何正确配置、如何在代码中安全获取、以及如何适配多端构建就成了一个必须扎实掌握的核心技能。这不仅仅是配几个文件那么简单它关系到项目的可维护性、团队协作的规范性以及最终交付的可靠性。接下来我就结合最近几个项目的实战经验把这套配置体系的思路、具体做法和踩过的坑系统地梳理一遍。2. 环境变量配置的核心思路与方案选型在开始动手写配置之前我们必须先想清楚目标我们需要一套怎样的环境变量管理方案结合UniApp多端发行的特点我认为一个理想的方案需要满足以下几个核心需求环境隔离清晰地区分开发development、测试staging、生产production等不同环境互不干扰。多端一致配置方案需要在H5、各家小程序微信、支付宝等、AppiOS/Android等所有UniApp支持的目标平台上都生效。安全可控敏感信息如密钥不应出现在前端代码仓库中而应通过安全的渠道注入。开发友好在开发时能方便地切换和预览不同环境的效果且支持热更新。构建集成能无缝融入Vite的构建流程并正确参与UniApp特有的编译过程。基于这些需求直接使用Vite原生环境变量.env文件是起点但并非终点。Vite使用dotenv从项目根目录的.env文件中加载环境变量并通过import.meta.env对象暴露给客户端代码。这是Vite的标准做法在纯Web项目中工作良好。然而UniApp的构建过程比纯Web项目复杂。当你运行npm run dev:mp-weixin开发微信小程序时UniApp CLI会调用Vite如果你配置了Vite模式进行源码编译但最终生成的是小程序的代码结构。在这个过程中Vite的环境变量替换是发生在源码编译阶段的。问题在于UniApp编译到不同平台时可能会对源码进行特定的转换和封装import.meta.env这个ES模块的元属性在某些平台特别是小程序环境其JavaScript运行环境并非标准的浏览器或Node可能无法被正确识别或访问。因此更稳健的方案是采用一种“双轨制”或“适配层”的思路构建时注入利用Vite的define配置将环境变量在构建时静态替换为具体的值。这样最终生成的代码里直接就是字符串常量不依赖于运行时的import.meta.env对象兼容性最好。运行时封装同时我们也可以创建一个统一的配置模块根据构建模式或平台特性安全地读取环境变量并提供统一的API给业务代码使用。经过多个项目的实践我总结出一套以“Vite环境变量文件为源通过define进行构建时替换并辅以统一配置模块”为核心的配置方案。这套方案能较好地平衡灵活性、兼容性和安全性。2.1 方案对比与决策在具体实施前我们简单对比几种常见做法方案优点缺点适用场景纯import.meta.envVite原生支持简单直接在小程序/App端可能无法访问变量值在构建后仍可能被查看非敏感信息可接受纯H5项目或仅用于非敏感、非关键的配置Vitedefine替换构建时静态替换生成字面量兼容性极佳可混淆敏感值需要预先明确所有变量名热更新需要重启服务修改.env文件时UniApp多端项目推荐尤其适合需要跨平台稳定运行的配置运行时HTTP请求加载配置可动态更新无需重新打包增加首屏加载依赖和复杂度需要处理加载失败和等待状态配置需要频繁变动的后台管理系统或微前端场景平台条件编译UniApp原生支持可针对不同平台写死不同配置配置散落在代码中难以维护无法根据构建环境dev/prod切换仅用于平台特性差异极大的配置不推荐用于环境变量对于大多数UniApp项目“Vitedefine替换”为主“统一配置模块”为辅的方案是最佳实践。它确保了配置在构建阶段就被确定并固化到产物中避免了运行时的兼容性问题同时通过配置模块提供了清晰的接口。3. 项目结构与环境变量文件设计明确了方案我们先来规划项目的目录结构和环境变量文件。一个清晰的结构是后续一切操作的基础。3.1 目录结构规划我建议在项目根目录下创建env文件夹或直接放在根目录专门管理环境变量相关文件。一个典型的结构如下your-uniapp-project/ ├── env/ # 环境变量目录 │ ├── .env.development # 开发环境 │ ├── .env.staging # 测试环境 │ ├── .env.production # 生产环境 │ └── .env # 所有环境的默认值可选 ├── src/ ├── vite.config.ts # Vite 配置文件 ├── manifest.json # UniApp 应用配置 └── package.json注意.env文件通常包含敏感信息务必将其添加到.gitignore中避免提交到代码仓库。可以将.env.example或.env.local仅包含变量名不含真实值提交供团队成员参考。3.2 环境变量文件内容示例每个.env.[mode]文件对应一种构建模式mode。Vite默认会根据你运行的命令如vite、vite build自动加载对应的文件。在UniApp中我们需要在package.json的 scripts 里指定模式。env/.env.development(开发环境)# 开发环境配置 VITE_APP_TITLE 我的应用(开发版) VITE_API_BASE_URL https://dev-api.example.com VITE_APP_DEBUG true VITE_WEIXIN_APPID wx1234567890abcdef # 开发用小程序AppIDenv/.env.staging(测试环境)# 测试环境配置 VITE_APP_TITLE 我的应用(测试版) VITE_API_BASE_URL https://staging-api.example.com VITE_APP_DEBUG true VITE_WEIXIN_APPID wxstaging1234567890env/.env.production(生产环境)# 生产环境配置 VITE_APP_TITLE 我的应用 VITE_API_BASE_URL https://api.example.com VITE_APP_DEBUG false VITE_WEIXIN_APPID wxproduction1234567890关键规则说明变量命名为了在客户端代码中能够被Vite捕获并处理自定义环境变量必须以VITE_开头。这是Vite的强制约定否则变量不会被载入import.meta.env。值类型等号右边的值会被解析为字符串。true或false在代码中获取时会是字符串true或false需要自行转换。模式覆盖Vite启动时会先加载.env文件所有模式共享然后根据--mode指定的模式加载对应的.env.[mode]文件后者会覆盖前者的同名变量。4. 核心配置Vite与UniApp的融合这是整个配置过程中最关键的一步我们需要修改vite.config.ts文件让Vite在构建UniApp时正确地将环境变量“注入”到最终代码中。4.1 修改vite.config.ts配置文件首先需要安装types/node以便在Vite配置中使用process等Node.js模块如果尚未安装npm install -D types/node然后在vite.config.ts中我们需要做两件事使用loadEnv函数加载指定模式的环境变量。通过define选项将环境变量定义为全局常量。// vite.config.ts import { defineConfig, loadEnv } from vite; import uni from dcloudio/vite-plugin-uni; import path from path; // https://vitejs.dev/config/ export default defineConfig(({ mode, command }) { // 1. 加载环境变量 // process.cwd() 返回项目根目录 // 第三个参数 表示加载所有以 VITE_ 开头的变量 const env loadEnv(mode, process.cwd() /env, ); // 注意我们指定了env目录 // 2. 准备需要注入的 define 对象 const define {} as Recordstring, any; // 遍历所有以 VITE_ 开头的环境变量将其注入 for (const key in env) { if (key.startsWith(VITE_)) { // 注意这里值需要 JSON.stringify因为 define 是做字符串替换 // 例如VITE_API_BASE_URL: https://api.com 会被替换为 https://api.com define[import.meta.env.${key}] JSON.stringify(env[key]); } } // 也可以注入一些通用的、非 VITE_ 前缀的变量或方便使用的别名 define[import.meta.env.MODE] JSON.stringify(mode); define[import.meta.env.PROD] JSON.stringify(command build); define[import.meta.env.DEV] JSON.stringify(command ! build); return { plugins: [uni()], // 3. 定义全局常量替换 define, // 其他配置如resolve.alias... resolve: { alias: { : path.resolve(__dirname, src), }, }, }; });这段配置的核心逻辑解释loadEnv(mode, process.cwd() /env, )从项目根目录下的/env文件夹中加载对应模式mode的环境变量。作为第三个参数意味着我们只加载前缀为即所有的变量但实际上我们后续通过if (key.startsWith(VITE_))进行了过滤这是一种更灵活的控制方式。你也可以直接写loadEnv(mode, process.cwd() /env, VITE_)来只加载VITE_开头的变量。define对象这是Vite的配置项它会在构建阶段将代码中出现的define对象的键如import.meta.env.VITE_API_BASE_URL直接替换为对应的值如https://api.example.com。这是一个静态文本替换的过程替换后的代码里不再有import.meta.env这个引用因此兼容性极高。JSON.stringify()这是必须的。因为define是做简单的字符串替换。如果不加JSON.stringify()假设env[key]是https://api.com替换后代码会变成import.meta.env.VITE_API_BASE_URL https://api.com这缺少引号会导致语法错误。经过JSON.stringify()后值变成了https://api.com带双引号的字符串替换后代码语法正确。4.2 修改package.json的 scripts接下来我们需要修改package.json中的启动和构建脚本通过--mode参数指定要使用的环境模式。{ scripts: { dev:h5: uni -p h5 --mode development, build:h5: uni build -p h5 --mode production, dev:mp-weixin: uni -p mp-weixin --mode development, build:mp-weixin: uni build -p mp-weixin --mode production, dev:app: uni -p app --mode development, build:app: uni build -p app --mode production, // 可以添加自定义模式如测试环境 build:staging:h5: uni build -p h5 --mode staging, build:staging:mp-weixin: uni build -p mp-weixin --mode staging } }关键点--mode development告诉Vite使用development模式从而加载env/.env.development文件。--mode production对应加载env/.env.production。--mode staging对应加载env/.env.staging这是我们自定义的模式。现在当你运行npm run dev:mp-weixin时Vite就会加载开发环境的变量并注入到代码中。5. 在代码中安全、优雅地使用环境变量配置好了构建过程接下来就是在业务代码中使用了。虽然经过define替换后我们可以直接使用import.meta.env.VITE_XXX但为了更好的类型提示、默认值处理和统一管理我强烈建议创建一个专门的配置模块。5.1 创建统一的环境配置模块在src目录下创建config文件夹并新建env.ts文件// src/config/env.ts /** * 应用运行环境类型 */ export type AppEnv development | staging | production; /** * 获取当前构建模式 * 通过 import.meta.env.MODE 获取该值已在 vite.config.ts 中通过 define 注入 */ export const getEnvMode (): AppEnv { const mode import.meta.env.MODE as string; if ([development, staging, production].includes(mode)) { return mode as AppEnv; } // 默认返回生产环境确保线上安全 return production; }; /** * 应用配置对象 * 所有环境变量在此集中定义并提供类型安全和默认值 */ const appConfig { // 应用标题 title: import.meta.env.VITE_APP_TITLE || UniApp, // API 基础地址 apiBaseUrl: import.meta.env.VITE_API_BASE_URL || , // 是否调试模式 isDebug: (import.meta.env.VITE_APP_DEBUG || false) true, // 微信小程序 AppID (如果需要) weixinAppId: import.meta.env.VITE_WEIXIN_APPID || , // 当前环境模式 mode: getEnvMode(), // 是否是生产环境 isProd: import.meta.env.PROD true, // 是否是开发环境 isDev: import.meta.env.DEV true, } as const; // 导出一个冻结的对象防止意外修改 export default Object.freeze(appConfig);这个模块的优势类型安全为配置对象提供了明确的类型定义。默认值处理避免了环境变量未定义导致的undefined错误。逻辑转换将字符串类型的VITE_APP_DEBUG转换为布尔值isDebug使用起来更直观。集中管理所有配置在一个地方方便查找和修改。只读保证通过Object.freeze防止运行时意外修改配置。5.2 在业务代码中使用配置现在在Vue组件、Composables或工具函数中你可以像下面这样使用script setup langts import { ref, onMounted } from vue; import envConfig from /config/env; // 使用别名指向src // 直接使用配置 const appTitle ref(envConfig.title); const apiBaseUrl envConfig.apiBaseUrl; onMounted(() { console.log(当前环境: ${envConfig.mode}); console.log(API地址: ${apiBaseUrl}); if (envConfig.isDebug) { console.warn(当前处于调试模式请注意控制台信息。); } // 发起网络请求示例 fetch(${apiBaseUrl}/user/profile) .then(res res.json()) .then(data console.log(data)); }); /script template view text{{ appTitle }}/text !-- ... -- /view /template5.3 处理平台特定配置有时某些配置可能因平台而异。例如微信小程序的AppID在H5环境下是无用的。我们可以在配置模块中增加平台判断逻辑。UniApp提供了uni.getSystemInfoSync().platform或条件编译。方法一运行时判断适用于逻辑简单的场景// 在 env.ts 中补充 import { getSystemInfoSync } from uni-get-system-info; // 或使用 uni.getSystemInfoSync const systemInfo getSystemInfoSync(); const isWeixinMiniProgram systemInfo.platform devtools || systemInfo.platform wechat; // 需精确判断 export const platformConfig { // 可以在这里根据平台返回不同的值 getAppId() { if (isWeixinMiniProgram) { return envConfig.weixinAppId; } return ; } };方法二条件编译更彻底代码更清晰条件编译是UniApp的强项适合平台差异大的配置。// src/config/env.ts let platformSpecificApi ; // #ifdef H5 platformSpecificApi /h5-api-proxy; // #endif // #ifdef MP-WEIXIN platformSpecificApi https://api.weixin.qq.com; // #endif // #ifdef APP platformSpecificApi envConfig.apiBaseUrl; // App可能用同一个 // #endif const appConfig { // ... 其他配置 platformApi: platformSpecificApi, };重要提示条件编译的注释 (// #ifdef) 是UniApp编译器识别的特殊注释它们会在编译到特定平台时被保留或移除。这确保了最终每个平台的代码只包含自己需要的部分。6. 多环境构建与部署实战配置写好了最终我们要打包部署。不同环境对应不同的命令和产物。6.1 配置 package.json scripts如前所述我们在package.json中已经配置了不同模式和平台的脚本。例如开发微信小程序npm run dev:mp-weixin(使用.env.development)构建生产环境H5npm run build:h5(使用.env.production)构建测试环境微信小程序npm run build:staging:mp-weixin(使用.env.staging)6.2 构建产物验证构建完成后如何确认环境变量正确注入了呢由于define是静态替换我们可以检查构建出的代码文件。对于H5检查dist/build/h5目录下的.js文件。搜索你定义的变量名例如VITE_API_BASE_URL你应该会发现它已经被替换成了具体的字符串值而不是import.meta.env.VITE_API_BASE_URL。对于小程序检查dist/dev/mp-weixin或dist/build/mp-weixin目录下的.js文件如app.js或页面js。同样搜索变量名确认已被替换。一个快速验证的方法在你的配置模块env.ts中添加一个在控制台打印配置的语句仅在开发环境if (import.meta.env.DEV) { console.log([Env Config], appConfig); }在开发时浏览器或开发者工具控制台会输出完整的配置对象。在构建生产包时由于import.meta.env.DEV被替换为false这段代码不会被执行不会泄露信息。6.3 敏感信息处理与安全建议绝对不要将真实的密钥、密码等敏感信息提交到代码仓库即使是测试环境的。使用.env.local或个人环境文件创建.env.local文件并加入.gitignore。在vite.config.ts中可以调整loadEnv逻辑优先加载本地覆盖文件。// 简化示例Vite本身支持 .env.local 覆盖 .env // 确保 .gitignore 包含 .env.local const env loadEnv(mode, process.cwd() /env, );CI/CD 管道注入在 Jenkins、GitLab CI、GitHub Actions 等持续集成/部署平台中将敏感信息设置为流水线的“机密变量”。在构建脚本中通过命令行参数或环境变量动态生成.env.production文件。# 示例在CI脚本中 echo VITE_API_BASE_URL$PRODUCTION_API_URL ./env/.env.production echo VITE_APP_KEY$PRODUCTION_APP_KEY ./env/.env.production npm run build:h5后端代理与鉴权最安全的做法是所有涉及敏感操作或数据的请求都不应该依赖前端环境变量中的密钥。前端只持有用于标识自身如AppID的非敏感信息具体的密钥应由后端服务器保管前端通过安全的鉴权流程如OAuth 2.0获取访问令牌。7. 常见问题、排查技巧与实战心得在实际项目中环境变量配置看似简单却容易遇到各种“坑”。下面是我总结的一些典型问题及解决方法。7.1 问题排查清单问题现象可能原因排查步骤与解决方案环境变量undefined1. 变量名不是以VITE_开头。2..env文件未放在正确目录或文件名与--mode不匹配。3.vite.config.ts中的loadEnv路径或前缀参数错误。4.define配置未正确注入该变量。1. 检查变量名确保以VITE_开头。2. 检查package.json脚本中的--mode参数确认对应的.env.[mode]文件存在且路径正确。3. 在vite.config.ts中console.log(env)打印加载的环境变量对象确认是否加载成功。4. 检查define对象中是否包含了该变量的键值对。H5正常小程序/App异常1. 代码中直接使用import.meta.env.VITE_XXX但该对象在小程序环境不可用。2. 未使用define进行构建时替换。确保使用了define配置。这是解决多端兼容性的关键。构建后检查小程序产物的js文件确认变量已被替换为字面量。修改.env文件后热更新不生效Vite 的环境变量热更新仅在服务启动时读取。define配置的替换是静态的。重启开发服务器。修改.env文件后需要停止并重新运行npm run dev:*命令。类型错误import.meta.env上不存在属性TypeScript 无法识别自定义的VITE_变量。在src目录下创建env.d.ts文件进行类型声明interface ImportMetaEnv { readonly VITE_APP_TITLE: string; readonly VITE_API_BASE_URL: string; }构建后代码中仍存在process.env项目中可能混用了Webpack或Node.js的process.env写法。UniApp Vite 项目应统一使用import.meta.env。全局搜索process.env并替换。Vite的define也可以用于替换process.env.NODE_ENV等。不同开发者本地环境不一致.env.development文件被意外提交并覆盖或者各自本地有未跟踪的配置。1.确保.env*.local和.env.development等在.gitignore中。2. 提交一个.env.example文件列出所有需要的变量名不含值供团队成员复制参考。3. 考虑使用dotenv库在代码中显式加载指定路径的文件但不如Vite集成方案优雅。7.2 实战心得与技巧环境变量命名规范化团队内部制定规范例如VITE_APP_前缀表示应用级配置VITE_API_前缀表示接口相关VITE_THIRD_表示第三方服务。一目了然便于管理。为配置模块编写单元测试虽然配置简单但写个简单的测试用例来验证getEnvMode()函数在不同import.meta.env.MODE值下的返回以及配置对象的默认值逻辑能有效防止后续修改时引入错误。善用条件编译处理平台差异对于真正因平台而异的配置如图片上传的API、社交分享的SDK初始化参数使用// #ifdef条件编译比在运行时通过if-else判断更干净还能减少无用代码被打包到其他平台。构建脚本自动化在package.json的 scripts 中可以组合命令。例如先清理旧构建产物再执行构建scripts: { clean: rimraf dist, build:prod:h5: npm run clean uni build -p h5 --mode production, }需要安装rimraf包npm i -D rimraf关注vite.config.ts的缓存有时修改了vite.config.ts但感觉没生效可能是Vite的缓存问题。可以尝试在启动命令后加上--force选项或者删除node_modules/.vite缓存目录。7.3 类型声明的完善为了让TypeScript更好地支持我们的环境变量创建src/env.d.ts文件// src/env.d.ts /// reference typesvite/client / // 扩展 ImportMetaEnv 接口定义自定义环境变量的类型 interface ImportMetaEnv { // 每个变量都应该是只读的 readonly VITE_APP_TITLE: string readonly VITE_API_BASE_URL: string readonly VITE_APP_DEBUG: string // 注意从.env读取的是字符串 readonly VITE_WEIXIN_APPID: string // 添加更多变量... } interface ImportMeta { readonly env: ImportMetaEnv }完成这一步后你在代码中键入import.meta.env.IDE就会自动提示出VITE_APP_TITLE等变量并且有正确的类型约束。经过以上从思路到实践从配置到排查的完整梳理相信你已经能够驾驭UniApp Vue3 Vite项目中的环境变量配置了。这套方案的核心在于理解Vite的构建时替换机制并利用它来规避UniApp多端运行时环境的差异。记住好的配置管理是项目工程化的基石花时间把它搭建稳健能为后续的开发、测试和部署省去无数麻烦。如果在实践中遇到新的问题不妨回头检查一下构建产物的代码看看变量是否被正确替换这往往是定位问题的捷径。