Vite import.meta.env 怎样区分构建期和运行期变量

Vite 里的 import.meta.env 最容易被误解成“浏览器启动时读取的环境变量”。实际边界是：Vite 在开发服务器或构建过程中加载环境文件，把公开变量注入模块；生产构建后，客户端代码拿到的是已经写进产物的值。需要部署后再变化的配置，应该另设一个公开的运行期入口。

官方地址：https://vite.dev/

一句话判断：import.meta.env 适合构建期决定代码和默认配置，不能指望它在同一份静态产物发布后自动读取服务器的新环境变量；运行期差异要通过配置文件或接口显式注入。

先判断变量到底在哪个时刻生效

Vite 官方文档说明，内置常量和环境变量会在构建时静态替换。浏览器最终执行的是替换后的 JavaScript，而不是继续解析服务器上的 .env 文件。因此下面三件事要分开看：

• 构建期：Vite 读取 .env、.env.production 等文件，把符合规则的值放进模块。
• 产物期：替换后的值已经成为静态资源的一部分；同一个文件不会因为部署到另一台机器就重新读取 process.env。
• 运行期：浏览器打开页面后，若还要知道当前部署地址或租户配置，必须加载一个公开配置脚本或请求配置接口。

这也是“改了服务器环境变量但页面仍然是旧值”的常见原因：服务器只替换了运行环境，之前已经生成的静态 JavaScript 并没有重新构建。

用 mode 管理构建期配置

构建期配置适合用 mode 表达目标环境。例如把默认值放进 .env，生产专属值放进 .env.production，预发布值放进 .env.staging：

# .env：所有 mode 都能读取的非敏感默认值
VITE_API_PREFIX=/api

# .env.production：vite build 默认使用 production mode
VITE_RELEASE_CHANNEL=production

# .env.staging：通过 --mode staging 显式选择
VITE_RELEASE_CHANNEL=staging

代码中只读取公开的 VITE_ 变量，并且把字符串转换成真正需要的类型：

const apiPrefix = import.meta.env.VITE_API_PREFIX
const releaseChannel = import.meta.env.VITE_RELEASE_CHANNEL

// Vite 环境变量默认都是字符串，布尔值要显式转换。
const showDiagnostics = import.meta.env.VITE_SHOW_DIAGNOSTICS === 'true'

export const clientConfig = {
  apiPrefix,
  releaseChannel,
  showDiagnostics,
}

构建命令可以把 mode 作为发布目标的一部分记录下来：

# 生产构建：默认 mode 是 production
npm run build

# 预发布构建：读取 .env.staging 等文件
npx vite build --mode staging

mode 专门描述 Vite 选择哪组环境文件；它不是“服务器现在是什么环境”的运行期探测器。并且，已有系统环境变量的优先级高于 .env 文件，发布脚本要避免无意中覆盖或污染目标值。

区分 mode、NODE_ENV 与字符串类型

Vite 的 import.meta.env.MODE 和 Node 的 process.env.NODE_ENV 不是同一个概念。常见组合如下：

const mode = import.meta.env.MODE
const isProduction = import.meta.env.PROD

// 不要把 MODE 当成 NODE_ENV；这里分别记录两个判断。
export function getBuildLabel() {
  return `${mode}:${isProduction ? 'prod' : 'dev'}`
}

另一个容易踩坑的点是类型。即使 VITE_PORT=8080，读出来也仍然是字符串；不要直接拿它做数值加法。需要数字、布尔值或列表时，在配置边界集中转换，并对非法值给出明确默认值。

为运行期配置留下稳定入口

如果希望“同一份构建产物部署到测试、预发布和生产，只在启动容器或上传文件时改变地址”，可以让 HTML 先加载一个公开的 runtime-config.js。它不是秘密仓库，只放 API 地址、功能开关这类本来就会发送给浏览器的值。

// public/runtime-config.js：部署脚本可以在发布时替换这些公开值
window.__APP_CONFIG__ = {
  API_BASE_URL: '__API_BASE_URL__',
  RELEASE_CHANNEL: '__RELEASE_CHANNEL__',
}

declare global {
  interface Window {
    __APP_CONFIG__?: {
      API_BASE_URL?: string
      RELEASE_CHANNEL?: string
    }
  }
}

// 运行期配置必须在应用启动时读取，并提供可诊断的缺省值。
export function getRuntimeConfig() {
  const config = window.__APP_CONFIG__
  return {
    apiBaseUrl: config?.API_BASE_URL || '/api',
    releaseChannel: config?.RELEASE_CHANNEL || 'unknown',
  }
}

如果配置接口是异步请求，就把应用挂载放到配置请求成功之后，并处理失败状态；否则首个请求可能在配置尚未到达时使用错误地址。无论采用脚本还是接口，配置里都不能放 API 密钥、数据库密码或其他服务端秘密，因为浏览器用户可以读取它。

发布前检查暴露边界

1. 检查变量名：只有明确允许进入浏览器的值才使用 VITE_ 前缀；敏感值不要靠改名隐藏。
2. 检查时刻：构建后不会变化的版本号、公开 API 前缀适合 import.meta.env；部署后才决定的地址适合运行期入口。
3. 检查重启：修改 .env 后重启 Vite 开发服务器；修改生产静态配置后清理或刷新缓存。
4. 检查加载顺序：runtime-config.js 必须先于应用入口，避免首屏初始化读到空配置。
5. 检查类型：把字符串到布尔值、数字和数组的转换集中在配置层，不让业务组件各自猜测。

可以用一个简单的决策表收尾：

最终判断标准不是“变量能不能读到”，而是它是否在正确的时刻进入正确的边界：构建期配置交给 Vite，运行期公开配置显式注入，敏感信息留在服务端。

常见问题

为什么改了服务器环境变量，前端页面没有变化？

因为 import.meta.env 通常已经在构建时写入静态产物。要么重新构建，要么改用运行期配置入口。

为什么 VITE_PORT 读出来不是数字？

Vite 会把环境变量作为字符串暴露，读取后应在配置层使用 Number() 或更严格的解析逻辑。

VITE_ 前缀能保护密钥吗？

不能。这个前缀的含义恰恰是允许进入客户端源码；密钥必须留在服务端。

mode 和 NODE_ENV 可以互相替代吗？

不可以。mode 决定 Vite 读取哪组环境文件，NODE_ENV 影响 Node/Vite 的环境判断，二者需要分别设计。