Allow customization of.env loading priorities

[tranhl]

Description

Currently, Vite loads .env files in the following order:

.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

My team uses this structure for our .env files:

.env             
.env.local        
.env.dev        
.env.staging
.env.prod

We use .env.local to toggle flags based on development needs without affecting the config for each mode/environment.

In this case, overriding environment variables locally works well enough if a mode is not passed to Vite explicitly as only the default .env + .env.local files will be loaded. However, when passing a mode to Vite explicitly, local overrides in .env.local will be clobbered by the higher precedent .env.[mode] environment variable. This means when switching modes locally, we need to remember to also rename .env.local to .env.[mode].local, which makes for clunky DX.

Suggested solution

I'd like to propose being able to configure the priority of .env files via config (i.e. envPriority). This is an example of how it could look:

export default defineConfig({
  envPriority: [
    '.env',
    '.env.[mode]',
    '.env.local',
    '.env.[mode].local',
  ],
})

This can then be passed directly to the environment loader:

vite/packages/vite/src/node/env.ts

Lines 8 to 15 in ccd1a4c

	export function getEnvFilesForMode(mode: string, envDir: string): string[] {
	return [
	/** default file */ `.env`,
	/** local file */ `.env.local`,
	/** mode file */ `.env.${mode}`,
	/** mode local file */ `.env.${mode}.local`,
	].map((file) => normalizePath(path.join(envDir, file)))
	}

Thoughts?

Alternative

To work around this right now, we've patched Vite using pnpm patch to adjust the load priority for our use case:

diff --git a/dist/node/chunks/dep-NjL7WTE1.js b/dist/node/chunks/dep-NjL7WTE1.js
index e8ab22b8512cc988241bff18d899ffdd897a7d3a..19214267386cb156d553573c9f43b8c34ba3e5a7 100644
--- a/dist/node/chunks/dep-NjL7WTE1.js
+++ b/dist/node/chunks/dep-NjL7WTE1.js
@@ -34849,10 +34849,10 @@ function getEnvFilesForMode(mode, envDir) {
   return [
     /** default file */
     `.env`,
-    /** local file */
-    `.env.local`,
     /** mode file */
     `.env.${mode}`,
+    /** local file */
+    `.env.local`,
     /** mode local file */
     `.env.${mode}.local`
   ].map((file) => normalizePath$3(path$n.join(envDir, file)));

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.