小蚂蚁云

Appearance

Become a sponsor
企业级中台解决方案
企业级中台解决方案

9.3 环境与构建配置 ​

概述

本节说明前端项目的环境变量配置和 Vite 构建配置，包括开发环境和生产环境的差异配置。前端通过 .env 文件管理环境变量，Vite 自动根据模式加载对应的 .env 文件。

环境变量文件 ​

text
ui/
├── .env                    # 所有环境通用配置
├── .env.development        # 开发环境配置
├── .env.production         # 生产环境配置
└── .env.local              # 本地覆盖（不提交 git）

加载优先级： .env.local > .env.{mode} > .env

开发环境配置 ​

.env.development ​

bash
# 开发服务器端口
VITE_PORT = 8001

# 公共基础路径（通常为 /）
VITE_PUBLIC_PATH = /

# API 接口基础路径（留空，由代理处理）
VITE_GLOB_API_URL =

# API 前缀（所有接口路径的前缀）
VITE_GLOB_API_URL_PREFIX = /api

# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]

# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload

# 图片访问地址（用于预览上传的图片）
VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue

# 是否在生产环境删除 console（开发环境保留）
VITE_DROP_CONSOLE = false

# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK = false

生产环境配置 ​

.env.production ​

bash
# 公共基础路径（通常为 /，如部署到子目录则设为 /subdir/）
VITE_PUBLIC_PATH = /

# API 接口基础路径（留空，由 Nginx 代理处理）
VITE_GLOB_API_URL =

# API 前缀
VITE_GLOB_API_URL_PREFIX = /api

# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload

# 图片访问地址（生产环境使用正式域名）
VITE_GLOB_IMG_URL = https://cdn.example.com

# 是否在生产环境删除 console
VITE_DROP_CONSOLE = true

# 是否启用 gzip 压缩
VITE_BUILD_COMPRESS = gzip

# 压缩后是否删除原文件
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false

环境变量详解 ​

VITE_PORT — 开发服务器端口 ​

bash
VITE_PORT = 8001
环境值说明
开发8001前端开发服务器端口
生产不生效生产环境由 Nginx 提供服务

VITE_PUBLIC_PATH — 公共基础路径 ​

bash
VITE_PUBLIC_PATH = /
场景值说明
根目录部署/默认值
子目录部署/admin/如 https://example.com/admin/

VITE_GLOB_API_URL — API 基础路径 ​

bash
VITE_GLOB_API_URL =
场景值说明
开发（代理）留空由 Vite proxy 转发
生产（同域）留空由 Nginx 代理
生产（跨域）https://api.example.com直接请求后端域名

VITE_PROXY — 开发代理配置 ​

bash
VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]

格式： JSON 数组，每项为 [前缀, 目标地址]

作用： 将前端 /api/* 请求代理到后端地址，解决开发环境跨域问题。

多代理示例：

bash
VITE_PROXY = [["/api","http://localhost:8080/api"],["/upload","http://localhost:8080/upload"]]

VITE_GLOB_API_URL_PREFIX — API 前缀 ​

bash
VITE_GLOB_API_URL_PREFIX = /api

所有 API 请求路径的前缀，与后端路由前缀一致。

VITE_GLOB_UPLOAD_URL — 上传接口地址 ​

bash
VITE_GLOB_UPLOAD_URL = /api/upload

文件上传组件使用的接口地址。

VITE_GLOB_IMG_URL — 图片访问地址 ​

bash
# 开发环境
VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue

# 生产环境
VITE_GLOB_IMG_URL = https://cdn.example.com

用于预览上传的图片，拼接图片的完整 URL。

VITE_DROP_CONSOLE — 删除 console ​

bash
# 开发环境：保留 console（方便调试）
VITE_DROP_CONSOLE = false

# 生产环境：删除 console（安全+减小体积）
VITE_DROP_CONSOLE = true

VITE_BUILD_COMPRESS — Gzip 压缩 ​

bash
VITE_BUILD_COMPRESS = gzip

启用 gzip 压缩后，构建产物会生成 .gz 文件，Nginx 配置 gzip_static on 可直接使用。

在代码中访问环境变量 ​

typescript
// 读取环境变量（VITE_ 前缀的变量才会暴露给客户端）
const apiUrl = import.meta.env.VITE_GLOB_API_URL;
const apiPrefix = import.meta.env.VITE_GLOB_API_URL_PREFIX;
const uploadUrl = import.meta.env.VITE_GLOB_UPLOAD_URL;
const imgUrl = import.meta.env.VITE_GLOB_IMG_URL;

// 完整 API 地址
const fullApiUrl = apiUrl + apiPrefix;  // 如 "/api" 或 "https://api.example.com/api"

VITE_ 前缀

只有以 VITE_ 开头的环境变量才会暴露给客户端代码，其他变量（如 PORT）不会被访问到。

Vite 配置 ​

vite.config.ts ​

typescript
import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  // 加载环境变量
  const env = loadEnv(mode, process.cwd());

  return {
    // 开发服务器
    server: {
      port: Number(env.VITE_PORT) || 8001,
      proxy: {
        '/api': {
          target: 'http://admin.thinkphp6.elevue/api',
          changeOrigin: true,
        },
      },
    },

    // 构建配置
    build: {
      // 生产环境删除 console
      drop: env.VITE_DROP_CONSOLE === 'true' ? ['console', 'debugger'] : [],
      // 启用 gzip 压缩
      rollupOptions: {
        output: {
          manualChunks: {
            vue: ['vue', 'vue-router', 'pinia'],
            element: ['element-plus'],
          },
        },
      },
    },
  };
});

代理配置详解 ​

typescript
// 开发环境代理配置
server: {
  proxy: {
    '/api': {
      target: 'http://admin.thinkphp6.elevue/api',  // 目标地址
      changeOrigin: true,                            // 修改请求头 Origin
      rewrite: (path) => path.replace(/^\/api/, ''), // 路径重写（可选）
    },
  },
}

代理效果：

text
前端请求: GET /api/user/page
    │
    ▼ Vite proxy
    │
    ▼ 转发到: http://admin.thinkphp6.elevue/api/user/page

构建命令 ​

bash
# 开发服务器（热更新）
pnpm dev

# 构建生产版本
pnpm build

# 预览构建结果（本地启动静态服务器）
pnpm preview

# ESLint 检查
pnpm lint:eslint

# ESLint 自动修复
pnpm lint:eslint --fix

# TypeScript 类型检查
pnpm type:check

构建产物 ​

text
ui/dist/
├── index.html              # 入口文件
├── assets/
│   ├── index-xxx.js        # 主 JS（带 hash）
│   ├── index-xxx.css       # 主 CSS（带 hash）
│   ├── vue-xxx.js          # Vue 相关（分包）
│   └── element-xxx.js      # Element Plus（分包）
├── favicon.ico
└── static/                 # 静态资源

部署配置 ​

Nginx 配置 ​

nginx
server {
    listen 80;
    server_name admin.example.com;

    # 前端静态文件
    root /data/www/admin/dist;
    index index.html;

    # SPA 路由（所有非文件请求都返回 index.html）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理到后端
    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 静态资源缓存
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_static on;  # 优先使用 .gz 文件
    gzip_types text/css application/javascript application/json;
}

多环境配置 ​

测试环境 ​

bash
# .env.staging
VITE_GLOB_API_URL =
VITE_GLOB_API_URL_PREFIX = /api
VITE_GLOB_IMG_URL = https://test-cdn.example.com
VITE_DROP_CONSOLE = true

构建命令：

bash
pnpm build --mode staging

环境变量对照表 ​

变量开发测试生产
VITE_PORT8001--
VITE_GLOB_API_URL留空留空留空
VITE_GLOB_API_URL_PREFIX/api/api/api
VITE_GLOB_IMG_URLhttp://file.xxxhttps://test-cdn.xxxhttps://cdn.xxx
VITE_DROP_CONSOLEfalsetruetrue
VITE_USE_MOCKfalsefalsefalse

常见问题 ​

问题 1：开发环境 API 请求 404 ​

原因： 代理配置错误或后端未启动。

解决： 检查 .env.development 中 VITE_PROXY 的目标地址是否正确。

问题 2：生产环境 API 请求跨域 ​

原因： VITE_GLOB_API_URL 配置了跨域地址但后端未配置 CORS。

解决： 推荐留空，由 Nginx 代理处理（同域无跨域问题）。

问题 3：图片不显示 ​

原因： VITE_GLOB_IMG_URL 配置错误。

解决： 检查图片访问地址是否正确，确保图片 URL 可直接访问。

问题 4：构建后体积过大 ​

原因： 未启用 gzip 压缩或未分包。

解决： 启用 VITE_BUILD_COMPRESS = gzip，配置 manualChunks 分包。

小蚂蚁云团队 · 提供技术支持

Copyright © 2018~2026 www.rxthink.cn. All rights reserved.