UniApp+Vue3+Vite环境变量配置全攻略：多端开发的核心实践-尧图网络科技

1. 项目概述：为什么环境变量是跨平台开发的“命门”？

如果你正在用 uniapp + vue3 + vite 这套技术栈开发应用，无论是小程序、H5还是App，环境变量配置绝对是你绕不开、也绝不能轻视的一环。这听起来像是个基础配置，但实际开发中，我见过太多团队在这里栽跟头：开发、测试、生产环境的API地址混用，导致测试数据污染线上；不同平台（如微信小程序和H5）的AppID配置混乱，打包出错；甚至因为一个环境变量没生效，整个应用在特定环境下白屏。

简单来说，环境变量就是给应用在不同“场合”下穿的不同“衣服”。开发时，我们连接本地的后端服务；测试时，指向测试服务器；上线时，则必须切换到生产环境的域名和密钥。在 uniapp 这种“一次开发，多端发布”的场景下，这个需求变得更加复杂，因为你可能还需要为不同平台（小程序、App、H5）配置差异化的参数，比如小程序特有的AppID，或者App独有的第三方SDK密钥。

传统的 webpack 方案在 uniapp 中自有其套路，但当我们拥抱更快的 vite 和组合式 API 的 vue3 时，原有的配置方法可能不再完全适用，或者有更优雅的解决方案。这次，我就结合最近几个项目的实战，把 uniapp + vue3 + vite 环境下，环境变量从设计、配置、读取到打包的完整链条，以及那些官方文档没细说的“坑”，给你彻底讲明白。无论你是刚接手一个现有项目，还是正准备从零搭建，这篇内容都能让你少走至少两天的弯路。

2. 环境变量设计：区分“编译时”与“运行时”

配置环境变量，第一步不是急着写代码，而是先理清思路：你需要哪些变量？它们应该在哪个阶段生效？在 uniapp 多端场景下，这是避免后续混乱的关键。

2.1 明确变量类型：编译时与运行时

这是最核心的概念，直接决定了你配置的方式和位置。

编译时环境变量：在项目构建（打包）过程中就被确定并替换的变量。它们会被直接“写死”到最终的构建产物（如 dist 目录下的 js 文件）中。
- 典型用途：VITE_API_BASE_URL（接口基地址）、VITE_APP_TITLE（应用标题）、不同环境的第三方SDK Key（这些Key通常不希望被轻易窥探）。它们的值在打包完成后就固定了，切换环境需要重新打包。
- Vite特性：Vite默认以VITE_开头的变量才会暴露给客户端代码。这是重要的安全特性，防止你将敏感的服务器端变量意外暴露到前端。
运行时环境变量：在应用代码实际运行在用户设备（浏览器、小程序、App）时才能确定的变量。
- 典型用途：用户的系统语言、屏幕宽度、网络类型、uni-app的平台标识（uni.getSystemInfoSync().platform）。这些显然无法在打包时确定。
- uniapp场景：我们有时也希望根据打包出的不同平台（如微信小程序 vs H5）来动态决定一些逻辑，这可以通过读取process.env.UNI_PLATFORM这类uniapp注入的编译时常量来实现，但它本质上是在编译时根据你的打包命令决定的，并非完全意义上的“运行时”。

实操心得：绝大多数业务配置，如API地址、应用ID、功能开关，都应设计为编译时环境变量。这样能保证每个部署包的环境是纯净、确定的。真正的“运行时”配置很少，且通常与用户设备状态相关。

2.2 规划多环境与多平台配置矩阵

一个成熟的项目需要应对多种环境。我通常采用以下命名约定，在项目根目录创建对应的.env文件：

.env：所有环境的默认值（可选，但建议保留基础配置）。
.env.development：本地开发环境。
.env.staging：测试/预发布环境。
.env.production：生产环境。

对于 uniapp，我们可能还需要考虑平台差异。例如，微信小程序要求配置appid，而H5不需要；某个 analytics SDK 在 App 端和 Web 端的 Key 不同。有两种主流思路：

环境文件内部分支：在一个环境文件（如.env.production）里，通过变量名后缀来区分，例如：
```
# .env.production VITE_APP_WX_APPID=wx1234567890abcdef VITE_APP_H5_TITLE=我的H5应用
```
然后在代码中根据process.env.UNI_PLATFORM判断使用哪个变量。
平台专属环境文件（更清晰）：Vite支持类似.env.[mode].[platform]的命名，但需要配合自定义逻辑。更实用的做法是，创建如.env.production.mp-weixin文件，并在打包脚本中指定加载。不过，uniapp的CLI对此支持不直接，我通常采用第一种或下面的“配置中心”方式。

避坑指南：不要试图用一套环境变量值适配所有平台。明确列出每个环境-平台组合所需的变量清单，能极大减少发布时的配置错误。我习惯用一个env-matrix.md文档来维护这个矩阵。

3. 核心配置解析：Vite与Uniapp的配置融合

理解了设计思路，我们开始动手配置。核心在于让 Vite 的 env 配置能力，顺畅地融入 uniapp 的构建体系。

3.1 环境变量文件的创建与优先级

在你的 uniapp 项目根目录（与vite.config.ts、src同级）创建上文提到的.env文件。Vite 会自动加载这些文件。

加载优先级（从高到低）：

指定模式下的.env.${mode}.local(本地覆盖，应加入.gitignore)
指定模式下的.env.${mode}
通用的.env.local
通用的.env

例如，执行npm run build:mp-weixin（对应mode为production），Vite会依次加载：.env.production.local->.env.production->.env.local->.env

注意事项：.env.local文件是给你本地覆盖配置用的，务必添加到.gitignore中，防止将本地数据库密码等敏感信息提交到仓库。

3.2 在`vite.config.ts`中传递环境变量

这是关键一步。我们需要在 Vite 配置中，将环境变量注入到 uniapp 的编译过程中。主要使用define选项。

// vite.config.ts import { defineConfig } from 'vite'; import uni from '@dcloudio/vite-plugin-uni'; import path from 'path'; // https://vitejs.dev/config/ export default defineConfig(({ mode }) => { // 这里可以根据 mode 动态加载不同的 dotenv 配置，但Vite已自动完成。 // 我们主要是获取并定义变量。 return { plugins: [uni()], define: { // 将 process.env 替换为一个自定义对象，避免 node 的 process 对象不存在于客户端 // 同时，我们只注入以 VITE_ 开头的变量，这是安全最佳实践 'process.env': { ...Object.keys(process.env).reduce((acc, key) => { if (key.startsWith('VITE_')) { acc[key] = JSON.stringify(process.env[key]); } return acc; }, {}), // 你也可以手动添加一些自定义的、非 VITE_ 前缀的变量，但务必谨慎 // 'CUSTOM_VAR': JSON.stringify('some_value'), // 非常重要：注入 uniapp 的平台模式，这在多端代码判断时极其有用 // Vite 的 mode 可能和 uniapp 的 platform 不完全对应，所以通常从命令行参数获取 // 一种更可靠的方式是通过 uniapp 插件或后续的脚本注入，这里先提供一个基础思路 'UNI_PLATFORM': JSON.stringify(process.env.UNI_PLATFORM || ''), 'UNI_SUB_PLATFORM': JSON.stringify(process.env.UNI_SUB_PLATFORM || ''), } }, // 其他配置... resolve: { alias: { '@': path.resolve(__dirname, 'src'), }, }, }; });

重要提示：上面的define配置是一个基础示例。在实际 uniapp 项目中，更推荐使用官方@dcloudio/vite-plugin-uni插件已经处理好的环境注入方式，或者使用社区更成熟的方案。直接替换process.env有时会与某些库的预期行为冲突。一个更安全、更常见的实践是：

// vite.config.ts export default defineConfig(({ mode }) => { // 1. 使用 loadEnv 加载指定模式的环境变量（Vite内置函数） const env = loadEnv(mode, process.cwd(), ''); // 2. 筛选出需要暴露给客户端的环境变量 const viteEnv = {}; Object.keys(env).forEach((key) => { if (key.startsWith('VITE_')) { viteEnv[key] = env[key]; } }); return { plugins: [uni()], define: { // 直接定义我们自己的全局常量，而不是覆盖 process.env '__VITE_ENV__': JSON.stringify(viteEnv), '__MODE__': JSON.stringify(mode), '__UNI_PLATFORM__': JSON.stringify(process.env.UNI_PLATFORM || ''), }, }; });

这样，我们在代码中就可以通过__VITE_ENV__.VITE_API_BASE_URL来访问变量，完全避免了与 Node.jsprocess.env的冲突。

3.3 在`package.json`中配置脚本命令

为了让不同的打包命令对应不同的环境，我们需要修改package.json中的scripts。

{ "scripts": { "dev:h5": "uni -p h5", "dev:mp-weixin": "uni -p mp-weixin", "build:h5": "uni build -p h5", "build:mp-weixin": "uni build -p mp-weixin", // 关键在这里：通过 --mode 参数指定环境 "build:staging:h5": "uni build -p h5 --mode staging", "build:production:h5": "uni build -p h5 --mode production", "build:staging:mp-weixin": "uni build -p mp-weixin --mode staging", "build:production:mp-weixin": "uni build -p mp-weixin --mode production" } }

运行npm run build:staging:mp-weixin时，Vite 会自动加载.env.staging文件，并将其中的变量注入到构建过程中。

踩坑实录：早期我忽略了--mode参数，一直用默认的development或production模式打包测试环境，导致环境变量错乱。务必为每个部署环境定义清晰的mode和对应的脚本命令。

4. 在代码中读取与使用环境变量

配置好了，如何在 Vue 组件或 JS 文件中使用呢？根据你在vite.config.ts中选择的注入方式，有两种主要方法。

4.1 方法一：使用`import.meta.env`（推荐，符合Vite标准）

如果你使用了 Vite 默认的规则（即以VITE_开头的变量），并且没有在define里覆盖它，那么可以直接使用import.meta.env对象。这是 Vite 官方推荐的方式。

<script setup> import { ref, onMounted } from 'vue'; // 直接访问环境变量 const apiBaseUrl = import.meta.env.VITE_API_BASE_URL; const appTitle = import.meta.env.VITE_APP_TITLE; const isProduction = import.meta.env.PROD; // Vite 内置，布尔值 const isDevelopment = import.meta.env.DEV; // Vite 内置，布尔值 console.log('接口基地址：', apiBaseUrl); console.log('应用标题：', appTitle); console.log('是否是生产环境：', isProduction); onMounted(() => { // 使用环境变量 document.title = appTitle; }); </script> <template> <view> <text>当前环境：{{ isProduction ? '生产' : '非生产' }}</text> <!-- 其他内容 --> </view> </template>

优点：标准、简洁，类型支持好（配合vite/client类型定义）。缺点：变量名必须严格以VITE_开头。

4.2 方法二：使用自定义的全局常量

如果你采用了上面推荐的第二种define配置（定义了__VITE_ENV__等），则需要这样使用：

<script setup> // 声明一个全局常量的引用（在Vite构建时会被替换为实际值） const viteEnv = __VITE_ENV__; const currentPlatform = __UNI_PLATFORM__; console.log('自定义环境变量：', viteEnv.VITE_APP_ID); console.log('当前平台：', currentPlatform); // 根据平台做条件渲染或逻辑 const isMpWeixin = currentPlatform === 'mp-weixin'; </script>

优点：更灵活，可以注入任意名称的变量，不与VITE_前缀绑定。缺点：需要自己维护类型定义，且失去了import.meta.env.PROD这样的内置变量。

4.3 为环境变量添加TypeScript智能提示

为了获得更好的开发体验，我们可以在src目录下创建一个env.d.ts文件，来扩展import.meta.env的类型。

// src/env.d.ts /// <reference types="vite/client" /> interface ImportMetaEnv { // 在这里添加你所有以 VITE_ 开头的环境变量及其类型 readonly VITE_API_BASE_URL: string readonly VITE_APP_TITLE: string readonly VITE_APP_ID: string readonly VITE_ENABLE_DEBUG: string // 注意，从 .env 文件读取的都是字符串 // 可以添加更多... } interface ImportMeta { readonly env: ImportMetaEnv }

定义之后，你在代码中键入import.meta.env.VITE_时，编辑器就会自动提示你定义过的变量名，并且有类型检查，避免了拼写错误。

5. 多端差异化配置与动态切换实战

uniapp开发中，真正的复杂性往往来自于不同平台的差异化需求。环境变量如何优雅地支持这种差异化？

5.1 策略一：环境变量内部判断

在.env.production文件中定义所有平台可能用到的变量，在代码中通过uni.getSystemInfoSync().platform或编译时注入的__UNI_PLATFORM__来判断。

# .env.production VITE_WX_APPID=生产环境微信小程序AppID VITE_H5_BASE_URL=https://h5.prod.com VITE_APP_BASE_URL=https://app.prod.com

// utils/config.js import.meta.env.VITE_API_BASE_URL export function getApiBaseUrl() { const platform = uni.getSystemInfoSync().platform; // 或者使用编译时注入的：const platform = __UNI_PLATFORM__; switch (platform) { case 'mp-weixin': // 微信小程序可能用特定接口 return import.meta.env.VITE_WX_API_BASE || import.meta.env.VITE_API_BASE_URL; case 'h5': return import.meta.env.VITE_H5_BASE_URL; case 'app': return import.meta.env.VITE_APP_BASE_URL; default: return import.meta.env.VITE_API_BASE_URL; } } export function getAppId() { const platform = uni.getSystemInfoSync().platform; if (platform === 'mp-weixin') { return import.meta.env.VITE_WX_APPID; } return ''; // 其他平台可能没有AppID概念 }

5.2 策略二：基于打包命令的动态加载（进阶）

如果你想为不同平台使用完全独立的环境文件，可以编写一个自定义的 Vite 插件或在构建脚本中动态处理。

思路：在运行打包命令前，通过 Node.js 脚本，根据UNI_PLATFORM和--mode参数，将对应的平台专属环境文件（如.env.production.mp-weixin）的内容复制或合并到.env.production中，然后再启动 Vite 构建。

// scripts/setup-env.js const fs = require('fs'); const path = require('path'); const mode = process.argv.find(arg => arg.startsWith('--mode'))?.split('=')[1] || process.env.NODE_ENV || 'production'; const platform = process.argv.find(arg => arg.startsWith('--platform'))?.split('=')[1] || process.env.UNI_PLATFORM; console.log(`准备环境: mode=${mode}, platform=${platform}`); const envFiles = [ `.env.${mode}.${platform}`, // 最高优先级：特定模式+平台 `.env.${mode}`, // 其次：特定模式 `.env` // 默认 ]; let finalEnvContent = ''; for (const file of envFiles) { const filePath = path.resolve(__dirname, `../${file}`); if (fs.existsSync(filePath)) { console.log(`加载环境文件: ${file}`); finalEnvContent += fs.readFileSync(filePath, 'utf8') + '\n'; } } // 将合并后的内容写入一个临时文件，或者直接传递给子进程 const targetPath = path.resolve(__dirname, `../.env.${mode}.temp`); fs.writeFileSync(targetPath, finalEnvContent); console.log(`环境文件已生成: .env.${mode}.temp`); // 设置环境变量，指示后续流程使用这个文件 process.env.VITE_USER_ENV_FILE = targetPath;

然后在vite.config.ts中，可以读取process.env.VITE_USER_ENV_FILE来加载这个合并后的文件。这种方式更彻底，但复杂度也更高，适合大型、平台差异非常明显的项目。

实操心得：对于大多数项目，策略一（环境变量内部分支）已经完全够用，且更易于理解和维护。策略二虽然清晰，但引入了额外的构建步骤和复杂度，除非必要，否则不建议轻易采用。

6. 常见问题、排查技巧与性能优化

即使配置正确，在实际开发和构建中，你仍可能会遇到一些棘手的问题。这里记录了几个我踩过的坑和解决方案。

6.1 问题一：环境变量在代码中显示为`undefined`

症状：在组件中打印import.meta.env.VITE_XXX，结果是undefined。

排查步骤：

检查变量名拼写：确保代码中的变量名与.env文件中的完全一致，包括VITE_前缀。这是最常见的原因。
确认环境文件已加载：检查你运行的 npm script 是否包含了正确的--mode参数。运行npm run build:h5和npm run build:production:h5加载的是不同的.env文件。
检查.env文件格式：确保文件是简单的KEY=VALUE格式，每行一个，VALUE不要加引号（除非值本身包含空格或特殊字符）。注释用#。
```
# 正确 VITE_API_URL=https://api.example.com # 错误（值带了不必要的引号，引号会成为值的一部分） VITE_API_URL="https://api.example.com"
```
检查 Vite 配置：如果你自定义了define配置，确保没有错误地覆盖或过滤掉了需要的变量。回退到最简单的配置测试。
清除缓存并重启：有时 Vite 的缓存会导致问题。尝试删除node_modules/.vite目录，并重启开发服务器或重新构建。

6.2 问题二：生产构建后，环境变量值没有正确替换

症状：开发时正常，但打包后，代码中还是process.env.VITE_XXX这样的字符串，而不是具体的值。

原因与解决：这通常是因为环境变量被用在了错误的地方。import.meta.env和define定义的变量只在Vite 构建阶段被静态替换。它们不能用于：

动态的键名：import.meta.env[key]（key是变量）是无法被替换的。
Node.js 运行时代码：例如在vite.config.ts中，你不能用import.meta.env.VITE_XXX，而应该用process.env.VITE_XXX或loadEnv函数的结果。

确保你在前端业务代码中，总是直接使用完整的变量名。

6.3 问题三：H5正常，但小程序或App报错

症状：环境变量在H5开发模式下工作良好，但在打包成小程序或App时，控制台报错process is not defined或import.meta is undefined。

原因：小程序和 App 的 JavaScript 运行环境与浏览器不同。虽然 uniapp 和 Vite 插件会做大量转换，但在使用define配置时如果处理不当，可能会引入不兼容的全局对象。

解决方案：

避免在define中直接使用process.env。如前文所述，使用__VITE_ENV__这样的自定义全局常量更安全。
确保你在vite.config.ts中正确引入了@dcloudio/vite-plugin-uni插件，它能处理很多平台兼容性问题。
在小程序开发者工具中，开启“详情”->“本地设置”->“调试基础库”下的“ES6转ES5”、“增强编译”等选项，有时能解决一些兼容性问题。

6.4 性能与安全优化建议

最小化暴露原则：只将前端代码必须知道的变量暴露给客户端（即以VITE_开头）。后端服务的密钥、数据库连接字符串等绝对不要放在这里。它们应该存在于服务器的环境变量或配置文件中。
类型安全：务必使用env.d.ts文件为ImportMetaEnv提供类型定义。这能在编码阶段就发现变量名错误，而不是等到运行时。
敏感信息处理：对于相对敏感但又前端必须使用的 Key（如地图 SDK Key），可以考虑通过后端接口动态下发，而不是硬编码在环境变量中。如果必须放在前端，确保其使用范围受到限制（如通过HTTP Referer、域名白名单等）。
环境文件管理：将.env.local、.env.*.local以及包含真实密钥的临时文件加入.gitignore。在团队协作中，可以提供一个.env.example或.env.template文件，列出所有需要的变量名但不包含具体值，供新成员参考。
构建速度：环境变量配置本身对构建速度影响微乎其微。但如果你发现vite build很慢，问题通常在于代码分割、图片优化、插件链等方面，与环境变量关系不大。