¿Falló el build de CF Pages? 8 problemas comunes y soluciones para ahorrarte medio día de depuración

El log de build de Cloudflare Pages muestra un rojo «Failed». Quinto fallo esta noche; mañana por la mañana tengo que enseñar el proyecto a un cliente. Quinientas líneas de log, npm ERR! por todas partes, sin saber por dónde empezar. Probé soluciones de internet: algunas no sirvieron, otras empeoraron las cosas.

La mayoría de fallos de build en CF Pages encajan en tres categorías: diferencias de entorno, configuración de dependencias y compatibilidad de versiones. Con ese patrón claro, el 90 % de los problemas se resuelve en 10 minutos. Este artículo describe el entorno de build de Cloudflare Pages, recopila 8 escenarios de fallo muy frecuentes (cada uno con errores reales y pasos completos de solución) y añade recomendaciones preventivas. Al terminar tendrás un enfoque de diagnóstico claro.

Parte 1: Entender el entorno de build de Cloudflare Pages

La particularidad del entorno de build de Pages

Antes de depurar casos concretos, conviene entender una cosa: el entorno de build de Cloudflare Pages no es el mismo que tu entorno local. Muchas veces el error no es tu código, sino la diferencia de entorno.

La configuración por defecto es esta:

• Sistema operativo: Ubuntu (Build System V2 usa Ubuntu 22)
• Versión de Node: 18.17.1 (sí, bastante antigua)
• Gestor de paquetes: usa npm clean-install por defecto, no npm install
• Timeout de build: límite fijo de 20 minutos
• Tamaño de Worker: tope de 10 MB

Puede que te preguntes por qué la versión de Node es tan antigua. Cloudflare lo hace por estabilidad. Pero muchos paquetes nuevos ya exigen Node >= 18.18.0 o >= 20.0.0, lo que provoca conflictos de versión.

Tres diferencias clave con el entorno local:

1. Sensibilidad a mayúsculas en el sistema de archivos: en Windows o Mac puedes escribir import Header from './header' aunque el archivo sea Header.js. En Linux no: debe coincidir exactamente. Es la trampa más fácil de pasar por alto.

2. Diferencias de red: en local quizá uses un mirror de npm (por ejemplo Taobao), pero Pages se conecta directamente al registro oficial y a veces hay timeouts.

3. Diferencia en el comando de build por defecto: Cloudflare ejecuta npm clean-install --progress=false antes de tu build command. Es mucho más estricto que npm install: si package-lock.json y package.json no coinciden, falla.

Método rápido para localizar el problema

Ya sabes que el entorno es distinto. Cuando falle el despliegue en Pages, ¿cómo encontrar la causa real?

Paso 1: leer el log de build

El log puede tener cientos de líneas, pero solo necesitas fijarte en unos puntos:

# Busca el último ERR! o ERROR
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
# O errores de Vite/Webpack
[vite]: Rollup failed to resolve import
# Y errores de Git
fatal: unable to access repository

Mi experiencia: busca «ERR!» (con el signo de exclamación) y mira 3-5 líneas hacia arriba; ahí suele estar la causa. No te distraigas con la salida de instalación anterior.

Paso 2: guardar el Deployment ID

Cada build fallido genera un Deployment ID único, visible en la barra de direcciones:

https://dash.cloudflare.com/xxx/pages/view/your-project/a398d794-7322-4c97-96d9-40b5140a8d9b
                                                          ↑ Este es el Deployment ID

Guardar este ID es muy importante. Si contactas con soporte o pides ayuda en la comunidad, con ese ID pueden localizar tu registro de build.

Paso 3: reproducir en local

Mucha gente omite este paso. Intenta reproducir en un entorno Linux:

# Método 1: simular Ubuntu 22 con Docker
docker run -it ubuntu:22.04 bash
# Método 2: usar npm ci estrictamente (igual que Pages)
npm ci
# Método 3: fijar la versión de Node (con nvm)
nvm use 18.17.1

Si npm ci falla en local, el problema está en las dependencias. Si al cambiar a Node 18.17.1 explota, es compatibilidad de versión.

Parte 2: 8 escenarios frecuentes de fallo de build y sus soluciones

Problema 1: fallo de instalación de dependencias (error de npm install)

Mensajes de error típicos:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! Fix the upstream dependency conflict, or retry this command
npm ERR! with --force or --legacy-peer-deps
O bien
npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network Socket timeout

Es el que más me ha tocado: npm install funciona en local y en Pages sale ERESOLVE. La razón es simple: Cloudflare usa npm ci por defecto, un comando muy estricto.

Causas:

1. npm clean-install no resuelve conflictos de peer dependency automáticamente
2. package-lock.json y package.json desincronizados
3. Timeout de red (sin acceso al registro oficial de npm)

Soluciones (por orden de recomendación):

Opción 1: omitir la instalación por defecto y personalizar el comando

# Añade en la configuración de Pages
SKIP_DEPENDENCY_INSTALL=true
# Y cambia el Build command a
npm install --legacy-peer-deps && npm run build

Es la opción más directa: le dices a Cloudflare que no use su comando por defecto y gestionas tú la instalación.

Opción 2: reparar package-lock.json

# Regenera el lock en local
rm package-lock.json
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"
git push

A veces el lock simplemente está corrupto y regenerarlo basta.

Opción 3: delegar el build a GitHub Actions

Si las dos anteriores no funcionan, el problema es más complejo. Puedes usar GitHub Actions + cloudflare/pages-action y controlar por completo el entorno:

# .github/workflows/deploy.yml
- name: Install dependencies
  run: npm install --force
- name: Build
  run: npm run build
- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1

Prevención: ejecuta npm ci en local con regularidad para asegurar que el lock está sincronizado.

Problema 2: incompatibilidad de versión de Node

Mensajes de error típicos:

ERR_PNPM_UNSUPPORTED_ENGINE Unsupported environment
This package requires Node.js version ^18.18.0 or >=20.0.0
O bien
The engine "node" is incompatible with this module.
Expected version ">=18.18.0". Got "18.17.1"

Con estos errores, casi seguro la versión de Node es demasiado antigua. Muchos paquetes (TypeScript ESLint, Next.js 14+) exigen Node >= 18.18.0, pero Pages usa 18.17.1 por defecto.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Soluciones (elige una):

Opción 1: variable de entorno (más recomendada)

En Cloudflare Pages, Settings > Environment variables:

Nombre: NODE_VERSION
Valor: 20.11.0

Es la forma oficial, simple y directa.

Opción 2: archivo .node-version

Crea .node-version en la raíz del proyecto:

echo "20.11.0" > .node-version
git add .node-version
git commit -m "chore: specify Node version for Cloudflare Pages"

Opción 3: archivo .nvmrc

Igual que arriba, otro nombre:

echo "20.11.0" > .nvmrc

Buena práctica: usa variable de entorno y .node-version a la vez para alinear local y producción. No elijas la última versión; mejor una LTS estable (por ejemplo 20.11.0).

Problema 3: timeout de build (más de 20 minutos)

Síntoma típico:

El log muestra exactamente 20 minutos y termina de repente, sin error claro. Solo una línea:

Build exceeded maximum time of 20 minutes

Es frustrante: casi sin información. Suele pasar en proyectos grandes o con muchas dependencias.

Causas:

• Demasiadas dependencias; npm install solo tarda 15 minutos
• Scripts de build con operaciones repetidas (regenerar todo el sitio cada vez)
• No aprovechar la caché de build

Soluciones:

Opción 1: limpiar la caché de build

A veces la caché empeora las cosas. En Pages:

Settings > Builds & deployments > Clear build cache

Vuelve a construir; a mí me ha funcionado varias veces.

Opción 2: analizar y optimizar dependencias

Usa un bundle analyzer:

# Proyecto Next.js
npm install --save-dev @next/bundle-analyzer
# Luego en next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer({
  // tu configuración
})

Ejecuta ANALYZE=true npm run build y mira qué paquetes pesan. En un proyecto importé moment.js entero; al cambiar a day.js el build bajó 3 minutos.

Opción 3: mover tareas parciales al CI

Deja typecheck y lint en GitHub Actions; Pages solo construye:

// package.json
{
  "scripts": {
    "build": "next build",
    "build:full": "npm run typecheck && npm run lint && npm run build"
  }
}

Opción 4: usar pnpm

pnpm instala dependencias mucho más rápido. En Pages:

Build command: pnpm install && pnpm run build

Problema 4: error de resolución de módulos (Module not found)

Mensajes de error típicos:

Module not found: Error: Can't resolve './App' in '/opt/buildhome/repo/src'
Did you mean 'App.js'?
O bien
[vite]: Rollup failed to resolve import '/src/components/Snackbar'
from '/opt/buildhome/repo/src/pages/Login.jsx'

Este error es muy sigiloso: en local va bien y en Pages no encuentra el módulo. El 99 % son problemas de mayúsculas.

Causa:

Linux distingue mayúsculas; Windows y macOS no. Escribes import App from './app' con archivo App.js: en Windows funciona, en Linux no.

Soluciones:

Opción 1: corregir todas las rutas de importación

Es la solución de raíz. Revisa cada import y asegura que coincida el case:

// ❌ Incorrecto
import Header from './header';  // pero el archivo es Header.jsx
// ✅ Correcto
import Header from './Header';

Revisar a mano cansa. Regla ESLint recomendada:

// .eslintrc.js
module.exports = {
  rules: {
    'import/no-unresolved': 'error',
  }
}

Opción 2: alias de rutas

Rutas absolutas o alias evitan muchos problemas:

// vite.config.js
export default {
  resolve: {
    alias: {
      '@': '/src',
      '@components': '/src/components'
    }
  }
}
// Import con alias
import Header from '@components/Header';

Opción 3: truco raro de la comunidad

Un usuario reportó algo absurdo pero efectivo: renombra la carpeta, haz commit, vuelve a renombrar y commit otra vez. No sé por qué funciona; quizá caché. Si nada más sirve, pruébalo.

Problema 5: error de configuración de variables de entorno

Síntoma típico:

console.log(process.env.API_KEY); // undefined

O el build falla porque falta una variable.

Causas:

Mucha gente mezcla variables de build y de runtime. Además, cada framework exige convenciones distintas.

Concepto clave:

Cloudflare Pages tiene dos tipos:

1. Variables de build: disponibles en npm run build, se compilan en el código
2. Variables de runtime: solo en Functions (edge)

En un sitio estático (HTML/JS puro) no puedes usar variables de runtime; solo las de build.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Soluciones:

Opción 1: configurar el tipo correcto

Al añadir variables en Pages, marca:

• «Production» y «Preview» según el entorno
• «Build» si la variable se necesita en compilación

Opción 2: seguir la convención del framework

# Vite: prefijo VITE_
VITE_API_KEY=xxx
# Next.js (públicas): prefijo NEXT_PUBLIC_
NEXT_PUBLIC_API_KEY=xxx
# Nuxt: runtimeConfig en nuxt.config.js

Opción 3: secretos sensibles

En Pages hay dos tipos:

• Text: valor visible
• Secret: valor oculto, almacenado cifrado

API keys y contraseñas de base de datos deben ser Secret.

Buena práctica:

1. En local usa .env.local (añádelo a .gitignore)
2. En producción, variables en Cloudflare Pages
3. Valores distintos por entorno (Preview con API de prueba, Production con API real)

Problema 6: problemas de integración Git

Síntomas típicos:

• No se puede autorizar el acceso al repositorio
• Error: «This repository is already in use by another Pages project»
• Tras un push, Pages no construye automáticamente

Causas:

Suele ser autorización de GitHub/GitLab rota o límite de Cloudflare (un repo no puede usarse en varias cuentas).

Soluciones:

Opción 1: reautorizar la GitHub App

En GitHub:

Settings > Applications > Cloudflare Pages > Configure > Uninstall

Desinstala, vuelve al Dashboard de Cloudflare y reconecta el repo para reautorizar.

Opción 2: revisar uso del repositorio

Si dice que el repo ya está en uso, comprueba si lo usas en varias cuentas de Cloudflare. No está permitido; elimina el proyecto Pages en las otras cuentas.

Opción 3: permisos de usuario en GitHub

Necesitas al menos rol Maintainer en el repo. Con Contributor no puedes conectar.

Opción 4: evitar caracteres especiales

Trampa: no uses emoji ni caracteres raros en el commit message; puede impedir que se dispare el build. GitHub lo permite; Cloudflare no siempre lo parsea bien.

Limitación conocida: los PR de repos fork no disparan despliegue de preview. Cloudflare dice que lo soportará más adelante; hoy no.

Problema 7: fallo de despliegue de Functions

Síntomas típicos:

El build parece OK pero falla al desplegar, con log poco útil. O:

Build failed: Functions bundle size exceeding limit

Causas:

• Bundle de Worker > 10 MB
• Bindings de Functions (KV, D1, R2) mal configurados
• APIs exclusivas de Node.js no soportadas en el edge

Soluciones:

Opción 1: analizar el tamaño del bundle de Functions

npm install --save-dev @next/bundle-analyzer

Suele ser falta de tree-shaking: se empaqueta la librería entera.

Opción 2: optimizar el adaptador Astro/SvelteKit

Si usas Astro o SvelteKit, configura bien el adaptador de Cloudflare:

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'hybrid',
  adapter: cloudflare({
    mode: 'directory',
  }),
};

Astro empaqueta páginas prerenderizadas en Functions por defecto y el volumen explota. mode: 'directory' lo corrige.

Opción 3: revisar Bindings

En Pages:

Settings > Functions > Bindings

KV, D1 y R2 usados en código deben estar configurados.

Opción 4: evitar APIs exclusivas de Node.js

Cloudflare Workers es V8, no Node.js completo. No disponibles:

• fs (sistema de archivos)
• path (parcialmente)
• child_process
• net / http (usa fetch)

Si las necesitas, muévelas al build.

Problema 8: caché y dominio personalizado

Síntomas típicos:

• Despliegue OK pero el sitio muestra contenido antiguo
• Dominio personalizado da 404 pero .pages.dev funciona
• La home muestra 404 Not Found

Causas:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

• Page Rules de Cloudflare interfieren con la caché de Pages
• DNS del dominio personalizado mal configurado
• Falta index.html

Soluciones:

Opción 1: quitar Page Rule «Cache Everything»

Si el dominio personalizado está Proxied (nube naranja), la zona afecta a Pages. Revisa:

Rules > Page Rules

Si hay «Cache Everything», elimínala. Pages tiene su propia caché.

Opción 2: dominio personalizado en DNS Only

Si lo anterior no sirve, prueba nube gris (DNS Only):

DNS > Records > tu registro > DNS Only

Así no pasa por el proxy de Cloudflare y apunta directo a Pages.

Opción 3: asegurar que existe index.html

Si la raíz (yourdomain.com/) da 404, comprueba que el directorio de salida tenga index.html. Muchos frameworks generan dist/index.html; verifica «Build output directory» en Pages.

Opción 4: purgar caché manualmente

Si la caché impide ver contenido nuevo:

Caching > Configuration > Purge Everything

Purga toda la zona; úsalo con cuidado.

Parte 3: Buenas prácticas preventivas

Mejores prácticas de configuración de build

Mejor configurar bien desde el inicio que arreglar después:

1. Especificar la versión de Node explícitamente

No confíes en la versión por defecto:

# archivo .node-version
20.11.0
# y en variables de entorno de Cloudflare Pages
NODE_VERSION=20.11.0

2. Comandos de build distintos por rama

Usa la variable CF_PAGES_BRANCH:

// package.json
{
  "scripts": {
    "build": "node scripts/build.js",
    "build:production": "next build",
    "build:preview": "next build && next export"
  }
}

// scripts/build.js
const branch = process.env.CF_PAGES_BRANCH || 'main';
const command = branch === 'main' ? 'build:production' : 'build:preview';
// ejecuta el comando correspondiente

3. En monorepos, fijar el directorio raíz correcto

Con pnpm workspace o Turborepo, en Pages:

Root directory: apps/web
Build command: pnpm run build

Monitorización continua y trucos de depuración

1. Entorno local de depuración

Simula el entorno de Pages con Docker:

# Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y nodejs npm
RUN node -v
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

2. Consultar Cloudflare Status

A veces el fallo es del servicio. Ante errores raros:

https://www.cloudflarestatus.com/

Si Pages tiene incidencias, espera; no pierdas tiempo depurando tu código.

3. Cuándo contactar con Cloudflare Support

Si:

• Probaste todo y nada funciona
• Sospechas un bug de la plataforma
• Necesitas subir límites de build (planes de pago pueden solicitarlo)

Contacta soporte. Lleva Deployment ID y log de error detallado.

Conclusión

En resumen, los fallos de build en CF Pages son de pocas categorías. En el 90 % de los casos: diferencias de entorno (Node, mayúsculas), configuración de dependencias (package-lock.json, peer dependency) o malentendido de cómo funciona Pages (variables de entorno, caché).

Un enfoque sistemático ayuda:

1. Lee el log y encuentra el error real
2. Clasifica el problema (dependencias, versión, rutas, configuración)
3. Reproduce en local
4. Aplica la solución correspondiente
5. Configura medidas preventivas para no repetir el error

Guarda este artículo como manual de incidencias. La próxima vez que falle un build, sigue este flujo: lo más probable es resolverlo en 10 minutos. Cuando veas el verde «✓ Deployed», el alivio no tiene precio.

¿Otros problemas con Cloudflare Pages? Compártelos en los comentarios; puede ayudar a más gente.