解决 Vite 项目中 import.meta.env 变量为 undefined 的问题

问题描述

在使用 Vite + Vue 3 的项目开发过程中，我遇到了一个奇怪的问题：尽管在 .env.development 文件中正确配置了环境变量，但在代码中通过 import.meta.env.VITE_API_BASE_URL 访问时却返回 undefined。

javascript 复制代码

onMounted(() => {
  console.log(import.meta.env.VITE_API_BASE_URL); // 输出: undefined
})

环境配置

项目中的 .env.development 文件内容如下：

env 复制代码

VITE_API_BASE_URL=http://172.20.10.10:8890/api
VITE_ENV=development

问题排查

1. 检查环境变量前缀

Vite 默认只暴露以 VITE_ 为前缀的环境变量到客户端代码中。确认我们的变量名 VITE_API_BASE_URL 符合这个要求。

2. 检查 Vite 配置

查看 vite.config.ts 文件，确认没有自定义的 envPrefix 配置：

typescript 复制代码

export default defineConfig({
  // ... 其他配置
  // 没有设置 envPrefix，使用默认的 VITE_
})

3. 检查文件编码问题（关键发现）

通过查看文件内容，发现 .env.development 文件存在编码问题：

复制代码

# 文件开头包含 UTF-16 BOM 标记
��# . e n v . d e v e l o p m e n t

文件被保存为 UTF-16 编码，包含了 BOM（Byte Order Mark），这导致 Vite 无法正确解析环境变量。

解决方案

方法一：重新创建环境文件

删除现有的 .env.development 文件
使用文本编辑器（如 VS Code、Notepad++ 等）重新创建文件
确保文件保存为 UTF-8 编码（无 BOM）
重新写入环境变量配置：

env 复制代码

VITE_API_BASE_URL=http://172.20.10.10:8890/api
VITE_ENV=development

方法二：使用命令行重新写入

bash 复制代码

# 使用 echo 命令重新创建文件（确保 UTF-8 编码）
echo "VITE_API_BASE_URL=http://172.20.10.10:8890/api
VITE_ENV=development" > .env.development

验证修复

修复后，重启开发服务器：

bash 复制代码

npm run dev

在代码中验证环境变量：

javascript 复制代码

onMounted(() => {
  console.log(import.meta.env.VITE_API_BASE_URL); // 现在应该输出: http://172.20.10.10:8890/api
})

预防措施

统一编辑器编码设置：确保所有开发工具都使用 UTF-8 编码保存文件
检查文件编码：在编辑器中查看文件编码状态，确保是 UTF-8（无 BOM）
版本控制 ：在 .gitattributes 中设置文本文件的编码：

gitattributes 复制代码

*.env text working-tree-encoding=UTF-8

总结

Vite 环境变量为 undefined 的问题通常与以下因素相关：

环境变量命名不符合 VITE_ 前缀要求
文件编码问题（如 UTF-16 BOM）
Vite 配置中自定义了 envPrefix
开发服务器未重启

通过系统性地排查这些因素，特别是注意文件编码问题，可以有效解决此类问题。

解决 Vite 项目中 import.meta.env 变量为 undefined 的问题