env变量和模式

Vite在特殊import.meta.env对象下暴露了某些常数。这些常数被定义为开发过程中的全局变量，并在建造时间静态替换以使树震动。

内置常数

在所有情况下，都可以使用一些内置常数:

• import.meta.env.MODE :{字符串}应用程序正在运行的模式。

• import.meta.env.BASE_URL :{string}基本URL该应用程序正在提供。这是由base配置选项确定的。

• import.meta.env.PROD :{boolean}该应用是在生产中运行的（使用NODE_ENV='production'运行DEV服务器还是运行使用NODE_ENV='production'构建的应用程序）。

• import.meta.env.DEV :{boolean}应用程序是否在开发中运行（始终与import.meta.env.PROD相反）

• import.meta.env.SSR :{boolean}应用程序是否在服务器中运行。

env变量

Vite自动将ENV变量揭示import.meta.env对象下的Env变量。

为了防止意外泄漏到客户端的ENV变量，只有带有VITE_前缀的变量暴露于您的Vite加工代码。例如，用于以下ENV变量:

.env

VITE_SOME_KEY=123
DB_PASSWORD=foobar

只有VITE_SOME_KEY将其视为import.meta.env.VITE_SOME_KEY客户源代码，但DB_PASSWORD不会。

console.log(import.meta.env.VITE_SOME_KEY) // “ 123”
console.log(import.meta.env.DB_PASSWORD) // 不明确的

如果要自定义ENV变量前缀，请参见EnvpRefix选项。

Env parsing

如上所示， VITE_SOME_KEY是一个数字，但解析时返回字符串。布尔值变量也会发生同样的情况。在代码中使用时，请确保将其转换为所需类型。

.env文件

Vite使用DotEnv从您的环境目录中的以下文件加载其他环境变量:

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

Env Loading Priorities

特定模式（例如.env.production ）的ENV文件将比通用模式更高（例如.env ）更高的优先级。

除特定于模式的.env.[mode]文件外，Vite将始终加载.env和.env.local 。在模式特定文件中声明的变量将优先于通用文件中的变量，但是仅在.env或.env.local中定义的变量仍将在环境中可用。

此外，执行VITE时已经存在的环境变量具有最高优先级，并且不会被.env文件覆盖。例如，运行VITE_SOME_KEY=123 vite build时。

.env文件在VITE的开头加载。更改后重新启动服务器。

此外，Vite使用Dotenv-Expand扩展了包装盒中编写的Env文件中写入的变量。要了解有关语法的更多信息，请查看他们的文档。

请注意，如果您想在环境价值内使用$ ，则必须使用\逃脱它。

.env

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

SECURITY NOTES

• .env.*.local文件仅本地化，可以包含敏感变量。您应该在.gitignore中添加*.local ，以避免将它们检查到GIT中。

• 由于暴露于您的Vite源代码的任何变量都将最终出现在您的客户端束中，因此VITE_*变量不应包含任何敏感信息。

Expanding variables in reverse order

Vite支持以相反顺序扩展变量。 例如，下面的.env将评估VITE_BAR=bar VITE_FOO=foobar 。

.env

VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar

这在shell脚本和其他工具等docker-compose中不起作用。 也就是说，Vite支持了这种行为，因为很长一段时间以来一直支持dotenv-expand ，JavaScript生态系统中的其他工具使用支持此行为的较旧版本。

为了避免互动问题，建议避免依靠这种行为。 Vite将来可能会开始对这种行为发出警告。

TypeScript的IntelliSense

默认情况下，Vite提供了import.meta.env合vite/client.d.ts中的类型定义。虽然您可以在.env.[mode]文件中定义更多自定义的ENV变量，但您可能需要获取带有VITE_前缀的用户定义的ENV变量的TypeScript Intellisense。

为了实现这一目标，您可以创建一个src中的vite-env.d.ts目录，然后按这样的增强ImportMetaEnv :

vite-env.d.ts

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // 更多的env变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

如果您的代码依赖于浏览器环境（例如DOM和Webworker）的类型，则可以在tsconfig.json中更新LIB字段。

tsconfig.json

{
  "lib": ["WebWorker"]
}

Imports will break type augmentation

如果ImportMetaEnv增强不起作用，请确保您在vite-env.d.ts中没有任何import语句。有关更多信息，请参见TypeScript文档。

html恒定更换

Vite还支持替换HTML文件中的常数。具有特殊%CONST_NAME%语法的import.meta.env文件中的任何属性都可以使用:

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

如果ENV在import.meta.env中不存在，例如%NON_EXISTENT% ，它将被忽略和替换，这与JS中的import.meta.env.NON_EXISTENT不同，在该JS中被替换为undefined 。

鉴于许多框架使用了VITE，因此在有条件等复杂替换方面有意地未经公开。可以使用现有的Userland插件或实现transformIndexHtml挂钩的自定义插件来扩展Vite。

模式

默认情况下，Dev Server（ dev命令）以development模式运行， build命令在production模式下运行。

这意味着运行vite build时，如果有一个，则将从.env.production加载env变量:

.env.production

VITE_APP_TITLE=My App

在您的应用中，您可以使用import.meta.env.VITE_APP_TITLE渲染标题。

在某些情况下，您可能需要以不同的模式运行vite build来渲染其他标题。您可以通过传递--mode选项标志来覆盖用于命令的默认模式。例如，如果您想为登台模式构建应用程序:

vite build --mode staging

并创建一个.env.staging文件:

.env.staging

VITE_APP_TITLE=My App (staging)

由于vite build默认运行生产构建，您还可以通过使用其他模式和.env文件配置来更改此版本并运行开发构建:

.env.testing

NODE_ENV=development

node_env和模式

重要的是要注意， NODE_ENV （ process.env.NODE_ENV ）和模式是两个不同的概念。以下是不同命令如何影响NODE_ENV和模式:

命令	node_env	模式
vite build	"production"	"production"
vite build --mode development	"production"	"development"
NODE_ENV=development vite build	"development"	"production"
NODE_ENV=development vite build --mode development	"development"	"development"

NODE_ENV和模式的不同值还反映了其相应的import.meta.env属性:

命令	import.meta.env.PROD	import.meta.env.DEV
NODE_ENV=production	true	false
NODE_ENV=development	false	true
NODE_ENV=other	false	true

命令	import.meta.env.MODE
--mode production	"production"
--mode development	"development"
--mode staging	"staging"

NODE_ENV in .env files

NODE_ENV=...可以在命令中以及.env文件中设置。如果在.env.[mode]文件中指定了NODE_ENV ，则该模式可用于控制其值。但是， NODE_ENV和模式都作为两个不同的概念。

命令中NODE_ENV=...的主要好处是，它允许VITE提早检测值。它还允许您在Vite Config中读取process.env.NODE_ENV因为Vite只有在评估配置后才可以加载Env文件。