《Vue3 从入门到大神20篇》环境变量与跨域处理 —— Vite 的配置秘籍

前言

在本地开发时，你的接口请求可能是这样的：

复制代码

axios.get('http://192.168.1.100:8080/api/users')

但部署到生产环境后，后端地址变成了：

复制代码

https://api.example.com/api/users

如果你把 IP 和端口硬编码在代码里，那每次部署都要改代码------这显然是不可接受的。

同时，本地开发还会遇到另一个经典问题：

浏览器报跨域错误（CORS）

这两个问题，本质上都属于环境配置与构建工具的能力范畴。

在 Vue3 + Vite 体系中，它们有非常优雅的解决方案。

这一篇，我们把 .env环境变量、Vite Proxy 代理、多环境管理、部署注意事项 一次性讲透。

一、环境变量：让代码适应不同环境

1️⃣ Vite 的环境变量机制

Vite 使用 **import.meta.env** 来暴露环境变量：

复制代码

console.log(import.meta.env.VITE_API_BASE_URL)

📌 核心规则：

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

2️⃣ 创建环境文件

在项目根目录下创建：

复制代码

.env                # 所有环境共用
.env.development    # 开发环境
.env.production     # 生产环境
.env.staging        # 预发布环境（可选）

3️⃣ 文件内容示例

复制代码

# .env.development
VITE_API_BASE_URL=/api
VITE_APP_TITLE=Vue3 Demo (Dev)
VITE_UPLOAD_LIMIT=10

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=Vue3 Demo
VITE_UPLOAD_LIMIT=50

4️⃣ 在代码中使用

复制代码

// utils/request.ts
const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})

<script setup>
console.log(import.meta.env.VITE_APP_TITLE)
</script>

5️⃣ TypeScript 类型提示（进阶）

复制代码

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_UPLOAD_LIMIT: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

✅ IDE 自动补全 + 类型校验

二、模式（Mode）与环境切换

1️⃣ Vite 的默认模式

命令	默认模式	加载文件
`vite dev`	`development`	`.env.development`
`vite build`	`production`	`.env.production`

2️⃣ 自定义模式

复制代码

// package.json
{
  "scripts": {
    "dev": "vite --mode development",
    "build:staging": "vite build --mode staging",
    "build": "vite build --mode production"
  }
}

📌 --mode决定加载哪个 .env文件

三、跨域问题：为什么本地开发会跨域？

1️⃣ 跨域的本质

浏览器出于安全考虑，阻止了：

复制代码

前端：http://localhost:5173
后端：http://192.168.1.100:8080

❌ 协议 / 域名 / 端口任一不同，就是跨域

2️⃣ 常见解决方案对比

方案	适用场景	说明
CORS（后端配置）	生产环境	后端加响应头
JSONP	老旧系统	只支持 GET
Nginx 反向代理	生产环境	运维配置
Vite Proxy	开发环境	✅ 前端自行解决

📌 开发环境用 Vite Proxy，生产环境用 Nginx 或 CORS

四、Vite Proxy 代理配置（重点）

1️⃣ 基础配置

复制代码

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://192.168.1.100:8080',
        changeOrigin: true
      }
    }
  }
})

📌 效果：

前端请求 /api/users
Vite 转发到 http://192.168.1.100:8080/api/users
浏览器只和 localhost 通信，不存在跨域

2️⃣ 路径重写

复制代码

proxy: {
  '/api': {
    target: 'http://192.168.1.100:8080',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, '')
  }
}

📌 请求 /api/users→ 转发到 http://.../users

3️⃣ 多个代理目标

复制代码

proxy: {
  '/api': {
    target: 'http://backend:8080',
    changeOrigin: true
  },
  '/upload': {
    target: 'http://file-server:9000',
    changeOrigin: true
  }
}

4️⃣ WebSocket 代理

复制代码

proxy: {
  '/ws': {
    target: 'ws://localhost:3000',
    ws: true,
    changeOrigin: true
  }
}

五、生产环境的跨域处理

1️⃣ Nginx 反向代理（推荐 ✅）

复制代码

server {
    listen 80;
    server_name example.com;

    location / {
        root /var/www/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📌 前端和后端在同一域名下，不存在跨域

2️⃣ 后端 CORS 配置

复制代码

// Node.js / Express 示例
app.use(cors({
  origin: ['https://example.com'],
  credentials: true
}))

六、环境变量安全注意事项

⚠️ 重要：前端环境变量是公开的

复制代码

VITE_API_BASE_URL=https://api.example.com  # ✅ 公开，没问题
VITE_SECRET_KEY=abc123                     # ❌ 密钥不能放前端！

📌 前端代码中不能放任何敏感信息：

数据库密码
JWT 签名密钥
私钥

✅ 敏感信息只能放在后端

七、部署时的常见问题

❌ 问题 1：刷新页面 404

原因：SPA 的路由是前端控制的，服务器不认识 /user这个路径

解决：Nginx 配置 try_files

复制代码

location / {
    try_files $uri $uri/ /index.html;
}

❌ 问题 2：API 请求打到前端服务器

原因：生产环境 baseURL配成了相对路径 /api，但没有代理

解决：生产环境用绝对路径或 Nginx 代理

❌ 问题 3：环境变量不生效

原因：变量名没有 VITE_前缀

解决：检查 .env文件和变量名

八、完整的 vite.config.ts 示例

复制代码

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

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

  return {
    plugins: [vue()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    server: {
      port: 5173,
      open: true,
      proxy: {
        '/api': {
          target: env.VITE_PROXY_TARGET || 'http://localhost:8080',
          changeOrigin: true,
          rewrite: (p) => p.replace(/^\/api/, '')
        }
      }
    },
    build: {
      outDir: 'dist',
      sourcemap: mode !== 'production',
      rollupOptions: {
        output: {
          chunkFileNames: 'assets/js/[name]-[hash].js',
          entryFileNames: 'assets/js/[name]-[hash].js',
          assetFileNames: 'assets/[ext]/[name]-[hash].[ext]'
        }
      }
    }
  }
})

九、面试高频问答

Q1：Vite 中环境变量为什么必须以 VITE_ 开头？

防止意外将敏感环境变量暴露到客户端代码中。

Q2：Vite Proxy 在生产环境能用吗？

不能，Vite Proxy 只在开发服务器生效，生产环境用 Nginx。

Q3：SPA 部署后刷新 404 怎么解决？

服务器配置 fallback 到 index.html（Nginx 的 try_files）。

十、总结（架构级）

.env文件管理不同环境的配置
VITE_前缀控制变量暴露
Vite Proxy 解决开发环境跨域
生产环境用 Nginx 反向代理
前端环境变量是公开的，不能放敏感信息

📢 下期预告

👉 第 21 篇：Vue3 性能优化九大策略