vue3.x教程-.env环境变量配置文件（.env.development、.env.production）

作者：马育民 • • 阅读：10110

介绍

通过环境变量传参，可以在不修改代码的情况下，加载不同的配置

作用

环境文件（.env系列）本质是一套多环境配置管理方案

  1. 区分运行模式：开发、测试、正式环境，一套代码，不同配置
  2. 集中管理常量：接口地址、页面标题、功能开关、第三方key统一放文件，不用到处改代码
  3. 隔离公私配置：公共配置提交git；本地私有配置（.local）不上传git，每个人本机可自定义
  4. 避免硬编码：不要把接口地址写死在业务代码，改环境文件即可切换环境
  5. 配合打包脚本：执行不同命令自动加载对应配置，不用手动改代码

底层原理

Vite构建时读取.env文件，把VITE_*变量静态替换进代码，打包后变成真实字符串。

应用场景

场景1：多环境接口地址切换（最常用）

前后端开发联调、测试服务器、线上正式服务器 接口地址不一样

  • 开发环境：http://127.0.0.1:8080
  • 测试环境：https://api-test.xxx.com
  • 生产环境：https://api.xxx.com

场景2：功能开关控制

不同环境开启/关闭某些功能

  • 开发开启打印日志
  • 显示调试面板
  • 开启mock模拟数据

场景3：页面标题、项目版本、版权信息

不同环境展示不同标题，区分环境方便测试人员识别当前是哪个包

场景5：自定义测试环境 build:test

后端有一套独立测试服务器，需要打测试包给测试人员，不改动正式环境配置。

场景6：本地开发人员个性化配置

工程师A本地后端端口是8081，工程师B是8082。

场景7：第三方前端公共密钥配置

前端可暴露的key（如地图AK、埋点id），放到环境变量统一管理。

注意： 不要放后端密钥、数据库密码

不该用环境文件的情况

  1. 后端密钥、数据库密码、token密钥：禁止，因为前端会泄露。这类配置放在后端服务。

  2. 运行时动态变化的参数：比如用户登录后获取的用户配置，不要写环境变量。env是构建期确定，打包完成后不能修改。

环境文件

Vite 会自动读取 项目根目录 下以 .env 开头的文件：

文件名 生效时机 说明
.env 所有环境，全局默认 所有模式都会加载，优先级最低
.env.local 所有环境，本地 git忽略，本机个人配置，不提交代码
.env.development development 开发模式 npm run dev 默认加载
.env.development.local 开发模式，本地 开发环境本机私有配置，不提交
.env.production production 生产模式 npm run build 默认加载
.env.production.local 生产模式，本地 生产打包本机私有配置，不提交

加载优先级（后面覆盖前面）

.env → .env.[mode] → .env.[mode].local

.local 文件永远不会被git提交，适合放密钥、本地特殊地址。

变量命名规则

只有以 VITE_ 开头的变量，才可以在前端代码 import.meta.env 访问

# ✅ 前端可以读到
VITE_API_BASE_URL = "https://api.dev.com"

# ❌ 不带VITE_，仅vite配置文件能读到，业务js/ts读不到
API_SECRET = "xxx"

语法规则

规则1

等号两边可以有空格；值不要加引号，Vite会自动处理，加引号会把引号当成字符串一部分

正确
VITE_API_URL=https://api.test.com
错误

值不能带双引号

VITE_API_URL="https://api.test.com"

注释

注释用 #，必须单独一行，不能写在行尾后面（部分版本会把行尾#当作值）

# 接口地址
VITE_API_URL=https://api.test.com

例子

在工程根目录下创建：.env.development 文件，这是开发环境，内容如下：

# .env.development 开发环境
VITE_ENV = development
# html标题
VITE_APP_TITLE = XXX管理系统-开发环境
# 设置代理，发送到后端api接口
VITE_API_BASE_URL = http://127.0.0.1:8080
VITE_SHOW_DEBUG = true

在工程根目录下创建：.env.production 文件，这是生产环境，内容如下：

# .env.production 生产环境
VITE_ENV = production
# html标题
VITE_APP_TITLE = XXX管理系统
# 设置代理，发送到后端api接口
VITE_API_BASE_URL = https://api.prod.com
VITE_SHOW_DEBUG = false

代码中使用环境变量

1. index.html 使用环境变量

使用 %变量名%，如：使用环境变量中的标题：

<title>%VITE_APP_TITLE%</title>

2. vue组件 / ts/js业务代码

// 获取环境变量
const baseUrl = import.meta.env.VITE_API_BASE_URL
console.log(import.meta.env.VITE_ENV)

// 内置环境变量（Vite自带，不需要自己写.env）
import.meta.env.DEV      // boolean，是否开发环境 npm run dev
import.meta.env.PROD     // boolean，是否生产环境 npm run build
import.meta.env.MODE     // 当前模式字符串 development / production

vue模板中直接使用：

<template>
  <div>{{ import.meta.env.VITE_APP_TITLE }}</div>
</template>

3. vite.config.ts 读取环境变量

vite配置文件属于node环境，不能直接用 import.meta.env，需要用 loadEnv API

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 第二个参数：项目根目录
  const env = loadEnv(mode, process.cwd(), '')
  console.log(env.VITE_API_BASE_URL)
  return {
    server:{
      proxy:{
        '/api':{
          target: env.VITE_API_BASE_URL
        }
      }
    }
  }
})

常见坑点

  1. ❌ 变量名不加 VITE_，前端代码读不到，只有vite配置能拿到
  2. ❌ 环境文件放错位置：必须根目录，不是src下面
  3. ❌ 变量值加双引号，运行后字符串自带引号
  4. ❌ 修改.env后没有重启vite服务，环境变量不会刷新
  5. ❌ .env.local写了变量，git不会提交，团队其他人拿不到，公共配置不要放local
  6. ❌ 不要把密钥、后端密码放到 VITE_* 变量！所有VITE_开头变量打包后暴露在前端，任何人F12可以查看。密钥只能放vite配置/node层，不能暴露给浏览器。

提示：.env.local建议加到.gitignore

.env.local
.env.*.local
吉ICP备15003043号