14. Entornos y despliegues

En un proyecto personal empecé desplegando directamente a producción desde mi portátil. Funciona hasta el día en que un cambio rompe algo y no sabes cómo volver. En este capítulo monto lo que uso ahora: entornos separados, previews por rama, despliegue gradual y vuelta atrás en segundos.

Para quién es y qué necesitas

Para quien ya despliega a mano y quiere probar cambios sin miedo: entornos separados, previews por rama, despliegues graduales y vuelta atrás.

Antes de empezar:

• Un proyecto con Wrangler 4.135 o posterior (para Workers Previews).
• Un repositorio en GitHub o GitLab si quieres despliegues automáticos.

Al terminar tendrás producción y staging separados, una preview por rama protegida con Access, despliegues graduales y la vuelta atrás ensayada.

El recorrido de un cambio

flowchart LR
    L[Local<br/>wrangler dev] --> PR[Preview por rama<br/>wrangler preview]
    PR --> ST[Staging<br/>--env staging]
    ST --> G[Producción gradual<br/>10 % → 100 %]
    G -->|algo va mal| RB[wrangler rollback]

Para un proyecto personal, me basta con local + previews + producción. Staging lo añado cuando hay más de una persona o datos que importan.

Entornos con Wrangler

Un entorno es una copia del Worker con su propia configuración. Los recursos (D1, KV, R2) no se heredan: hay que declararlos en cada entorno, y deben ser distintos de los de producción.

{
  "name": "notes",
  "main": "src/index.ts",
  "compatibility_date": "2026-11-03",
  "vars": { "ENVIRONMENT": "production" },
  "d1_databases": [
    { "binding": "DB", "database_name": "notes", "database_id": "…" }
  ],
  "routes": [{ "pattern": "notes.mydomain.dev", "custom_domain": true }],
  "env": {
    "staging": {
      "vars": { "ENVIRONMENT": "staging" },
      "d1_databases": [
        {
          "binding": "DB",
          "database_name": "notes-staging",
          "database_id": "…"
        }
      ],
      "routes": [
        { "pattern": "staging.notes.mydomain.dev", "custom_domain": true }
      ]
    }
  }
}

npx wrangler deploy --env=""        # production (the top level)
npx wrangler deploy --env staging
npx wrangler secret put STRIPE_KEY --env staging
npx wrangler d1 migrations apply notes-staging --env staging --remote

Con entornos definidos, Wrangler avisa si despliegas sin --env. Para producción uso --env="": deja claro a qué entorno va cada despliegue, también en los scripts de package.json.

Previews por rama

Workers Previews crea, para cada rama, un entorno aislado bajo el mismo Worker, con su URL, variables, secretos, bindings y observabilidad. Se configura en el bloque previews (no hereda nada de producción):

{
  "previews": {
    "vars": { "ENVIRONMENT": "preview" },
    "d1_databases": [
      { "binding": "DB", "database_name": "notes-preview", "database_id": "…" }
    ]
  }
}

npx wrangler preview                         # creates or updates the current branch's preview
npx wrangler preview delete --name my-branch # deletes it

Cada preview tiene dos URLs:

Versiones y despliegue gradual

Cada wrangler deploy crea una versión y la pone al 100 %. Para cambios con riesgo, prefiero subir la versión sin publicarla y darle primero un porcentaje del tráfico:

npx wrangler versions upload      # uploads the version, with no traffic
npx wrangler versions deploy      # picks versions and percentages (10% / 90%)
npx wrangler versions list        # version history

Mientras dura, el tráfico se reparte así:

flowchart LR
    U[Usuarios] -->|90 %| V1[Versión actual]
    U -->|10 %| V2[Versión nueva]
    V2 -->|sin errores| T[100 % a la nueva]
    V2 -->|errores| R[Vuelta a la actual]

Durante el despliegue gradual, la afinidad de versión mantiene a cada usuario en la misma versión, para que no salte entre la nueva y la antigua en cada clic. Si los errores no suben en el panel de observabilidad, paso al 100 %.

Volver atrás

npx wrangler rollback                              # to the previous version
npx wrangler rollback <version-id> -m "reason" -y  # to a specific one

Lo probé en este mismo blog: los archivos estáticos vuelven con la versión y el cambio se nota en unos 10–15 segundos.

Despliegue automático: Workers Builds o GitHub Actions

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npm run check
      - run: npm test
      - run: npx wrangler d1 migrations apply notes --remote
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Entornos de desarrollo protegidos con Access

Staging y previews no deberían ser visibles para nadie de fuera. Con Access (gratis hasta 50 usuarios) se protegen sin tocar el código:

1. Zero Trust › Access › Applications › Add an application › Self-hosted.
2. Dominios: staging.notes.mydomain.dev y *-notes.<subdomain>.workers.dev (todas las previews).
3. Política: Allow a los correos de tu equipo, con código por email o login de GitHub.
4. En el Worker de staging, comprueba el JWT de Access como en el capítulo de seguridad.

Además, en los entornos que no son de producción, añado X-Robots-Tag: noindex a todas las respuestas: si un enlace se escapa, que al menos no acabe en Google.

Activar funciones poco a poco

Para cambios que no quieres atar a un despliegue (una función nueva solo para algunos usuarios, un porcentaje de tráfico), Cloudflare tiene Flagship, su servicio de feature flags con segmentación y porcentajes. En un proyecto pequeño me basta con una variable en KV; cuando hay varios flags y personas decidiendo, Flagship evita mantenerlo a mano.

Cuánto cuesta

Al llegar al límite de previews, Cloudflare borra la menos usada.

Resumen

• Cada despliegue es una versión; wrangler rollback vuelve en segundos (el código, no los datos).
• Previews por rama con recursos propios, protegidas con Access.
• Despliegue gradual para los cambios con riesgo; CI con Workers Builds o GitHub Actions.
• Siguiente capítulo: cuándo no usar Cloudflare.

Recursos

• Workers Previews
• Versiones y despliegues
• Despliegue gradual
• Entornos de Wrangler
• Workers Builds
• Flagship