¿Qué hace Publicar Sitio Estático?
Objetivo
Publicar o preparar el despliegue de un sitio web estático terminado.
Esta habilidad es para el resultado HTML/CSS/JS desplegable, como site/, dist/, out/, public/ o docs/. También puede publicar proyectos de frameworks después de que produzcan una carpeta de salida estática, pero no debe convertir un sitio estático simple en un proyecto de framework solo para desplegarlo.
Postura predeterminada:
- Preferir alojamiento estático simple sobre despliegues específicos de frameworks.
- Preferir despliegue basado en Git para sitios que el usuario seguirá editando.
- Preferir carga directa solo para publicaciones rápidas y únicas.
- No crear repositorios remotos, enviar código, cambiar DNS, agregar dominios ni desplegar en una cuenta de pago a menos que el usuario lo solicite explícitamente.
Contrato
Entradas:
- Raíz de despliegue estático, como
site/,dist/,out/,public/,docs/o la raíz del repositorio. - Plataforma o destino preferido: GitHub Pages, Cloudflare Pages, Netlify, Vercel, dominio personalizado, solo orientación o despliegue en vivo.
- Estado actual de Git/repositorio, acceso a la cuenta de la plataforma, inicio de sesión CLI/navegador y cualquier restricción de despliegue.
Salidas:
- Configuración de despliegue concreta: plataforma, rama, comando de compilación, directorio base, directorio de publicación/salida y archivos de configuración cuando sea necesario.
- Configuración opcional específica de la plataforma, como flujo de trabajo de GitHub Pages,
netlify.toml,vercel.json,.nojekylloCNAME. - URL en vivo y verificación posterior al despliegue cuando el despliegue se realiza realmente.
- Pasos manuales del panel de control cuando no están disponibles las credenciales o el acceso a la cuenta.
Límites:
- No construir ni rediseñar el sitio; derivar los defectos a la habilidad secundaria adecuada.
- No enviar, crear repositorios/proyectos, cargar, vincular dominios, cambiar DNS ni usar recursos de pago a menos que esté expresamente autorizado.
- No usar el despliegue como solución para problemas de compatibilidad local/estática a menos que el usuario acepte explícitamente un comportamiento solo de raíz de servidor.
Puerta de éxito:
review-static-siteha pasado o los riesgos no resueltos son explícitos.- La raíz de despliegue contiene
index.htmly la plataforma publicará la carpeta correcta. - La URL en línea carga la página de inicio, los activos, la navegación y las subpáginas representativas después del despliegue.
Si la puerta falla:
- Corregir los bloqueadores de ruta, activo, codificación o tipo de página antes del despliegue.
- Derivar los problemas de contenido/diseño/importación a
personalize-site,edit-site-part,add-blog-posts,make-personal-siteocopy-website-style. - Volver a ejecutar
review-static-sitey luego reintentar o actualizar la configuración de despliegue.
Referencias
Cargue solo la referencia necesaria para la plataforma o problema elegido:
- Estrategia de ruta y compatibilidad de apertura directa:
references/path-strategy.md. - Integración Git de Cloudflare Pages y Carga Directa:
references/cloudflare-pages.md. - Fuente de rama de GitHub Pages y flujos de trabajo de Actions:
references/github-pages.md. - Panel de Netlify y
netlify.toml:references/netlify.md. - Panel de Vercel y
vercel.json:references/vercel.md.
Documentación oficial:
- Fuente de publicación de GitHub Pages: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- Flujos de trabajo personalizados de GitHub Pages: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- HTML estático de Cloudflare Pages: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Integración Git de Cloudflare Pages: https://developers.cloudflare.com/pages/get-started/git-integration/
- Carga Directa de Cloudflare Pages: https://developers.cloudflare.com/pages/get-started/direct-upload/
- Crear despliegues de Netlify: https://docs.netlify.com/deploy/create-deploys/
- Configuración de compilación de Netlify: https://docs.netlify.com/build/configure-builds/overview/
- Despliegues de Vercel: https://vercel.com/docs/deployments
- Configuración de proyectos de Vercel: https://vercel.com/docs/project-configuration
Modos de Despliegue
Primero determine lo que el usuario realmente quiere:
- Solo orientación: explicar la elección de la plataforma y la configuración exacta. No editar archivos a menos que sea útil.
- Preparar repositorio: agregar los archivos de configuración necesarios y decirle al usuario qué hacer clic en el panel de alojamiento.
- Desplegar ahora: realizar acciones remotas solo si el usuario lo solicitó explícitamente y existe la CLI/auth/sesión requerida.
- Verificar URL en vivo: abrir la URL desplegada en un navegador y compararla con el sitio local.
Si faltan credenciales, acceso a la cuenta, inicio de sesión del navegador o autenticación CLI, proporcione los pasos exactos del panel en lugar de inventar una solución alternativa.
Flujo de Trabajo
- Identificar la carpeta de salida estática y la plataforma preferida del usuario, si la hay.
- Llamar o sugerir usar
review-static-siteantes de publicar. - Confirmar que la raíz de despliegue contiene
index.html. - Inspeccionar las rutas de los activos y convertir las rutas absolutas de raíz accidentales a rutas locales del sitio antes de publicar. Cargar
references/path-strategy.mdcuando el comportamiento de la ruta no esté claro. - Elegir la plataforma y el modo de despliegue más simples.
- Cargar la referencia de la plataforma elegida y agregar solo los archivos de configuración requeridos por esa plataforma.
- Si se despliega a través de Git, verificar el estado de Git y evitar incluir archivos no relacionados o privados.
- Si el usuario autorizó acciones remotas, enviar o desplegar exactamente lo acordado.
- Después de publicar, abrir la URL en vivo y verificar el sitio desplegado en un navegador.
Lista de Verificación Previa al Vuelo
Realizar estas comprobaciones antes de escribir configuraciones de despliegue o decirle al usuario la configuración:
- Raíz de despliegue: elegir la carpeta que contiene directamente
index.html. - Página de entrada:
index.htmldebe existir en el nivel superior de la raíz de despliegue. - Vista previa de apertura directa: el
index.htmlraíz debe mantener CSS, JS, imágenes y navegación cuando se abre directamente desde el sistema de archivos, a menos que el usuario acepte explícitamente un comportamiento solo de servidor. - HTTP local: servir la raíz de despliegue con
python -m http.servery confirmar que funciona a través dehttp://127.0.0.1:<porto>/. - Auditoría estática: ejecutar o recomendar
review-static-sitepara enlaces, legibilidad UTF-8, residuos de marcadores de posición, renderizado del navegador, residuos de privacidad y diseño móvil. - Rutas de activos: inspeccionar
href,src,srcset, CSSurl(...), fuentes, favicons, imágenes de portada, RSS, sitemap y enlaces de manifiesto. - Datos privados: asegurarse de que los tokens, las rutas del sistema de archivos local, las notas borrador, las identidades del sitio de origen y los secretos personales no se estén publicando.
- Integridad de la salida: confirmar que las subpáginas, publicaciones, imágenes, fuentes de proveedores, activos KaTeX/matemáticos y medios copiados estén dentro de la raíz de despliegue.
Tratar estos como bloqueadores:
- No hay
index.htmlen la raíz de despliegue. - Rutas de activos CSS, JS, imagen, fuente, RSS, sitemap o proveedor rotas localmente.
- Los archivos fuente contienen mojibake o codificación ilegible.
- El sitio personal generado aún contiene la identidad copiada de la fuente que debería haber sido reemplazada.
- Rutas accidentales absolutas de raíz locales del sitio como
/assets/...,/posts/...,/data/...o/images/...permanecen en un sitio estático plano generado. - El sitio funciona solo a través de HTTP local porque las rutas absolutas de raíz se sirven desde
127.0.0.1, pero la apertura directa de archivos o el despliegue en subruta perdería CSS/JS/imágenes. - Se desplegarían archivos sensibles a la privacidad o secretos.
- La plataforma desplegaría la carpeta incorrecta.
Elección de Plataforma
Usar esta clasificación predeterminada para sitios personales estáticos simples:
- Integración Git de Cloudflare Pages: mejor opción predeterminada para una carpeta
site/generada y actualizaciones futuras. - GitHub Pages con GitHub Actions: mejor cuando el usuario quiere todo dentro de GitHub.
- Netlify: alojamiento estático simple con vistas previas amigables y configuración del panel.
- Vercel: bueno cuando el usuario ya usa Vercel o puede migrar a Next.js más tarde, pero no es la opción predeterminada para HTML simple.
Reglas de decisión:
- Si el usuario quiere la menor fricción y tiene un repositorio de GitHub: Integración Git de Cloudflare Pages. Cargar
references/cloudflare-pages.md. - Si el usuario quiere alojamiento solo de GitHub: GitHub Pages. Cargar
references/github-pages.md. - Si los archivos de despliegue viven en la raíz del repositorio o en
/docs: la fuente de la rama de GitHub Pages es aceptable. - Si los archivos de despliegue viven en
site/,dist/,out/u otra carpeta personalizada: preferir GitHub Actions para GitHub Pages. - Si el usuario quiere carga manual hoy: Carga Directa de Cloudflare o despliegue manual de Netlify.
- Si el usuario ya tiene una cuenta/proyecto de Vercel: usar Vercel con ajustes explícitos del directorio de salida.
Salida Estática de Framework
Si el sitio no es HTML/CSS/JS simple:
- Inspeccionar
package.json, la configuración del framework y los scripts existentes. - Usar el comando de compilación existente del proyecto; no inventar flujos de trabajo npm.
- Publicar la carpeta de salida estática final, no la carpeta de origen.
- Las salidas comunes incluyen
dist,out,build,.output/publicypublic, dependiendo del framework. - Para la exportación estática de Next.js, verificar que el proyecto esté realmente configurado para exportación estática antes de tratar
out/como salida final. - Para proyectos Vue/Vite/Astro, publicar el directorio de salida configurado después de una compilación exitosa.
Si el usuario solicitó publicación estática simple y no existen archivos de framework, no introducir npm.
Política de Archivos de Configuración
Solo agregar archivos de configuración que coincidan con la plataforma elegida:
- Acciones de GitHub Pages:
.github/workflows/pages.yml. - Dominio personalizado de GitHub Pages:
CNAMEen la raíz desplegada, solo cuando el usuario proporcionó el dominio. - Bypass de Jekyll de GitHub Pages:
.nojekyllen la raíz desplegada cuando sea útil. - Netlify:
netlify.tomlsolo cuando la configuración del panel no sea suficiente o el usuario quiera la configuración en Git. - Vercel:
vercel.jsonsolo cuando Vercel necesite ajustes de salida explícitos. - Cloudflare Pages: normalmente la configuración del panel es suficiente para sitios estáticos simples.
No agregar configuraciones de despliegue para todas las plataformas a la vez.
Seguridad de Git y Remoto
Antes de cualquier acción remota, indicar lo que sucederá y confirmar que el usuario lo solicitó:
- Crear un repositorio de GitHub.
- Agregar un remoto.
- Preparar o confirmar archivos.
- Enviar commits a una rama remota.
- Habilitar GitHub Pages.
- Crear proyectos de Cloudflare, Netlify o Vercel.
- Cargar archivos a un proveedor de alojamiento.
- Agregar variables de entorno.
- Agregar dominios personalizados o cambiar registros DNS.
Antes de preparar o enviar:
- Ejecutar
git status --short. - Identificar archivos de sitio generados frente a cambios no relacionados del usuario.
- No preparar cambios no relacionados.
- No publicar notas privadas, credenciales, rutas locales, capturas de pantalla con secretos ni archivos temporales.
Nunca poner secretos, tokens, notas privadas o rutas del sistema de archivos local en el sitio estático o la configuración de despliegue.
Verificación Posterior al Despliegue
Después de que la plataforma informe una URL en vivo:
- Abrir la URL desplegada con una herramienta de navegador interactiva realmente disponible. "Disponible" significa que está expuesta en la lista de herramientas invocables del turno actual. En Codex, esto puede ser el complemento Browser/in-app browser cuando se enruta en el turno.
- Verificar que la página de inicio no sea un 404, una página en blanco o un listado de directorio.
- Verificar que CSS, JavaScript, imágenes, fuentes, favicon, RSS, sitemap y activos de proveedores se carguen desde el dominio desplegado.
- Hacer clic en la navegación principal y al menos una subpágina representativa por tipo de página.
- Probar anchos de escritorio y móvil.
- Revisar la consola del navegador en busca de activos faltantes o errores de JavaScript.
- Confirmar metadatos, título, descripción, imagen de Open Graph, URL canónica, RSS, sitemap y archivos robots cuando estén presentes.
- Si se usa GitHub Pages de proyecto, verificar específicamente las URLs de subpáginas y activos bajo la subruta del repositorio.
- Si se usa un dominio personalizado, verificar HTTPS y redirecciones entre apex y
wwwsi está configurado.
Si no es invocable ninguna herramienta de navegador interactiva, no fingir que se realizó la verificación del navegador en vivo. Preguntar al usuario que habilite o invoque la herramienta de navegador si la verificación visual en vivo es importante; para Codex, eso puede significar enviar una solicitud que mencione explícitamente @browser. Si el usuario no redirige o el cliente no tiene dicha herramienta, recurrir a Playwright, capturas de pantalla, comprobaciones HTTP o comprobaciones estáticas e indicar la limitación.
No predeterminar a Playwright o verificación en vivo solo con capturas de pantalla cuando una herramienta de navegador interactiva es realmente invocable. Usar Playwright solo como alternativa, o cuando el usuario solicite explícitamente comprobaciones de despliegue con script.
Si el sitio desplegado difiere de la vista previa local, inspeccionar el registro de despliegue, el directorio de salida y la estrategia de ruta de activos antes de cambiar el código de diseño.
Salida
Mantener conciso el informe final dirigido al usuario:
- Plataforma elegida y por qué.
- Carpeta estática publicada o preparada.
- Modo de despliegue: orientación, configuración preparada, integración Git, carga directa o despliegue en vivo.
- Configuración utilizada: rama, comando de compilación, directorio base, directorio de publicación/salida.
- Archivos de configuración modificados, si los hay.
- URL de la guía oficial de la plataforma elegida.
- URL en vivo, si se realizó el despliegue.
- Verificación realizada y cualquier paso manual restante.
Si solo se solicitó orientación, no fingir que el sitio fue desplegado. Proporcionar ajustes concretos de la plataforma y enlaces a la guía oficial.