彻底弄懂了Vite中的环境变量和模式

环境变量

Vite 在一个特殊的import.meta.env对象中提供了一些环境变量。这个对象中有一些在所有情况下都可以使用的内建变量：

import.meta.env.MODE：{string} 应用运行的模式。
import.meta.env.BASE_URL: {string} 部署应用时的基本 URL。他由 base 配置项决定。
import.meta.env.PROD: {boolean} 应用是否运行在生产环境。
import.meta.env.DEV: {boolean} 应用是否运行在开发环境 (永远与 import.meta.env.PROD 相反)。
import.meta.env.SSR: {boolean} 应用是否运行在 server 上。

生产环境替换

在生产环境中，这些环境变量会在构建时被静态替换，因此，在引用它们时请使用完全静态的字符串。动态的 key 将无法生效。

// ❌ 错误
const key = 'VITE_API_URL';
console.log(import.meta.env[key]); // 无法正常工作！

// ✅ 正确（静态访问）
console.log(import.meta.env.VITE_API_URL);

.env文件

Vite可以在.env文件中配置环境变量。

环境变量文件类型

Vite 支持以下类型的 .env 文件，按 优先级从高到低 排序：

解释

• .env.[mode].local：特定模式的本地覆盖文件，适用于特定环境的本地配置，不会被 Git 忽略。
• .env.local：通用的本地覆盖文件，适用于所有模式的本地配置，不会被 Git 忽略。
• .env.[mode]：特定模式的配置文件，适用于特定环境的配置，会被 Git 忽略。
• .env：通用的配置文件，适用于所有模式的配置，会被 Git 忽略。
• 加载顺序：按照优先级由高到低依次加载
• 覆盖规则：同名的环境变量会被更高优先级的文件覆盖，不同名的环境变量会合并。
  通过这种方式，你可以更好地管理不同环境下的配置，并确保敏感信息不会被意外提交到版本控制系统中。

示例文件 .env.development：

# 客户端可访问的变量（必须以 VITE_ 开头）
VITE_APP_API_BASEURL=/api
VITE_APP_TITLE=Vite + React + Ts (development)
VITE_DEBUG=true

# 服务端专用变量（非 VITE_ 前缀，仅在 Node.js 中通过 process.env 访问）
SECRET_KEY=123456

场景 1：运行 vite dev（默认 development 模式）
加载顺序：

1. .env.development.local（如果存在）

2. .env.development

3. .env.local

4. .env

场景 2：运行 vite build --mode staging
加载顺序：

1. .env.staging.local（如果存在）

2. .env.staging

3. .env.local

4. .env

在代码中访问环境变量
通过 import.meta.env 访问以 VITE_ 开头的变量：

// 访问环境变量
const apiUrl= import.meta.env.VITE_APP_API_BASEURL
const isDebug = import.meta.env.VITE_DEBUG;

console.log(`API 地址：${apiUrl}`); // 输出：http://localhost:3000/api
console.log(`调试模式：${isDebug}`); // 输出：true（注意：这里得到的是字符串 "true"，不是布尔值）

环境变量的类型处理
环境变量的值始终是字符串类型。如果需要其他类型，需手动转换：

类型转换示例：

// 转换为布尔值
const isDebug = import.meta.env.VITE_DEBUG === 'true'; 

模式（Mode）与构建命令
Vite 通过 --mode 参数指定模式，默认模式为：

• development：vite dev 或 vite serve
• production：vite build

自定义模式：

# 使用 staging 模式
vite build --mode staging

此时 Vite 会加载 .env.staging 文件。

在 TypeScript 中添加类型提示
在 TypeScript 项目中，扩展 ImportMetaEnv 接口以避免类型错误：

步骤：
在vite-env.d.ts文件中添加类型定义：

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

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_DEBUG: string;
  // 添加其他自定义环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

代码中访问时会有自动补全和类型检查：

const apiUrl: string = import.meta.env.VITE_API_URL; // 类型安全

image.png

2.服务端环境变量
非 VITE_ 前缀的变量只能在 Node.js 中通过 process.env 访问：

// vite.config.js
export default defineConfig(({ mode }) => {
  const secretKey = process.env.SECRET_KEY; // 来自 .env 文件或系统环境变量
  return {
    // 配置...
  };
});

注意事项

• 敏感信息：不要将密码、密钥等敏感信息以 VITE_ 前缀暴露给客户端。
• 重启服务：修改 .env 文件后需重启开发服务器。
• 生产部署：生产环境变量应通过服务器环境（如 Docker、Kubernetes）注入，而非硬编码在文件中。

模式
默认情况下，开发服务器 (dev 命令) 运行在 development (开发) 模式，而 build 命令则运行在 production (生产) 模式。
当运行对应命令时会自动加载对用的.env文件。

Vite 内置的两种默认模式
Vite 内置了两种默认模式，无需额外配置即可使用。以下是这两种模式的详细说明：

1. development 模式
触发条件：

• 运行 vite dev 或 vite serve。
  行为：

• 启动开发服务器：提供实时预览和调试功能。

• 加载环境变量：自动加载 .env.development 和 .env.local 文件中的环境变量。

• 启用热更新（HMR）：修改代码后自动刷新相关模块，提升开发效率。

• 未压缩代码：生成未压缩的代码文件，便于调试。

• 完整的 Source Map：生成详细的源码映射文件，方便调试时追踪错误。
  典型场景：

• 本地开发调试：适用于开发者在本地环境中进行代码编写和测试。
  2. production 模式
  触发条件：

• 运行 vite build。
  行为：

• 执行生产构建：生成优化后的静态资源文件，用于部署到生产环境。

• 加载环境变量：自动加载 .env.production 和 .env.local 文件中的环境变量。

• 代码压缩：对生成的 JavaScript 和 CSS 文件进行压缩，减小文件体积。

• Tree Shaking：移除未使用的代码，减少最终包的大小。

• 优化资源输出：对静态资源进行优化处理，如图片压缩、字体优化等。
  典型场景：

• 部署到线上生产环境：适用于将应用打包并部署到生产服务器或 CDN。

通过这两种模式，Vite 提供了简洁而强大的工具链，帮助开发者在不同阶段高效地管理和优化项目。

3. 自定义模式
通过 --mode 参数可指定任意自定义模式，适合多环境需求（如测试、预发布）。

示例：创建 staging 模式

为了在 Vite 项目中添加一个预发布环境（staging），你需要定义相应的环境变量文件，并在 package.json 中添加一个脚本来触发预发布模式的构建。以下是具体步骤：

1. 创建预发布环境变量文件
创建一个 .env.staging 文件，用于定义预发布环境的变量：

# .env.staging
VITE_API_URL=https://staging.api.example.com
VITE_DEBUG=false

2. 添加预发布模式的脚本命令
   在 package.json 文件中添加一个脚本命令，用于触发预发布模式的构建：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview",
    "build:staging": "vite build --mode staging"
  }
}

3. 使用预发布模式
现在你可以通过以下命令来构建预发布环境：

npm run build:staging

这将使用 .env.staging 文件中的环境变量进行构建，并生成适用于预发布的静态资源文件。

4. 多环境配置
如果你有多个环境（如开发、测试、生产），你可以创建多个配置文件，然后在 vite.config.ts 中根据环境变量动态加载。

1. 在根目录下创建三个配置文件：
基础配置文件

// vite.config.base.ts 
import { UserConfig } from "vite"
import react from "@vitejs/plugin-react"
import { resolve } from "path"
const baseConfig: UserConfig = {
 plugins: [react()],
 resolve: {
   alias: [
     {
       find: /^@\//,
       replacement: `${resolve(__dirname, "src")}/`,
     },
     {
       find: /^images\//,
       replacement: `${resolve(__dirname, "src/assets/images")}/`,
     },
     {
       find: /^utils\//,
       replacement: `${resolve(__dirname, "src/utils")}/`,
     },
   ],
 },
}

export default baseConfig

开发环境配置文件

// vite.config.dev.ts
import { UserConfig } from "vite"

const devConfig: UserConfig = {
  server: {
    port: 8000, // 开发服务器端口
    open: true, // 自动打开浏览器
  },
}

export default devConfig

生产环境配置文件

import { UserConfig } from "vite"

const prodConfig: UserConfig = {
  build: {
    outDir: "dist", // 输出目录
    minify: "terser", // 代码压缩
    sourcemap: false, // 不生成 sourcemap
    rollupOptions: {
      output: {
        manualChunks: {
          // 代码分割
          react: ["react", "react-dom"],
          vendor: ["lodash", "axios"],
        },
      },
    },
  },
}

export default prodConfig

2. 在Vite默认配置文件合并配置

// vite.config.ts
import { defineConfig, ConfigEnv, UserConfig, mergeConfig } from "vite"
import baseConfig from "./vite.config.base"
import devConfig from "./vite.config.dev"
import prodConfig from "./vite.config.prod"

export default defineConfig(({ command, mode }: ConfigEnv): UserConfig => {
  let envConfig = {}
  // 或者使用command === "serve"
  if (mode === "development") {
    // 开发环境配置
    envConfig = devConfig
  } else {
    // 生产环境配置
    envConfig = prodConfig
  }

  return mergeConfig(baseConfig, envConfig)
})