Clarify how wrangler --env affects loading .env and .dev.vars (#19340)

Co-authored-by: Pete Bacon Darwin <[email protected]>

Author: vicb

src/content/docs/workers/wrangler/system-environment-variables.mdx

@@ -16,6 +16,11 @@ System environment variables are local environment variables that can change Wra
 
 3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration.
 
+:::note
+
+You can set system environment variables per environment by creating additional files with the naming convention `.env.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.env` file - they are not merged.
+:::
+
 ## Supported environment variables
 
 Wrangler supports the following environment variables:

src/content/partials/workers/secrets-in-dev.mdx

@@ -12,4 +12,6 @@ SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
+You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.dev.vars` file - they are not merged.
+
+Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.