使用 Vue 3、Vite 和 TypeScript 的环境变量配置

使用 Vue 3、Vite 和 TypeScript 的环境变量配置

在开发现代前端应用时，环境变量是一个非常重要的概念。它可以帮助我们根据不同的环境（开发、测试、生产）配置不同的行为，比如 API 请求地址、调试选项等。在 Vue 3、Vite 和 TypeScript 项目中，如何正确配置和使用环境变量是一个经常遇到的问题。

一、初始化 Vue 3 项目

首先，我们需要使用 Vite 来初始化一个 Vue 3 项目，并启用 TypeScript 支持。

npm init vite@latest my-vue-app --template vue-ts
cd my-vue-app
npm install

执行上面的命令后，你将得到一个包含 Vue 3 和 TypeScript 支持的 Vite 项目。

二、环境变量的基础概念

在 Vite 中，环境变量可以通过 .env 文件进行管理。Vite 内置支持基于不同环境（开发、生产等）的变量管理，这意味着你可以为不同的环境创建不同的变量文件。

• .env：适用于所有环境
• .env.development：仅适用于开发环境
• .env.production：仅适用于生产环境

这些文件中定义的环境变量将会在项目启动时被自动加载。

三、如何定义环境变量

在 .env 文件中定义环境变量非常简单，你只需要按照 KEY=VALUE 的格式来定义即可。

# .env.development
VITE_API_URL=https://dev.api.example.com
VITE_APP_TITLE=MyVueApp (Development)

# .env.production
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=MyVueApp

注意，Vite 要求环境变量的名字必须以 VITE_ 前缀开头。这是为了确保这些变量在构建时能够被正确注入到项目中，并防止与其他工具或系统环境变量冲突。

四、在项目中使用环境变量

一旦定义了环境变量，就可以在项目代码中通过 import.meta.env 访问这些变量。例如，在一个 Vue 组件中：

<script lang="ts">
import { defineComponent } from 'vue';export default defineComponent({setup() {const apiUrl = import.meta.env.VITE_API_URL;const appTitle = import.meta.env.VITE_APP_TITLE;console.log('API URL:', apiUrl);console.log('App Title:', appTitle);return { apiUrl, appTitle };}
});
</script>

import.meta.env 是 Vite 提供的一个全局对象，它包含了所有以 VITE_ 开头的环境变量。

五、区分不同环境

在项目开发中，我们可能需要区分不同的环境来执行不同的逻辑。可以使用 import.meta.env.MODE 来判断当前的构建环境。

<script lang="ts">
import { defineComponent } from 'vue';export default defineComponent({setup() {if (import.meta.env.MODE === 'development') {console.log('Running in development mode');} else if (import.meta.env.MODE === 'production') {console.log('Running in production mode');}return {};}
});
</script>

import.meta.env.MODE 会返回当前的模式，可以是 development 或 production，也可以是自定义的模式。

六、TypeScript 环境变量类型提示

为了让 TypeScript 识别我们定义的环境变量，我们可以创建一个 env.d.ts 文件，手动为 import.meta.env 提供类型声明。

在项目根目录下创建 src/env.d.ts 文件，内容如下：

interface ImportMetaEnv {readonly VITE_API_URL: string;readonly VITE_APP_TITLE: string;
}interface ImportMeta {readonly env: ImportMetaEnv;
}

这样，当我们使用 import.meta.env.VITE_API_URL 时，TypeScript 就会提供类型检查和提示功能，避免拼写错误或类型错误。

七 .env文件的运行模式

在 Vite 项目中，.env 文件的后缀（如 .env.development 和 .env.production）通过 运行模式 (mode) 来生效。Vite 根据不同的运行模式，自动加载相应的环境文件。这一过程可以通过以下几个方面来理解。

1. 运行模式（Mode）

Vite 提供了不同的 运行模式，如 development、production 和自定义模式。运行模式影响了环境变量的加载方式，以及构建时的配置差异。

• development 模式：用于本地开发，通常启用热模块替换（HMR）等功能。
• production 模式：用于生产环境，通常会启用代码压缩、Tree-shaking 等优化。

当你启动 Vite 时，Vite 会根据运行模式选择性加载不同的 .env 文件：

• 如果是 development 模式，Vite 会加载 .env.development 文件。
• 如果是 production 模式，Vite 会加载 .env.production 文件。
• .env 文件是通用文件，不论什么模式都会加载。

2. 文件加载顺序

Vite 会按照以下顺序依次加载环境文件，且后面的文件会覆盖前面文件中定义的同名变量：

1. .env：通用环境变量，适用于所有模式。
2. .env.local：通用的本地环境变量，不会上传到版本控制。
3. .env.[mode]：特定模式的环境变量，例如 .env.development 或 .env.production。
4. .env.[mode].local：特定模式的本地环境变量，不会上传到版本控制。

例如，在 development 模式下，Vite 的加载顺序如下：

• .env
• .env.local
• .env.development
• .env.development.local

在 production 模式下，加载顺序为：

• .env
• .env.local
• .env.production
• .env.production.local

3. 如何指定运行模式

默认情况下，Vite 在开发环境中运行 development 模式，在构建时运行 production 模式。不过，你也可以通过命令行参数显式指定模式。

例如，使用 vite 启动开发服务器时，默认运行 development 模式：

npm run dev

但你也可以通过 --mode 参数指定运行模式：

# 使用 production 模式启动开发服务器
npm run dev -- --mode production

同样地，在构建项目时，默认是 production 模式，但你也可以指定其他模式：

# 以 staging 模式构建
npm run build -- --mode staging

通过指定 --mode 参数，Vite 会根据所提供的模式来加载对应的 .env.[mode] 文件。

4. 自定义模式

除了 development 和 production 模式，你还可以根据项目需求创建自定义模式。

假设你要为 staging（预发布）环境配置变量，可以创建一个 .env.staging 文件，然后在构建命令中指定 staging 模式：

# .env.staging 文件中的变量
VITE_API_URL=https://staging.api.example.com
VITE_APP_TITLE=MyVueApp (Staging)

构建命令：

npm run build -- --mode staging

当你运行这个命令时，Vite 会加载 .env.staging 和 .env.staging.local 文件中的环境变量。

5. 环境变量覆盖

同一环境下的多个 .env 文件中如果定义了同名变量，加载顺序较后的文件中的值会覆盖较前的文件中的值。这为我们提供了灵活性，可以通过 .env.local 或 .env.[mode].local 文件来覆盖默认的设置，而不需要修改公共的 .env 文件。这在团队协作中尤为有用，.local 文件可以包含敏感信息或个人的开发配置，并且可以被 .gitignore 忽略，不会被提交到版本控制系统中。

6. 运行模式汇总说明

• .env 文件后缀根据 Vite 的 运行模式（mode）生效，如 development、production 等。
• 通过 .env.[mode] 文件可以为特定模式定义环境变量，Vite 会根据当前模式自动加载对应的 .env 文件。
• 加载顺序为 .env → .env.local → .env.[mode] → .env.[mode].local，后者会覆盖前者的同名变量。
• 可以通过命令行的 --mode 参数指定自定义模式，以便加载自定义的环境配置文件。

七、总结

在 Vue 3、Vite 和 TypeScript 项目中使用环境变量可以极大地提高应用的灵活性和可维护性。通过创建 .env 文件，并使用 import.meta.env 来访问和管理环境变量，可以轻松地根据不同的环境配置不同的项目行为。记得在项目中使用 TypeScript 类型声明为环境变量提供类型提示，这样可以进一步提升开发体验。

参考链接

• Vite 官方文档：https://vitejs.dev/guide/env-and-mode.html
• Vue 3 官方文档：https://vuejs.org/
• TypeScript 官方文档：https://www.typescriptlang.org/docs/