Trabajadores y páginas: implementación, enrutamiento y lo que esconde cada modelo

Cuando un equipo adopta Cloudflare Workers, la primera implementación es trivial: wrangler deploy, eso es todo, el script está activo. Cuando otro equipo adopta Pages, la primera implementación también es trivial: conectar el repositorio de GitHub, configurar el comando de compilación, eso es todo. El problema aparece cuando los dos coexisten en la misma zona, cuando necesitas una vista previa por rama o cuando alguien necesita auditar lo que se está ejecutando en producción sin acceder al panel.

Cómo se despliegan los trabajadores

El artefacto central de un proyecto de Trabajadores es wrangler.toml. Contiene rutas, enlaces, variables de entorno, límites de compatibilidad y entornos. Una implementación típica de producción/ensayo se ve así en el mismo archivo:

name = "minha-api"
main = "src/index.ts"
compatibility_date = "2024-09-23"

[[routes]]
pattern = "api.exemplo.com/*"
zone_name = "exemplo.com"

[env.staging]
name = "minha-api-staging"
[[env.staging.routes]]
pattern = "api-staging.exemplo.com/*"
zone_name = "exemplo.com"

Esta es una configuración versionada en código, revisable en solicitudes de extracción y rastreable en el historial de Git. Cualquier cambio de ruta o vinculante pasa por el mismo proceso de revisión de código.

wrangler deploy --env staging implementa el script como un trabajador separado (minha-api-staging), con sus propias rutas y enlaces. Los entornos en Workers son trabajadores distintos, no variantes de la misma implementación.

Cómo se implementa Pages

Pages funciona a través de git push. Usted conecta un repositorio, define el comando de compilación y el directorio de salida en el panel, y cada envío a la rama principal activa una canalización: clonar, instalar, compilar y cargar los activos en la CDN. El proceso ejecuta hasta 500 compilaciones/mes en el plan gratuito y 5000/mes en el plan pago ($20/mes).

La gran diferencia operativa: cada envío a cualquier sucursal que no sea la principal genera una implementación de vista previa automática con una URL única en el formato hash-branch.seuprojet.pages.dev. Abres una solicitud de extracción, Cloudflare comenta el PR con la URL de vista previa. El equipo de producto prueba la URL antes de aprobar la combinación. Workers no tiene un equivalente nativo para esto.

La limitación simétrica: la configuración de compilación de las páginas (comando de compilación, variables de entorno, versión del nodo) está en el panel, no en el archivo de código. Hasta la fecha, no hay soporte completo para wrangler.toml Pages. Esto significa que los cambios de configuración de compilación no pasan por solicitudes de extracción y no están en el historial de Git. Para los equipos que requieren un seguimiento completo de la auditoría de la infraestructura, esto es una verdadera fricción.

Enrutamiento y trampa de colisión de ruta

Los trabajadores utilizan patrones de ruta vinculados a una zona. El patrón api.exemplo.com/v1/* captura todas las solicitudes para esta ruta y las entrega al script correspondiente. Si dos trabajadores diferentes intentan registrar el mismo patrón en la misma zona, la segunda implementación falla con un error de conflicto.

Pages utiliza un subdominio dedicado (*.pages.dev) o un dominio personalizado vinculado al proyecto. Cuando usas un dominio personalizado en Pages, Cloudflare crea un trabajador interno que sirve los activos y los enruta a las funciones. Este trabajador interno ocupa las rutas del dominio.

El problema concreto: tiene un proyecto de Pages en app.exemplo.com y desea agregar un trabajador independiente para procesar webhooks en app.exemplo.com/webhooks. No da. Las rutas de páginas ya capturan app.exemplo.com/*. La solución es mover el controlador de webhooks a una función de páginas en /functions/webhooks.ts, o usar un subdominio separado (webhooks.exemplo.com) con un trabajador independiente.

La precedencia de enrutamiento dentro de las páginas sigue un orden fijo: primero se procesa _redirects, luego _headers, luego las funciones en /functions y, por último, los activos estáticos. Esto significa que una función en /functions/blog/[slug].ts tiene prioridad sobre un archivo estático en /blog/qualquer-coisa.html, lo que puede resultar sorprendente si generó páginas estáticas con la misma ruta.

Entornos de página y lo que falta

Pages tiene el concepto de entornos de producción y vista previa. La producción es la rama principal; cualquier otra rama genera una vista previa. Puede configurar variables de entorno separadas por entorno en el panel.

Lo que Pages no tiene: múltiples entornos con nombres con diferentes configuraciones de compilación. Workers permite wrangler deploy --env staging con un conjunto completamente diferente de enlaces y variables. En Pages, si desea un entorno de prueba con una base de datos D1 diferente, debe crear un proyecto de Pages separado y administrar la sincronización entre los dos manualmente.

Para los equipos que trabajan con una preparación estricta ([base de datos separada, claves API de zona de pruebas, indicadores de características distintas), esta limitación es significativa y generalmente traslada estas cargas de trabajo a los trabajadores.

Cómo va wrangler.toml (parcialmente) a Pages

Cloudflare anunció soporte experimental en 2020 para configurar enlaces de Pages Functions: espacios de nombres KV, bases de datos D1, variables de entorno. Esto resuelve parte del problema del seguimiento de auditoría: los enlaces permanecen en el código. Pero la canalización de compilación (comando, directorio de salida, versión del nodo) todavía está en el panel.

El estado actual es parcial. Aquellos que hoy necesitan una configuración de código del 100 % utilizan Workers con activos servidos a través de R2 + Cache API, renunciando a la CDN de Pages gratuita. Esta es una verdadera compensación que vale la pena calcular antes de tomar la decisión.

##Qué evaluar antes de decidir

El modelo de implementación de Pages ofrece dos activos concretos: canal de compilación integrado (sin CI externo para ensamblar) e implementaciones de vista previa automática por sucursal. Para los equipos de diseño y productos que revisan las funciones antes de fusionarlas, la vista previa de la rama acelera considerablemente el ciclo de revisión.

Workers ofrece configuración de código auditable desde el primer día, entornos con nombre con enlaces distintos y soporte para activadores que no son HTTP (cron, colas, correo electrónico) que Pages no tiene. Para API o servicios sin un componente visual que necesitan una puesta en escena rigurosa, los trabajadores estructurados con wrangler.toml bien organizados son operativamente más limpios.