Vite 配置与环境变量

学习目标

Vite 是 Vue 3 的标准构建工具，但「默认能跑」和「配置得当」是两回事。这一节掌握 vite.config.js 的关键项、环境变量的三种文件与使用规则、代理解决开发期跨域，以及 ESLint 与格式化工具的接入。

问题场景

本地开发时接口在 http://localhost:8080，上线后是 https://api.example.com。你把地址硬编码在一个 api.js 里，部署前手动改——某次忘了改，线上请求打到 localhost。另一个问题：开发环境直接请求后端 8080 端口被 CORS 拦，你给后端加了一堆 Access-Control-Allow-Origin，其实前端代理一行配置就能解决。

核心解释

环境变量：Vite 用 .env 系列文件，只有 VITE_ 前缀的变量才会暴露给客户端：

# .env                （所有模式共享）
VITE_APP_TITLE=我的学习站

# .env.development    （npm run dev 时加载）
VITE_API_BASE=/api

# .env.production     （npm run build 时加载）
VITE_API_BASE=https://api.example.com

代码里用 import.meta.env.VITE_API_BASE 读取。命名前缀是安全边界：不带 VITE_ 的变量不会打进客户端包，适合放密钥类配置（但前端项目里本来就不该有真正的密钥）。

开发期代理：server.proxy 把 /api 转发到后端，浏览器看到的同源请求，CORS 问题消失：

// vite.config.js
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: { "@": "/src" },
  },
  server: {
    port: 5173,
    proxy: {
      "/api": {
        target: "http://localhost:8080",
        changeOrigin: true,
      },
    },
  },
  build: {
    outDir: "dist",
    sourcemap: false,
  },
});

alias 让 import 路径可读：import { api } from "@/lib/api" 代替 ../../lib/api。记得同步 jsconfig.json/tsconfig.json 的 paths，编辑器才能跳转。

模式（mode）：vite build --mode staging 会加载 .env.staging。多环境部署时用模式而不是复制配置。import.meta.env.PROD / DEV / MODE 是内置变量。

ESLint：create-vue 可选内置。Vue 官方推荐 flat config（eslint.config.js）配 eslint-plugin-vue：

// eslint.config.js
import pluginVue from "eslint-plugin-vue";

export default [
  ...pluginVue.configs["flat/recommended"],
  {
    rules: {
      "vue/multi-word-component-names": "off",
    },
  },
];

配合 Prettier 时注意「谁管格式」：ESLint 管代码质量，Prettier 管格式，用 eslint-config-prettier 关闭冲突规则，避免两套工具打架。

示例拆解

一个完整的 API 客户端，把环境变量、类型声明、错误处理串起来：

// src/lib/api.ts
const BASE = import.meta.env.VITE_API_BASE ?? "";

export async function apiGet<T>(path: string, { signal }: { signal?: AbortSignal } = {}): Promise<T> {
  const res = await fetch(`${BASE}${path}`, { signal });
  if (!res.ok) {
    throw new Error(`请求失败：HTTP ${res.status}`);
  }
  return res.json();
}

// src/env.d.ts：给自定义环境变量补类型，拼错变量名会报错
/// <reference types="vite/client" />
interface ImportMetaEnv {
  readonly VITE_API_BASE: string;
  readonly VITE_APP_TITLE?: string;
}
interface ImportMeta {
  readonly env: ImportMetaEnv;
}

验证环境变量生效：npm run dev 时打印 import.meta.env.VITE_API_BASE 应为 /api；npm run build 后到 dist/assets/*.js 里搜 api.example.com 应该能搜到（证明生产值被打包），搜 /api 出现在开发包而不是生产包。

动手任务

1. 建 .env.development / .env.production 两个文件，用 import.meta.env 区分接口地址，并在页面上显示当前模式。
2. 配置 /api 代理指向一个本地 mock 服务（可用 node -e 起一个简单 HTTP 服务），验证跨域消失。
3. 接入 ESLint flat config，故意写一个未使用变量，确认 npm run lint 报错。

常见错误

• 变量没写 VITE_ 前缀：import.meta.env.API_BASE 永远是 undefined，且不会报错。
• 把密钥写进 VITE_ 变量：会打进客户端包，任何人可读。密钥必须放服务端。
• 改了 .env 不重启开发服务器：环境变量在启动时读取，需要重启 dev server。
• alias 只配了 Vite 没配 tsconfig：构建能过，编辑器红线不断。

检查与复盘

• 能写出三种环境变量文件并说明加载顺序
• 能配置开发代理并解释它和 CORS 的关系
• 能说出 VITE_ 前缀的安全含义

参考资料

• Vite 官方文档「环境变量与模式」：加载规则
• Vite 官方文档「配置」：server.proxy 与 resolve.alias
• Vue 官方文档「工具链」：官方推荐的工具组合