前端 Vite 环境变量前缀 怎样处理

Vite默认把VITE_前缀的环境变量提供给客户端代码。需要改前缀时，使用envPrefix配置；迁移期间可以保留旧前缀并加入新的公开前缀。关键是把它视为客户端暴露选择，而不是秘密保护机制：匹配前缀的变量都应按公开信息管理。

本文以多个前端应用共用构建约定为例，说明如何从散落的变量读取收敛到显式配置对象。这是工程方案示例，不是线上迁移报告，未运行构建或性能测试。官方入口：https://vite.dev/guide/env-and-mode。

一、多应用配置的瓶颈不是前缀不够短

当管理端、门户和活动页分别读取环境变量，问题往往出在同一个字段有不同名字、缺省值不一致，以及共享构建任务混入不属于该应用的配置。仅把VITE_改成一个团队缩写，不能解决这些问题。

建议先维护一份公开配置清单：字段用途、类型、允许值、所属应用、构建模式和责任人。服务端凭据不进入这份清单。没有匹配envPrefix不代表变量绝不可能泄露，插件、手写define或把配置文件放进公开资源目录都可能形成另一条暴露路径。

二、双前缀迁移，必须显式保留旧范围

下面的vite.config.js片段保留旧VITE_并加入PORTAL_PUBLIC_，用于门户应用过渡。它不会自动把旧变量改名，也不会把新字段写回旧字段。

import { defineConfig } from 'vite'

// 过渡期同时接受两个公开前缀；不是两个互相隔离的安全域
export default defineConfig({
  envPrefix: ['VITE_', 'PORTAL_PUBLIC_'],
})

如果只配置PORTAL_PUBLIC_，原先VITE_字段就不再因默认前缀被暴露。不要用空字符串表示“全部兼容”：Vite会拒绝空前缀。前缀匹配也不是逐字段白名单；不要把包含敏感内容的变量改成公开前缀来修复undefined。

示例.env只含公开值，文件名应结合当前应用的环境目录和模式使用。

# 门户公开配置示例，不包含服务端凭据
PORTAL_PUBLIC_API_BASE=/api/portal
PORTAL_PUBLIC_SEARCH_ENABLED=false

三、集中读取，明确新旧字段冲突和类型转换

在src/public-config.js中集中读取，业务模块仅依赖publicConfig，不自行拼变量名或扩展整个环境对象。下面选择“新旧同时存在且不同就报错”，防止构建任务悄悄使用意外值。

// 新旧字段均为公开配置；不输出原值到错误日志
function pickPublic(name, current, legacy) {
  if (current !== undefined && legacy !== undefined && current !== legacy) {
    throw new Error(name + ' 新旧配置冲突')
  }
  return current ?? legacy
}

const apiBase = pickPublic(
  'API_BASE',
  import.meta.env.PORTAL_PUBLIC_API_BASE,
  import.meta.env.VITE_API_BASE,
)
const searchFlag = pickPublic(
  'SEARCH_ENABLED',
  import.meta.env.PORTAL_PUBLIC_SEARCH_ENABLED,
  import.meta.env.VITE_SEARCH_ENABLED,
)

// 本例仅允许根相对路径，避免把错误外部地址当作API入口
if (typeof apiBase !== 'string' || !apiBase.startsWith('/') ||
    apiBase.startsWith('//') || /[\\\s?#]/.test(apiBase)) {
  throw new Error('API_BASE必须是约定的根相对路径')
}
if (searchFlag !== 'true' && searchFlag !== 'false') {
  throw new Error('SEARCH_ENABLED必须为true或false')
}

export const publicConfig = Object.freeze({
  apiBase,
  searchEnabled: searchFlag === 'true', // 不使用Boolean("false")
})

这段路径规则只是本例输入格式约束，不是网络访问授权或完整URL安全过滤器。生产项目应按真实API路由维护更具体的允许范围。模块里的throw发生在模块被求值时，不能据此宣称vite build一定会主动执行这套业务检查；若要求构建时阻断，需要在构建配置或独立配置检查中落实同一契约。

自定义环境变量通常是字符串，字符串false并不是JavaScript假值。Vite自身的DEV、PROD等内置布尔常量属于另一类，不要为了统一处理而把所有字段都当字符串。TypeScript声明只能改善编辑体验，也不会凭空提供缺失值或完成运行期转换。

四、前缀正确仍然为空，检查配置来源

排查时分别记录应用root、envDir、mode、变量名以及值是否存在，不打印整个环境。前缀决定可暴露命名范围，模式决定读取哪一组环境文件，两者不能混为一谈。

模式专属文件可以覆盖通用文件；启动Vite时已经存在的环境变量优先于.env文件。因此本地文件看起来正确，也可能被CI任务注入的旧值覆盖。修改.env后应重新启动开发服务；生产静态页面则需要重新构建并部署对应产物，而不是只重启静态文件服务器。

五、按应用推进迁移，而不是一次扩散共享范围

建议以单应用为单位增加前缀、引入集中读取、迁移字段，再删除旧前缀兼容。双前缀期的代价是暴露候选范围更大，应设明确结束条件。不同应用共用一个仓库，也不意味着要共享全部.env目录或公开变量。

回退要绑定配置文件、CI字段和构建产物版本。若只回退代码却保留新配置，新旧字段可能冲突。若发生真实密钥暴露，应按凭据处置流程撤销或轮换，不能以删除前缀和重新构建宣称历史泄露已消失。

上线观察项可以包括缺字段错误、冲突错误、配置版本和错误接口请求，但本文没有执行上线或给出改进比例。后续扩展到运行期配置时，应单独定义公开配置端点与缓存策略，不把构建期变量误认为动态配置中心。

六、常见问题

.env.local不提交Git，就能放前端密钥吗？

不能。是否提交仓库与是否注入客户端是两件事。进入客户端的秘密不再能由文件忽略规则保护。

可以用process.env替代import.meta.env吗？

浏览器不是Node进程，不应依赖服务端环境读取方式。配置文件能读取到某个值，也不表示客户端可以安全读取它。

没有VITE_前缀就一定安全？

不是。前缀只是Vite这条暴露规则；还应避免手工注入整个process.env、公开原始配置文件或让插件扩散敏感配置。

参考：Vite环境变量与模式、envPrefix配置。多应用配置的核心是公开字段契约与清晰归属，前缀只是其中一个入口。