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

# 介绍

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

### 作用

环境文件（`.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` 访问**

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

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

# 语法规则

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

##### 正确

```env
VITE_API_URL=https://api.test.com
```

##### 错误

值不能带双引号

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

### 注释

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

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

### 例子

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

```env
# .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
# .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业务代码
```ts
// 获取环境变量
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模板中直接使用：
```vue
<template>
  <div>{{ import.meta.env.VITE_APP_TITLE }}</div>
</template>
```

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

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

```ts
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`
```gitignore
.env.local
.env.*.local
```

原文出处：/show_1GW3ooz9YN0K.html