Pular para o conteúdo

Environment variables and secrets

Atualizado em Ver como Markdown

Put secrets for use in local development in either a .dev.vars file or a .env file, in the same directory as the Wrangler configuration file.

These files should be formatted using the dotenv ↗ syntax. For example:

.dev.vars / .envbash
SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

To set different secrets for each Cloudflare environment, create files named .dev.vars.<environment-name> or .env.<environment-name>.

When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic .dev.vars (or .env) file.

  • When using .dev.vars.<environment-name> files, all secrets must be defined per environment. If .dev.vars.<environment-name> exists then only this will be loaded; the .dev.vars file will not be loaded.
  • In contrast, all matching .env files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence:
    • .env.<environment-name>.local (most specific)
    • .env.local
    • .env.<environment-name>
    • .env (least specific)

Basic setup

Here are steps to set up environment variables for local development using either .dev.vars or .env files.

  1. Create a .dev.vars / .env file in your project root.

  2. Add key-value pairs:

    .dev.vars/.envini
    API_HOST="localhost:3000"
DEBUG="true"
SECRET_TOKEN="my-local-secret-token"

  3. Run your dev command

    Wrangler

    
								
									
									npx
									 wrangler dev

    Vite plugin

    
								
									
									npx
									 vite dev

Multiple local environments

To simulate different local environments, you can provide environment-specific files. For example, you might have a staging environment that requires different settings than your development environment.

  1. Create a file named .dev.vars.<environment-name>/.env.<environment-name>. For example, we can use .dev.vars.staging/.env.staging.

  2. Add key-value pairs:

    .dev.vars.staging/.env.stagingini
    API_HOST="staging.localhost:3000"
DEBUG="false"
SECRET_TOKEN="staging-token"

  3. Specify the environment when running the dev command:

    Wrangler

    
								
									
									npx
									 wrangler dev --env staging

    Vite plugin

    
								
									
									CLOUDFLARE_ENV=staging
									 npx vite dev
    • If using .dev.vars.staging, only the values from that file will be applied instead of .dev.vars.
    • If using .env.staging, the values will be merged with .env files, with the most specific file taking precedence.

Learn more