Funciones de páginas: cuándo usar en lugar de trabajadores puros

Existe una idea errónea común sobre las funciones de las páginas: que son una versión simplificada o limitada de los trabajadores, adecuadas para casos triviales e insuficientes para una producción seria. Eso no es cierto. Las funciones de páginas se ejecutan en el mismo tiempo de ejecución V8 que los trabajadores, acceden a los mismos enlaces y respetan los mismos límites. La diferencia entre las dos formas de despliegue no es de capacidad, sino de contexto operativo.

Qué son las funciones de las páginas, técnicamente

Las funciones de Pages son trabajadores implementados mediante una convención del sistema de archivos dentro de un proyecto de Pages. Crea un directorio /functions en la raíz del repositorio, y cada archivo TypeScript o JavaScript allí se convierte en una ruta. El archivo /functions/api/users/[id].ts responde en /api/users/:id. El archivo /functions/webhooks/stripe.ts responde en /webhooks/stripe.

El tiempo de ejecución que ejecuta este código es idéntico al de un Worker independiente: aislamientos V8, arranque en frío por debajo de 1 ms, 128 MB de memoria por invocación (límite estricto), 30 segundos de CPU por solicitud en el plan pago, 1000 subsolicitudes por invocación. Los enlaces disponibles son los mismos: D1 para la base de datos SQLite en el borde, KV para almacenamiento de valores clave, R2 para objetos, Objetos duraderos para estado consistente, AI para inferencia, Enlaces de servicio para llamadas directas a otros trabajadores.

La distinción existe en la implementación: una función de páginas se crea como parte de un proyecto de páginas que también tiene activos estáticos. No es posible implementar una función de Pages sin un proyecto de Pages. Esto no es una limitación técnica: es una elección de producto que define cuándo tiene sentido utilizar uno u otro.

Cuando ganan las funciones de páginas

El caso más sólido para Pages Functions es la coubicación: frontend y backend en el mismo repositorio, con el mismo ciclo de implementación. Un proyecto Next.js, Astro o SvelteKit con rutas API se ubica naturalmente en el mismo lugar: cambia un componente y la ruta API que consume en la misma confirmación, la misma solicitud de extracción y la misma implementación de vista previa.

Esta vista previa por sucursal es el diferenciador operativo más concreto. Cada envío a cualquier rama genera una URL de vista previa con el formato hash-nome-da-branch.seuproject.pages.dev, donde se ejecutan tanto los activos estáticos como las funciones. Esto significa que el revisor de relaciones públicas puede probar la función completa (interfaz y API) sin implementarla en ningún entorno independiente. Los trabajadores puros no tienen este flujo de forma nativa.

Si el enrutamiento de su API se asigna naturalmente a rutas URL y no necesita una lógica de enrutamiento compleja fuera de la estructura del directorio, las funciones de Pages eliminan la necesidad de un trabajador independiente con sus propias rutas configuradas en wrangler.toml.

La estructura del directorio y el patrón de middleware.

Una estructura de proyecto realista de Páginas con Funciones:

/functions
  _middleware.ts          ← executa antes de toda Function no diretório
  /api
    _middleware.ts        ← executa antes de toda Function em /api
    users/
      [id].ts             ← GET /api/users/:id, PUT /api/users/:id
      index.ts            ← GET /api/users, POST /api/users
    webhooks/
      stripe.ts           ← POST /api/webhooks/stripe

El archivo _middleware.ts es un mecanismo de composición que mucha gente ignora. Recibe la solicitud antes de que se ejecute la función específica de la ruta y puede cortocircuitarla con su propia respuesta o pasarla al siguiente controlador a través de ctx.next(). Esto es para autenticación, registro centralizado y CORS sin repetir la lógica en cada función:

// /functions/api/_middleware.ts
export async function onRequest(ctx: EventContext<Env, any, any>) {
  const token = ctx.request.headers.get("Authorization");
  if (!token || !isValidToken(token, ctx.env.JWT_SECRET)) {
    return new Response("Unauthorized", { status: 401 });
  }
  const response = await ctx.next();
  response.headers.set("X-Content-Type-Options", "nosniff");
  return response;
}

El middleware en la raíz /functions cubre todas las funciones. El middleware en /functions/api solo cubre rutas API. Puede apilar los dos: el que está en el directorio principal se ejecuta primero.

Cuando los trabajadores puros son la elección correcta

Las funciones de páginas no admiten activadores cron. Si necesita un trabajo que se ejecute a las 3 a. m. para procesar la facturación, sincronizar una fuente externa o limpiar sesiones caducadas, debe ser un trabajador independiente con [triggers] crons en wrangler.toml. No hay alternativa dentro del modelo de Pages.

Los consumidores de colas (trabajadores que procesan mensajes de colas de Cloudflare de forma asincrónica) tampoco existen en Pages. Si su arquitectura utiliza colas para desacoplar el procesamiento pesado de la ruta crítica de la solicitud, el consumidor debe ser un trabajador independiente.

Workers for Platforms, el mecanismo de envío de scripts implementados por el usuario (en el caso de SaaS multiinquilino donde cada cliente tiene su propio código), es exclusivo de Workers. Trabajadores de correo electrónico, que reciben y procesan correos electrónicos entrantes, lo mismo.

La regla general: si el desencadenante no es una solicitud HTTP, es un trabajador puro. Las funciones de las páginas son exclusivamente HTTP.

Compartir código entre funciones y trabajadores de páginas independientes

Una arquitectura común utiliza ambos: el proyecto Pages para la interfaz y la API principal en /functions, además de trabajadores separados para trabajos en segundo plano. El problema es que es posible que sea necesario compartir el código comercial: validación de datos, acceso a la base de datos D1, lógica de autorización.

La solución son paquetes npm internos (que utilizan espacios de trabajo npm/pnpm) o un trabajador dedicado como una "capa de servicio" al que otros acceden a través de Service Binding. El enlace de servicio permite que una función de páginas llame a un trabajador directamente, en la misma red interna de Cloudflare, sin costo de red y sin pasar por la Internet pública:

// /functions/api/orders/index.ts
export async function onRequestPost(ctx: EventContext<Env, any, any>) {
  // Chama o Worker de processamento via Service Binding
  const result = await ctx.env.ORDER_PROCESSOR.fetch(
    new Request("https://internal/process", {
      method: "POST",
      body: ctx.request.body,
    })
  );
  return result;
}

El ORDER_PROCESSOR aquí es un trabajador independiente que tiene acceso a colas, crons y cualquier otra primitiva que las funciones de páginas no admitan. Las funciones de las páginas están en la capa HTTP; Los trabajadores autónomos se sientan en disparadores asincrónicos. Los dos comparten enlaces D1 y KV que apuntan a los mismos recursos.

Los criterios de decisión

Si está creando un proyecto con una interfaz (cualquier cosa que genere activos estáticos en el momento de la construcción), comience con Pages. Las funciones que agrega en /functions tienen exactamente el mismo poder que un trabajador independiente para casos HTTP. Obtiene una vista previa de la sucursal y un proceso de compilación integrado sin pagar ningún costo operativo adicional.

Si está creando un servicio sin interfaz, con desencadenadores que no son HTTP o que requiere entornos con nombre con diferentes enlaces para la preparación y la producción, Workers es la ruta más directa. La configuración explícita en wrangler.toml es más auditable y el modelo de implementación es más flexible para servicios de backend puros.

Los dos no son mutuamente excluyentes. La mayoría de los proyectos serios terminan con ambos: páginas para lo que es HTTP y están ubicadas junto con la interfaz, trabajadores para lo que es asíncrono o programado.