tsl-env-vite-plugin

Vite 构建期环境变量运行时注入插件。

它会在 vite build 时读取当前 mode 对应的客户端环境变量，生成根目录 env.js，并把源码中静态访问的 import.meta.env.VITE_* 替换为运行时读取 window.__tacos_env__。这样同一份构建产物可以通过替换 env.js 适配不同部署环境。

安装

发布到 npm 后：

npm install tsl-env-vite-plugin -D

本地 npm pack 后在业务项目中安装：

yarn add file:C:/Document/TSL/tacos-fe/tsl-env-vite-plugin/tsl-env-vite-plugin-0.1.0.tgz

使用

import { defineConfig } from 'vite'
import tacosEnv from 'tsl-env-vite-plugin'

export default defineConfig({
  plugins: [tacosEnv()]
})

构建时会自动处理：

• 按 Vite loadEnv 规则加载客户端环境变量
• 在构建输出根目录生成 env.js
• 给每个 HTML 入口注入 env.js
• 将静态 import.meta.env.VITE_* 替换为 window.__tacos_env__.VITE_*
• 仅在 vite build 生效，vite dev 不触发
• SSR 构建默认跳过，避免服务端产物访问 window

生成的 env.js 示例：

window.__tacos_env__={"VITE_API_URL":"/api"};

源码示例：

const apiUrl = import.meta.env.VITE_API_URL

构建后会变为：

const apiUrl = window.__tacos_env__.VITE_API_URL

配置项

interface TacosEnvPluginOptions {
  fileName?: string
  globalName?: string
  envPrefix?: string | string[]
}

默认值：

• fileName: env.js
• globalName: __tacos_env__
• envPrefix: 优先使用 Vite 配置中的 envPrefix，否则为 VITE_

示例：

export default defineConfig({
  plugins: [
    tacosEnv({
      fileName: 'config/env.js',
      globalName: '__APP_ENV__',
      envPrefix: ['VITE_', 'APP_']
    })
  ]
})

说明

默认只处理符合 Vite 客户端暴露规则的变量，例如 VITE_API_URL。无前缀变量不会写入客户端，避免误泄露敏感配置。

插件只支持静态点访问：

import.meta.env.VITE_API_URL

暂不支持动态访问或解构：

import.meta.env['VITE_API_URL']
const { VITE_API_URL } = import.meta.env

MODE、BASE_URL、DEV、PROD、SSR 等 Vite 内置变量仍由 Vite 自身处理，不写入 env.js。

兼容性

已验证通过：

• Vite 5.4
• Vite 6.4
• Vite 7.3
• Vite 8.0