环境配置

了解如何配置不同环境的变量和参数。

环境文件

项目使用 .env 文件管理不同环境的配置：

.env.development    # 开发环境
.env.production     # 生产环境

开发环境配置

.env.development 文件配置示例：

bash

# 应用端口
VITE_APP_PORT=3000

# 项目名称
VITE_APP_TITLE=vue3-element-admin

# 代理前缀
VITE_APP_BASE_API=/dev-api

# 接口地址
VITE_APP_API_URL=https://api.youlai.tech  # 线上接口
# VITE_APP_API_URL=http://localhost:8989    # 本地接口

# WebSocket 端点（不配置则关闭）
# 线上: ws://api.youlai.tech/ws
# 本地: ws://localhost:8989/ws
VITE_APP_WS_ENDPOINT=

# 启用 Mock 服务
VITE_MOCK_DEV_SERVER=false

生产环境配置

.env.production 文件配置示例：

bash

# 代理前缀
VITE_APP_BASE_API=/prod-api

# 项目名称
VITE_APP_TITLE=vue3-element-admin

# WebSocket端点（可选）
#VITE_APP_WS_ENDPOINT=wss://api.youlai.tech/ws

生产环境说明

生产环境不需要配置 VITE_APP_API_URL，接口请求通过 Nginx 反向代理实现。只需配置 VITE_APP_BASE_API 作为代理前缀即可。

环境变量说明

变量名	说明	类型	默认值	适用环境
`VITE_APP_PORT`	应用端口	`number`	`3000`	开发
`VITE_APP_TITLE`	项目名称	`string`	-	全部
`VITE_APP_BASE_API`	API 代理前缀	`string`	`/dev-api` / `/prod-api`	全部
`VITE_APP_API_URL`	API 接口地址	`string`	-	仅开发
`VITE_APP_WS_ENDPOINT`	WebSocket 端点	`string`	-	全部（可选）
`VITE_MOCK_DEV_SERVER`	是否开启 Mock	`boolean`	`false`	仅开发

使用环境变量

在代码中使用

typescript

// 获取代理前缀
const baseAPI = import.meta.env.VITE_APP_BASE_API

// 获取 API 地址（仅开发环境）
const apiUrl = import.meta.env.VITE_APP_API_URL

// 获取项目名称
const title = import.meta.env.VITE_APP_TITLE

// 获取 WebSocket 端点
const wsEndpoint = import.meta.env.VITE_APP_WS_ENDPOINT

// 判断是否开启 Mock
if (import.meta.env.VITE_MOCK_DEV_SERVER === 'true') {
  // Mock 相关逻辑
}

在 HTML 中使用

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <title>%VITE_APP_TITLE%</title>
</head>
</html>

代理配置

在 vite.config.ts 中配置开发环境代理：

typescript

export default defineConfig({
  server: {
    port: Number(env.VITE_APP_PORT) || 3000,
    proxy: {
      // 代理前缀为 /dev-api 的请求
      [env.VITE_APP_BASE_API]: {
        target: env.VITE_APP_API_URL,  // 目标接口地址
        changeOrigin: true,
        rewrite: (path) => path.replace(new RegExp(`^${env.VITE_APP_BASE_API}`), '')
      }
    }
  }
})

代理原理

开发环境：请求 /dev-api/user/info → Vite 代理 → https://api.youlai.tech/user/info
生产环境：请求 /prod-api/user/info → Nginx 代理 → 后端服务

Nginx 生产环境配置

生产环境通过 Nginx 反向代理处理 API 请求：

nginx

server {
    listen 80;
    server_name yourdomain.com;

    # 前端静态资源
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /prod-api/ {
        proxy_pass http://backend-server:8080/;  # 后端服务地址
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # WebSocket 代理（可选）
    location /prod-api/ws {
        proxy_pass http://backend-server:8080/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

重要提示

生产环境构建时，前端代码中的 /prod-api 会被保留，由 Nginx 进行代理转发，因此不需要在 .env.production 中配置 VITE_APP_API_URL。

切换接口环境

开发环境可以灵活切换不同的接口环境。

使用在线接口（默认）

bash

# .env.development
VITE_APP_API_URL=https://api.youlai.tech
VITE_MOCK_DEV_SERVER=false

使用本地接口

bash

# .env.development
VITE_APP_API_URL=http://localhost:8989
VITE_MOCK_DEV_SERVER=false

使用 Mock 接口

bash

# .env.development
VITE_MOCK_DEV_SERVER=true

接口环境切换

在线接口：使用线上已部署的后端服务，适合前端独立开发
本地接口：使用本地启动的后端服务，适合前后端联调
Mock 接口：使用前端 Mock 数据，适合后端接口未就绪时开发

环境判断

typescript

// 判断是否为开发环境
if (import.meta.env.DEV) {
  console.log('开发环境')
}

// 判断是否为生产环境
if (import.meta.env.PROD) {
  console.log('生产环境')
}

// 获取环境模式
console.log(import.meta.env.MODE) // 'development' 或 'production'

注意事项

1. 环境变量前缀

只有以 VITE_ 开头的变量才会暴露给客户端代码。

bash

# ✅ 可以访问
VITE_APP_TITLE=vue3-element-admin

# ❌ 无法访问（没有 VITE_ 前缀）
APP_SECRET=my-secret-key

2. 类型转换

环境变量始终是字符串类型，需要手动转换：

typescript

// ❌ 错误 - 得到字符串 '3000'
const port = import.meta.env.VITE_APP_PORT

// ✅ 正确 - 转换为数字 3000
const port = Number(import.meta.env.VITE_APP_PORT)

// ❌ 错误 - 字符串 'false' 也是 truthy
if (import.meta.env.VITE_MOCK_DEV_SERVER) {
  // 总是会执行
}

// ✅ 正确 - 使用字符串比较
if (import.meta.env.VITE_MOCK_DEV_SERVER === 'true') {
  // 只有值为 'true' 时才执行
}

3. 生产环境配置

不要在 .env.production 中配置 VITE_APP_API_URL
生产环境的 API 请求通过 Nginx 代理实现
只需配置 VITE_APP_BASE_API 作为请求前缀

4. 敏感信息

不要在环境变量中存储敏感信息（如密钥、密码等），这些信息会暴露在客户端代码中。

5. 修改后重启

修改 .env 文件后，需要重启开发服务器才能生效。

bash

# 停止服务器（Ctrl+C），然后重新启动
npm run dev

TypeScript 支持

在 src/types/env.d.ts 中定义环境变量类型：

typescript

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_APP_PORT: string
  readonly VITE_APP_BASE_API: string
  readonly VITE_APP_API_URL: string
  readonly VITE_APP_WS_ENDPOINT: string
  readonly VITE_MOCK_DEV_SERVER: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

环境配置 ​

环境文件 ​

开发环境配置 ​

生产环境配置 ​

环境变量说明 ​

使用环境变量 ​

在代码中使用 ​

在 HTML 中使用 ​

代理配置 ​

Nginx 生产环境配置 ​

切换接口环境 ​

使用在线接口（默认） ​

使用本地接口 ​

使用 Mock 接口 ​

环境判断 ​

注意事项 ​

1. 环境变量前缀 ​

2. 类型转换 ​

3. 生产环境配置 ​

4. 敏感信息 ​

5. 修改后重启 ​

TypeScript 支持 ​

相关链接 ​

环境配置

环境文件

开发环境配置

生产环境配置

环境变量说明

使用环境变量

在代码中使用

在 HTML 中使用

代理配置

Nginx 生产环境配置

切换接口环境

使用在线接口（默认）

使用本地接口

使用 Mock 接口

环境判断

注意事项

1. 环境变量前缀

2. 类型转换

3. 生产环境配置

4. 敏感信息

5. 修改后重启

TypeScript 支持

相关链接