Vue / 系统课时

管理环境变量

管理环境变量

管理后台通常需要在开发、测试和生产环境使用不同的接口地址与功能开关。本课建立可覆盖的环境变量文件,封装读取逻辑,并明确哪些值可以进入前端构建产物、哪些敏感信息绝不能放入其中。

学习目标

  • 按环境拆分接口地址、应用标题和功能开关
  • 为 import.meta.env 补充类型并统一转换数据类型
  • 判断环境变量中可以存放与禁止存放的内容

规划环境文件

Vite 会根据运行模式加载对应文件。通用值放在 .env,开发与生产差异分别放在 .env.development、.env.production,仅供本机使用且不提交仓库的覆盖值放在 .env.local。

只有以 VITE_ 开头的变量会暴露给客户端代码。变量名应表达业务含义,不要把环境名称硬编码进名称中。

bash
# .env
VITE_APP_TITLE=Vue 3 管理后台项目
VITE_ENABLE_MOCK=false
bash
# .env.development
VITE_API_BASE_URL=/api
VITE_ENABLE_MOCK=true
bash
# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_ENABLE_MOCK=false

同名变量按当前模式覆盖通用值。.env.local 适合个人调试地址,但应加入 .gitignore,避免把本机配置意外提交。

补充类型声明

新建或编辑 src/vite-env.d.ts,显式声明项目使用的变量。这样拼错变量名时,编辑器会在开发阶段提示,而不是等到运行时才得到 undefined。

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

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_ENABLE_MOCK: 'true' | 'false'
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

类型声明只描述预期结构,不会自动校验实际文件内容,因此仍需要在读取层处理缺失值和字符串转换。

封装读取逻辑

在 src/config/env.ts 中集中读取变量,业务组件只依赖转换后的配置对象。布尔值不能使用 Boolean('false') 转换,因为非空字符串始终会得到 true。

ts
function requireEnv(name: string, value: string | undefined): string {
  if (!value) {
    throw new Error(`缺少环境变量:${name}`)
  }
  return value
}

export const appEnv = Object.freeze({
  apiBaseUrl: requireEnv(
    'VITE_API_BASE_URL',
    import.meta.env.VITE_API_BASE_URL
  ),
  appTitle: requireEnv(
    'VITE_APP_TITLE',
    import.meta.env.VITE_APP_TITLE
  ),
  enableMock: import.meta.env.VITE_ENABLE_MOCK === 'true'
})

这种封装让缺失配置在应用启动阶段立即失败,也避免组件重复解析字符串。需要新增变量时,应同时修改环境文件、类型声明和读取对象。

运行并验证

在 src/main.ts 中临时加入下面的片段示例,开发模式启动后从浏览器控制台检查最终值。验证完成后可以删除日志。

ts
import { appEnv } from './config/env'

console.table(appEnv)

预期结果:

text
apiBaseUrl  /api
appTitle    Vue 3 管理后台项目
enableMock  true

再执行生产构建,确认生产变量能够被正确替换:

bash
npm run build

预期输出:

text
✓ built in <TIME>s

实际耗时可能不同。若读取结果仍是旧值,应停止并重新启动开发服务器,因为环境文件变化通常不会在现有进程中完整重载。

敏感信息边界

前端环境变量会在构建时写入浏览器可下载的 JavaScript,因此不能保存数据库密码、私钥、永久访问令牌或第三方服务密钥。真正的秘密必须保存在服务端或部署平台的受控变量中,由后端代为调用。

接口基础地址、应用标题和非敏感功能开关可以进入前端。即使变量写在未提交的 .env.local 中,只要被前端代码引用并完成构建,最终用户仍可能看到它。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理环境变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通