Workers environments: staging and production from one config

TL;DR

The Worker name becomes my-worker-staging` (name plus env suffix), and each environment can carry its own routes, KV namespaces, D1 databases, and other bindings.

Steps

1. One Wrangler file, multiple deployments. Environments override top-level config per named environment.

{
 "name": "my-worker",
 "route": "dev.example.com/*",
 "vars": { "ENVIRONMENT": "dev" },
 "env": {
 "staging": {
 "vars": { "ENVIRONMENT": "staging" },
 "route": "staging.example.com/*"
 },
 "production": {
 "vars": { "ENVIRONMENT": "production" },
 "routes": ["example.com/*"]
 }
 }
}

2. Deploy with wrangler deploy --env staging. The Worker name becomes my-worker-staging (name plus env suffix), and each environment can carry its own routes, KV namespaces, D1 databases, and other bindings.
3. - vars are non-inheritable. Top-level vars do not flow into environments; every environment must define its own. The config above repeats ENVIRONMENT in each env for exactly this reason.

• Custom domains and routes need per-env values. If you deploy to a custom domain or route, each environment needs its own route/routes key. A staging deploy without one goes to workers.dev (or fails, depending on the rest of the config).
• workers_dev per environment. To give staging a *.workers.dev subdomain, set workers_dev = true inside that environment's block.
• With the Vite plugin, select the environment with CLOUDFLARE_ENV, not --env; the build flattens to a single config for that environment.

4. - Give each environment its own backing resources (separate KV namespaces, D1 databases); sharing production data with staging is how staging writes end up in prod.

• wrangler dev --env staging for local work against the staging config.
• Name environments staging and production, not dev2 and final; future you will thank present you.

When to use

You are seeing this: One Wrangler file, multiple deployments. Use this skill when you run into "Workers environments: staging and production from one config".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against the live Wrangler Environments doc: --env flag, name mangling (my-worker-staging), vars non-inheritable, per-env route requirement, workers_dev per env. Ref: https://developers.cloudflare.com/workers/wrangler/environments/