Clarify .env* environment variable priority (#36967)

Clarify that the environment variables are ordered in descending priority and that the existing system environment is not overridden.

fixes #36966

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `yarn lint`


Co-authored-by: JJ Kasper <[email protected]>

Author: gaspar09

docs/basic-features/environment-variables.md

@@ -152,26 +152,14 @@ export default async () => {
 
 ## Environment Variable Load Order
 
-Depending on the environment (as set by `NODE_ENV`), Environment Variables are loaded from the following sources in top-to-bottom order. In all environments, the existing `env` is not overridden by following sources:
+Environment variables are looked up in the following places, in order, stopping once the variable is found.
 
-`NODE_ENV=production`
-
-1. `.env.production.local`
-1. `.env.local`
-1. `.env.production`
-1. `.env`
-
-`NODE_ENV=development`
-
-1. `.env.development.local`
-1. `.env.local`
-1. `.env.development`
+1. `process.env`
+1. `.env.$(NODE_ENV).local`
+1. `.env.local` (Not checked when `NODE_ENV` is `test`.)
+1. `.env.$(NODE_ENV)`
 1. `.env`
 
-`NODE_ENV=test`
-
-1. `.env.test.local`
-1. `.env.test`
-1. `.env`
+For example, if `NODE_ENV` is `development` and you define a variable in both `.env.development.local` and `.env`, the value in `.env.development.local` will be used.
 
-> **Note:** `.env.local` is not loaded when `NODE_ENV=test`.
+> **Note:** The allowed values for `NODE_ENV` are `production`, `development` and `test`.